feat(go): introduce standalone sample #101

stefanoamorelli · 2025-10-26T18:24:22Z

Tip

Better reviewed commit-by-commit.

Description

Implements a standalone go sample.

Follow the CONTRIBUTING Guide.
Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
Ensure the tests and linter pass
Appropriate docs were updated (if necessary)

Closes #71 🦕

gemini-code-assist · 2025-10-26T18:24:47Z

Summary of Changes

Hello @stefanoamorelli, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request delivers a new, self-contained Go sample for the Agent Payments Protocol (AP2). It provides a practical demonstration of how different agents can collaborate to facilitate commerce transactions, covering the entire flow from product discovery to payment processing. The implementation emphasizes clear architecture, robust message handling, and the integration of advanced AI capabilities for tool selection, offering a valuable reference for developers looking to build agentic commerce solutions in Go.

Highlights

New Go Sample for AP2: Introduces a complete, standalone Go sample implementation of the Agent Payments Protocol (AP2), demonstrating agent-to-agent commerce transactions.
Three Agent Roles: The sample includes three distinct agents: a Merchant Agent (manages products/carts), a Credentials Provider Agent (handles payment credentials), and a Merchant Payment Processor Agent (processes payments).
LLM-Based Tool Routing: Features intelligent tool/function routing using Google Gemini 2.5 Flash, with a fallback to simple string matching if an API key is not provided.
Comprehensive Documentation and Build System: Includes a detailed README with setup instructions, project structure, key AP2 concepts, and testing guidance, alongside a Makefile for streamlined building, testing, and running of agents.
Core AP2 Type Definitions: Defines all core AP2 protocol types in Go, such as IntentMandate, CartMandate, PaymentMandate, ContactAddress, and W3C Payment Request objects, following idiomatic Go patterns.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a comprehensive standalone Go sample for the Agent Payments Protocol. The implementation is well-structured, covering multiple agent roles, common utilities, AP2 types, and supporting infrastructure like a Makefile and a detailed README. The code is clean, idiomatic, and demonstrates the protocol flow effectively.

My review includes a few suggestions for improvement, mainly focusing on enhancing robustness, code clarity, and adhering to Go best practices. These include safer type assertions, using the standard library for efficiency, and clarifying mock implementations. Overall, this is an excellent addition that will serve as a great reference for developers.

samples/go/pkg/common/function_resolver.go

samples/go/pkg/roles/merchant_agent/executor.go

samples/go/Makefile

samples/go/README.md

samples/go/cmd/merchant_agent/main.go

samples/go/pkg/common/function_resolver.go

samples/go/pkg/roles/merchant_agent/storage.go

joshlund-goog · 2025-10-27T20:10:02Z

Could you add a README that instructs the user:

how to run this sample
how to interact with this sample (I notice there is no shopping_agent implemented in go)
what the sample is demonstrating

An example may be found at samples/python/scenarios/a2a/human-present/cards/README.md.

- Add detailed scenario README at samples/go/scenarios/a2a/human-present/cards/README.md - Explains how to run the Go sample - Clarifies no shopping agent is included (backend only) - Documents what the sample demonstrates - Provides cURL examples for testing - Compares with Python samples - Update samples/go/README.md to be Go-specific - Removes incorrect Python-focused content - Provides Go project overview and structure - Documents development workflow Addresses PR feedback on google-agentic-commerce#101

…operability - Clarify Go sample provides backend agents only (no shopping agent) - Add detailed instructions for using Python shopping agent with Go backends - Highlight language-agnostic interoperability as key feature - Include cURL examples for direct API testing - Document architecture decisions and integration patterns - Add comparison table with Python sample This addresses PR google-agentic-commerce#101 feedback by clearly documenting: - How to run the Go sample (backend agents only) - How to interact with it (Python shopping agent or direct API calls) - What it demonstrates (backend infrastructure + interoperability)

stefanoamorelli · 2025-10-28T14:30:19Z

Could you add a README that instructs the user:
* how to run this sample

* how to interact with this sample (I notice there is no shopping_agent implemented in go)

* what the sample is demonstrating
An example may be found at samples/python/scenarios/a2a/human-present/cards/README.md.

