[DO NOT MERGE - PoC] feat: support open agent discovery under shared base URL via API Catalog

[ognis1205]

Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• Follow the CONTRIBUTING Guide.
• Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
• Ensure the tests and linter pass (Run nox -s format from the repository root to format)
• Appropriate docs were updated (if necessary)

Note:
This PR is currently not ready to be merged as it temporarily uses types.py generated from a personal fork of the schema repository. This will be replaced with an official schema source once it becomes available or is upstreamed.

While this PR is primarily intended as a PoC/demo implementation, if google/A2A#642 is considered meaningful and accepted by the community, we may consider merging this implementation more formally into the project.

Some checks (e.g., Check Spelling, Lint Code Base) are currently failing, but since this PR is primarily for PoC/demonstration purposes, these issues are not critical at this stage. They will be addressed within this PR.

TODO

• Complete SDK implementation
• Add example usage
• Write test cases

Fixes N/A 🦕

[holtskinner]

Can you move this demo into the a2a-samples repo? https://github.com/google-a2a/a2a-samples

[ognis1205]

Thanks for the suggestion!

As noted in the PR, this is currently a PoC and includes temporary implementations of A2AStarletteRouteBuilder and A2AStarletteBuilder within this working branch. These are used to support the example shown here.

I've kept the example in this repo for now to keep everything self-contained and demonstrable in one place. That said, if the upstream proposal is accepted, I'm happy to migrate the example to the a2a-samples.

Appreciate the feedback—please let me know if you'd prefer an early move regardless of the upstream status. Thanks again!

[holtskinner]

This change will need to be approved in the A2A specification. https://github.com/google-a2a/A2A

This file is the current source of truth https://github.com/google-a2a/A2A/blob/main/types/src/types.ts

[ognis1205]

Hi @holtskinner , thank you for the review!

Just a quick reminder: as mentioned in the PR description, this is a PoC and currently uses a temporary types.py generated via datamodel-codegen from a personal fork of the schema repository. This setup is only intended to demonstrate what integration might look like, and will be updated once the schema is finalized and available upstream.

To make this intent clearer, I’ll update the PR title accordingly as well. Thanks again for taking the time to look through it!

[yangzhengzhiroy]

I was exploring shared domain and this is right on time, thanks!

If I understand correctly, this change requires agent catalog definition to have multiple agent card info into one catalog for agent discovery. Since this requires changes on a2a.json, will it be easier to adopt this feature by keeping the same schema with separate well-known locations, {base-url}/{agent-identifier}/.well-known/agent.json? Though this requires one agent.json per each agent, it may help to push this feature more smoothly.

[ognis1205]

Hi @yangzhengzhiroy, thank you for your comment!

Your understanding is mostly correct. While "API Catalog" might sound a bit grand, the idea is to support Open Discovery by exposing a list of agent endpoints via a /.well-known/agent-catalog endpoint. So as you pointed out, if we want to adopt this as part of the A2A protocol, it would indeed require changes to the a2a.json schema.

One small clarification: according to the RFC for Well-Known URIs, the .well-known path must reside at the root level of the origin. That means {base-url}/{agent-identifier}/.well-known/agent.json would not be valid. Instead, a path like {base-url}/{agent-identifier}/path/to/agent.json would be more appropriate (the actual path can be arbitrary outside of .well-known).

I'd really appreciate it if you could also take a look at this discussion and share your thoughts there!