feat(go): introduce standalone sample (#101)

> [!TIP]
> Better reviewed commit-by-commit.

# Description

Implements a standalone `go` sample.

- [x] Follow the [`CONTRIBUTING`
Guide](https://github.com/google-agentic-commerce/AP2?tab=contributing-ov-file#how-to-contribute).
- [x] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- [x] Ensure the tests and linter pass
- [x] Appropriate docs were updated (if necessary)

Closes #71  🦕

Author: stefanoamorelli

.cspell.json

@@ -8,7 +8,8 @@
     ".cspell/**",
     ".gemini/**",
     ".vscode/**",
-    ".cspell.json"
+    ".cspell.json",
+    "**/go.sum"
   ],
   "dictionaryDefinitions": [
     {

.cspell/custom-words.txt

@@ -11,21 +11,25 @@ androidx
 Applebot
 appname
 ASGI
+bazel
 Blackhawk
 Boku
 BVNK
+celerybeat
 classpath
 CLASSPATH
 CMSPI
 cmwallet
 Cobo
 contentnegotiation
+Connor
 credman
 Crossmint
 cryptographical
 CYGPATTERN
 Dafiti
 dcql
+dmypy
 Dcql
 DCQL
 deviceauth
@@ -47,15 +51,20 @@ Garena
 gemini
 genai
 generativeai
+gofmt
 gradlew
+gradletasknamecache
 Gravitee
 gson
+hprof
+htmlcov
 Hashkey
 icns
 imei
 Imtp
 inlinehilite
 inmemory
+ipynb
 issuerauth
 JAVACMD
 jetbrains
@@ -72,6 +81,7 @@ ktor
 Ktor
 KXMYBJWNQ
 Lazada
+libpeerconnection
 Lightspark
 linenums
 llms
@@ -86,6 +96,7 @@ MSYS
 multistep
 Mysten
 Nuvei
+nosetests
 octicons
 okhttp
 Otherville
@@ -100,6 +111,9 @@ pids
 proguard
 Proguard
 pymdownx
+pyflow
+pypa
+pypackages
 reemademo
 refundability
 renamesourcefileattribute
@@ -108,6 +122,7 @@ repudiable
 Revolut
 Riskified
 ROOTDIRS
+ropeproject
 ROOTDIRSRAW
 Rulebook
 screenreaders
@@ -119,6 +134,9 @@ sideloaded
 Signifyd
 skus
 Splitit
+Spyder
+spyderproject
+spyproject
 stablecoins
 superfences
 Truelayer
@@ -127,6 +145,7 @@ viewmodel
 vulnz
 Wallex
 Wayfair
+webassets
 Worldline
 Worldpay
 Xdock
@@ -135,3 +154,28 @@ XVCJ
 Yapily
 Zalopay
 Zalora
+cncf
+davecgh
+envoyproxy
+felixge
+genproto
+glog
+gopkg
+groupcache
+honnef
+httpsnoop
+logr
+longrunning
+objx
+opentelemetry
+otelgrpc
+otelhttp
+pmezard
+prometheus
+protoc
+RPCURL
+stdr
+stretchr
+udpa
+unmarshal
+xerrors

.github/workflows/linter.yaml

@@ -41,3 +41,5 @@ jobs:
           VALIDATE_GITHUB_ACTIONS_ZIZMOR: false
           VALIDATE_JSCPD: false
           VALIDATE_SHELL_SHFMT: false
+          VALIDATE_GO: false
+          VALIDATE_GO_MODULES: false

.gitignore

@@ -8,6 +8,9 @@ __pycache__/
 /out-tsc
 /bazel-out
 
+# Go binaries
+bin/
+
 # C extensions
 *.so
 
@@ -193,7 +196,7 @@ gradle-app.setting
 # Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
 !gradle-wrapper.jar
 
-# Avoid ignore Gradle wrappper properties
+# Avoid ignore Gradle wrapper properties
 !gradle-wrapper.properties
 
 # Cache of project

samples/go/.gitignore

@@ -0,0 +1,26 @@
+# Binaries
+bin/
+*.exe
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool
+*.out
+
+# Go workspace file
+go.work
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

samples/go/Makefile

@@ -0,0 +1,76 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+.PHONY: all build clean test run-merchant run-credentials run-processor run-all help fmt lint
+
+all: fmt lint build
+
+build:
+	@echo "Building all agents..."
+	@mkdir -p bin
+	@go build -o bin/merchant_agent ./cmd/merchant_agent
+	@go build -o bin/credentials_provider_agent ./cmd/credentials_provider_agent
+	@go build -o bin/merchant_payment_processor_agent ./cmd/merchant_payment_processor_agent
+	@echo "Build complete!"
+
+clean:
+	@echo "Cleaning build artifacts..."
+	@rm -rf bin
+	@echo "Clean complete!"
+
+test:
+	@echo "Running tests..."
+	@go test ./...
+
+fmt:
+	@echo "Formatting code..."
+	@go fmt ./...
+
+lint:
+	@echo "Running linter..."
+	@go vet ./...
+
+run-merchant:
+	@echo "Starting Merchant Agent on port 8001..."
+	@go run ./cmd/merchant_agent
+
+run-credentials:
+	@echo "Starting Credentials Provider Agent on port 8002..."
+	@go run ./cmd/credentials_provider_agent
+
+run-processor:
+	@echo "Starting Merchant Payment Processor Agent on port 8003..."
+	@go run ./cmd/merchant_payment_processor_agent
+
+run-all:
+	@echo "Starting all agents..."
+	@bash scenarios/a2a/human-present/cards/run.sh
+
+deps:
+	@echo "Downloading dependencies..."
+	@go mod download
+	@go mod tidy
+
+help:
+	@echo "Available targets:"
+	@echo "  make build         - Build all agent binaries"
+	@echo "  make clean         - Remove build artifacts"
+	@echo "  make test          - Run tests"
+	@echo "  make fmt           - Format code"
+	@echo "  make lint          - Run linter"
+	@echo "  make deps          - Download and tidy dependencies"
+	@echo "  make run-merchant  - Run merchant agent"
+	@echo "  make run-credentials - Run credentials provider agent"
+	@echo "  make run-processor - Run payment processor agent"
+	@echo "  make run-all       - Run all agents (background)"

samples/go/README.md

@@ -0,0 +1,56 @@
+# Go Samples for the Agent Payments Protocol AP2
+
+This directory contains Go samples demonstrating how to build AP2
+agents.
+
+## Available Scenarios
+
+Currently, one scenario is available:
+
+- **[Human-Present Card Payment](./scenarios/a2a/human-present/cards/README.md)**
+    - Complete card payment flow with Go agents and Python Shopping
+      Agent
+
+See the [scenario README](./scenarios/a2a/human-present/cards/README.md) for
+detailed setup and usage instructions.
+
+## Why Go for Backend Agents?
+
+Go can be exceptionally well-suited for building AP2 backend services:
+
+- **Type Safety**: Compile-time validation of protocol structures
+- **Performance**: Fast response times and low resource usage
+- **Concurrency**: Efficient handling of concurrent requests
+- **Deployment**: Single binary with no runtime dependencies
+
+## Project Structure
+
+```text
+samples/go/
+├── cmd/                               # Agent entry points
+├── pkg/
+│   ├── ap2/types/                    # AP2 protocol types
+│   ├── common/                       # Shared infrastructure
+│   └── roles/                        # Agent implementations
+└── scenarios/                        # Runnable examples
+    └── a2a/
+        └── human-present/
+            └── cards/                # Card payment scenario
+```
+
+## Development
+
+```sh
+# Run tests
+make test
+
+# Format code
+make fmt
+
+# Build all agents
+make build
+```
+
+## License
+
+Copyright 2025 Google LLC. Licensed under the Apache License, Version 2.0.

samples/go/cmd/credentials_provider_agent/main.go

@@ -0,0 +1,42 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"log"
+
+	"github.com/google-agentic-commerce/ap2/samples/go/pkg/common"
+	"github.com/google-agentic-commerce/ap2/samples/go/pkg/roles/credentials_provider_agent"
+)
+
+const (
+	AgentPort = 8002
+	RPCURL    = "/a2a/credentials_provider"
+)
+
+func main() {
+	agentCard, err := common.LoadAgentCard("pkg/roles/credentials_provider_agent")
+	if err != nil {
+		log.Fatalf("Failed to load agent card: %v", err)
+	}
+
+	executor := credentials_provider_agent.NewCredentialsProviderExecutor(agentCard.Capabilities.Extensions)
+
+	server := common.NewAgentServer(AgentPort, agentCard, executor, RPCURL)
+
+	if err := server.Start(); err != nil {
+		log.Fatalf("Server error: %v", err)
+	}
+}