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

[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.

TODO

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

Fixes N/A 🦕

[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!

[ognis1205]

Hi @yangzhengzhiroy, thanks again for your input!

I took another look at your comment and realized there might be a fundamental misunderstanding. To clarify:

The API Catalog is not intended to combine multiple Agent Card definitions into a single catalog.
Instead, it’s designed to support Open Discovery, as outlined in the Internet Draft, by exposing the list of A2A-related
endpoints — such as Agent Card URLs — via a .well-known/api-catalog endpoint.

So, it's more about publishing a directory of endpoints (including one or more Agent Cards per agent, if needed), rather than merging multiple agents’ information into one file.

Hope that clears things up — happy to discuss further if needed!

[ognis1205]

TODO:

• https://www.rfc-editor.org/rfc/rfc9727.html#section-4.2-1