Thanks for the feedback @joshlund-goog! I've updated the READMEs to address your points, but I also wanted to ask your opinion on something before finalizing this. Right now the golang sample focuses on the three backend agents (merchant, credentials provider, payment processor) without a Shopping Agent because the Python sample uses adk-python which handles all the agent orchestration, state management, and the web UI. We don't have an equivalent framework in Go, so I'd need to build a simplified version from scratch. It would work, but it wouldn't have the same polish as the Python version with ADK's dev-ui.

Alternatively, we can demonstrate the golang agents orchestrated using the Python Shopping Agent, implemented in adk-python. This would show interoperability but it's not a 100% golang sample.

What do you think makes more sense, or do you have other ideas? Please let me know if I'm missing out something.

samples/go/README.md

samples/go/go.sum

samples/go/README.md

samples/go/pkg/common/server.go

joshlund-goog · 2025-10-30T18:14:25Z

Could you add a README that instructs the user:
* how to run this sample

* how to interact with this sample (I notice there is no shopping_agent implemented in go)

* what the sample is demonstrating
An example may be found at samples/python/scenarios/a2a/human-present/cards/README.md.
Thanks for the feedback @joshlund-goog! I've updated the READMEs to address your points, but I also wanted to ask your opinion on something before finalizing this. Right now the golang sample focuses on the three backend agents (merchant, credentials provider, payment processor) without a Shopping Agent because the Python sample uses adk-python which handles all the agent orchestration, state management, and the web UI. We don't have an equivalent framework in Go, so I'd need to build a simplified version from scratch. It would work, but it wouldn't have the same polish as the Python version with ADK's dev-ui.

Alternatively, we can demonstrate the golang agents orchestrated using the Python Shopping Agent, implemented in adk-python. This would show interoperability but it's not a 100% golang sample.

What do you think makes more sense, or do you have other ideas? Please let me know if I'm missing out something.

I like your solution of keeping the adk-python Shopping Agent as the entry point. I sent a review of the snags I ran into testing it out. Please fix and I'll continue testing/reviewing the go sample.

stefanoamorelli · 2025-11-01T16:31:38Z

Thanks @joshlund-goog, I've addressed your comments and added a few improvements.

Here's also an E2E walkthrough of the process:

video.mp4

joshlund-goog

Verified the E2E test works. Nice work. Couple of README updates and then we can squash on merge.

samples/go/scenarios/a2a/human-present/cards/README.md

samples/go/README.md

.github/workflows/linter.yaml

Update scenario documentation to reflect correct agent endpoint paths and improve documentation clarity: - Add complete endpoint paths to agent descriptions (e.g., /a2a/merchant_agent instead of just port numbers) - Fix credentials provider endpoint from credentials_provider_agent to credentials_provider to match actual implementation - Update integration instructions to clarify Python Shopping Agent is pre-configured - Fix markdown linting issues (line length, list indentation, blank lines) - Update run.sh output to display correct credentials provider endpoint These changes align documentation with the actual implementation following commit 669f2a6 where agent cards are hosted at path level. Related to PR google-agentic-commerce#101

Refactor samples/go/README.md following the pattern established in Python samples to eliminate duplication with scenario-specific documentation: - Reduce from 307 to 86 lines (72% reduction) - Remove detailed content duplicated in scenario READMEs - Keep only essential overview, quick start, and navigation links - Point readers to scenario directories for detailed instructions - Remove "production-ready" wording per feedback - Align structure with samples/python/README.md (26 lines) This establishes scenario READMEs as the single source of truth for detailed documentation, making the codebase easier to maintain and reducing the risk of documentation drift. Benefits: - Single source of truth per scenario - Easier maintenance (update once, not twice) - Clearer navigation structure - Consistent with Python samples pattern Related to PR google-agentic-commerce#101

Reduce redundancy in the opening section by: - Shortening title to be more direct - Combining repetitive paragraphs into concise introduction - Using bullet list for what's included instead of prose - Removing repeated mentions of "sample", "Go", "backend agents" - Making the note about Python Shopping Agent more concise The new introduction is clearer and gets to the point faster while maintaining all essential information.

stefanoamorelli · 2025-11-06T19:35:32Z

@joshlund-goog good stuff and thank you so much for all the feedback. I've given some love to the READMEs, lmkwyt!

samples/go/scenarios/a2a/human-present/cards/README.md

joshlund-goog · 2025-11-07T23:29:14Z

@joshlund-goog good stuff and thank you so much for all the feedback. I've given some love to the READMEs, lmkwyt!

And thank you for the work on the go sample. We're very close.

stefanoamorelli · 2025-11-08T17:35:35Z

Adjusted as suggested ✔️ @joshlund-goog

joshlund-goog · 2025-11-11T19:29:48Z

It appears we're blocked by this issue: https://github.com/orgs/community/discussions/144455. I'm looking into temporarily disabling the requirement for "conversations to be resolved".

holtskinner · 2025-11-11T19:36:10Z

It appears we're blocked by this issue: https://github.com/orgs/community/discussions/144455. I'm looking into temporarily disabling the requirement for "conversations to be resolved".

The requirement is removed now

stefanoamorelli requested a review from a team as a code owner October 26, 2025 18:24

gemini-code-assist bot reviewed Oct 26, 2025

View reviewed changes

stefanoamorelli force-pushed the feat/go-standalone-sample branch 15 times, most recently from c9fc058 to 2b8f93d Compare October 26, 2025 20:03

stefanoamorelli mentioned this pull request Oct 26, 2025

[Feat]: Go reference implementation #71

Closed

1 task

stefanoamorelli marked this pull request as draft October 28, 2025 14:31

joshlund-goog reviewed Oct 30, 2025

View reviewed changes

stefanoamorelli marked this pull request as ready for review November 1, 2025 16:27

stefanoamorelli force-pushed the feat/go-standalone-sample branch 2 times, most recently from 104a1f8 to 3a98db2 Compare November 1, 2025 16:44

joshlund-goog approved these changes Nov 6, 2025

View reviewed changes

samples/go/scenarios/a2a/human-present/cards/README.md Outdated Show resolved Hide resolved

samples/go/README.md Outdated Show resolved Hide resolved

joshlund-goog reviewed Nov 6, 2025

View reviewed changes

.github/workflows/linter.yaml Outdated Show resolved Hide resolved

stefanoamorelli added 7 commits November 6, 2025 20:58

chore: re-introduce python ruff linters

c059c17

chore: adjust readme

baea382

docs(go): add link to Quick Start section

66a1e95

docs(go): reorganize integration steps for clarity

2939ca6

stefanoamorelli force-pushed the feat/go-standalone-sample branch 7 times, most recently from c51e4b7 to b5b472d Compare November 6, 2025 19:29

docs(go): add step-by-step instructions for testing shopping flow

a5fa461

stefanoamorelli force-pushed the feat/go-standalone-sample branch from b5b472d to a5fa461 Compare November 6, 2025 19:33

joshlund-goog reviewed Nov 7, 2025

View reviewed changes

samples/go/scenarios/a2a/human-present/cards/README.md Outdated Show resolved Hide resolved

joshlund-goog reviewed Nov 7, 2025

View reviewed changes

samples/go/scenarios/a2a/human-present/cards/README.md Outdated Show resolved Hide resolved

chore: adjust readme

deeff55

joshlund-goog approved these changes Nov 11, 2025

View reviewed changes

joshlund-goog merged commit c3a3876 into google-agentic-commerce:main Nov 11, 2025
4 checks passed

a2a-bot mentioned this pull request Nov 11, 2025

chore(main): release 0.2.0 #108

Closed

a2a-bot mentioned this pull request Nov 18, 2025

chore(main): release 0.2.0 #114

Open

feat(go): introduce standalone sample #101

feat(go): introduce standalone sample #101

Conversation

stefanoamorelli commented Oct 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

gemini-code-assist bot commented Oct 26, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

joshlund-goog commented Oct 27, 2025

Uh oh!

stefanoamorelli commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

joshlund-goog commented Oct 30, 2025

Uh oh!

stefanoamorelli commented Nov 1, 2025

Uh oh!

joshlund-goog left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stefanoamorelli commented Nov 6, 2025

Uh oh!

Uh oh!

Uh oh!

joshlund-goog commented Nov 7, 2025

Uh oh!

stefanoamorelli commented Nov 8, 2025

Uh oh!

joshlund-goog commented Nov 11, 2025

Uh oh!

holtskinner commented Nov 11, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stefanoamorelli commented Oct 26, 2025 •

edited

Loading

stefanoamorelli commented Oct 28, 2025 •

edited

Loading