feat: introduce AgentCardProvider #130

adamsitnik · 2025-08-01T10:42:32Z

This PR does the following:

it removes ITaskManager.OnAgentCardQuery because TaskManager should not be responsible for Agent Cards and events should not be queries
introduces AgentCardProvider:
- allows for customization (the method is virtual)
- allows for simple configuration: the user just needs to provide AgentCard.
- it enforces validation: all the [JsonRequired] fields are checked at creation time

So far TaskManager was by default returning an invalid AgentCard:

a2a-dotnet/src/A2A/Server/TaskManager.cs

Line 42 in 5b6cdd8

: Task.FromResult(new AgentCard() { Name = "Unknown", Url = agentUrl });

And the user had to find out how to configure it properly. Now I hope it's more intuitive and kind of obvious.

fixes #88

…kManager.OnAgentCardQuery

gemini-code-assist

Summary of Changes

Hello @adamsitnik, 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 significantly refactors the mechanism for agents to expose their capabilities and metadata within the A2A framework. My goal was to improve clarity, configurability, and adherence to best practices in API design by centralizing agent card management and decoupling it from task management responsibilities. This change makes it more intuitive for users to configure agent cards and ensures robust validation of agent metadata.

Highlights

Decoupling Agent Card Provision from TaskManager: I've refactored the responsibility of providing AgentCard information. Previously, ITaskManager had an OnAgentCardQuery delegate. This has been removed, as TaskManager should not be responsible for agent card queries.
Introduction of AgentCardProvider: I've introduced a new class, AgentCardProvider, which is now solely responsible for handling and validating AgentCard instances. This centralizes the logic for agent card configuration and ensures that all required fields are present at creation time.
Simplified Agent Card Exposure: Agents now expose their AgentCard as a public property (e.g., public AgentCard Card { get; }) instead of implementing a method to query it. This simplifies how agents define and provide their metadata.
Improved MapWellKnownAgentCard API: The MapWellKnownAgentCard extension method in A2A.AspNetCore has been updated. It now directly accepts an AgentCard instance or an AgentCardProvider, making the API more intuitive and removing the previous dependency on ITaskManager for mapping agent cards.
Ensuring Immutability of Agent Cards: To prevent unintended modifications and ensure thread safety, AgentCardProvider now returns cloned instances of AgentCard when queried. This ensures that each request receives a fresh copy of the agent's metadata.
Standardization of Agent Discovery Endpoint: The /v1/card endpoint, which was previously used for agent discovery, has been removed from MapHttpA2A. The standard .well-known/agent.json endpoint is now the sole mechanism for agent card discovery, streamlining the API surface.

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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

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 issue 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 or fill out our survey to provide feedback.

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

src/A2A.AspNetCore/A2AEndpointRouteBuilderExtensions.cs

adamsitnik · 2025-08-01T10:44:48Z

src/A2A.AspNetCore/A2AEndpointRouteBuilderExtensions.cs

-        // /v1/card endpoint - Agent discovery
-        routeGroup.MapGet("/v1/card", async (HttpRequest request, CancellationToken cancellationToken) =>


It seems like #110 missed it.

If this code is removed, how can the agent card be requested?

right; there are 2 ways to get at the card in our impl; one is via an http route, and the other is via the well known endpoint (a la json RPC)

if we remove this, we're forcing only well-known support. could be ok, but just so we're aware.

Based on #105 I have assumed that we want the AgentCard to be exposed optionally. I am fine reverting this particular change, but I want to make sure that it's desired.

@darrelmiller thoughts?

I'm fine with removing that (maybe in a separate PR) as long as there's a way to configure getting the agent card over an HTTP route if needed.

The specification is a bit challenging in that it says an Agent MUST expose an Agent Card, but doesn't mandate how the agent must be discovered (which is good). It feels to me like the introduction of the /v1/card endpoint is one way to guarantee that if someone gives you a URL to an agent, then at least you have a guaranteed way to find the card. Except JSON-RPC doesn't yet implement that endpoint so, again not guaranteed.
I think priority one is that we make it possible to make compliant agents. Creating a library that helps people fall into the pit of success can come over time.

My understanding of the specification is that this endpoint should implement Extended Authenticated Agent Card https://a2a-protocol.org/dev/specification/#356-method-mapping-reference-table

@Blackhex Thanks for that pointer. That's news to me and a somewhat perplexing decision in my opinion.

gemini-code-assist

Code Review

This pull request introduces a significant architectural improvement by creating the AgentCardProvider. This change effectively centralizes agent card creation and validation, removing this responsibility from the ITaskManager. The implementation is well-executed across the sample agents and ASP.NET Core extensions, enhancing modularity and maintainability. My review includes a critical suggestion to ensure deep cloning in the AgentCard copy constructor to prevent potential data corruption issues, and a refactoring suggestion in AgentCardProvider to improve code readability.

src/A2A/Models/AgentCard.cs

src/A2A/Server/AgentCardProvider.cs

src/A2A/Models/AgentCapabilities.cs

src/A2A/Server/AgentCardProvider.cs

SergeyMenshykh · 2025-08-01T11:46:15Z

src/A2A.AspNetCore/A2AEndpointRouteBuilderExtensions.cs

-        // /v1/card endpoint - Agent discovery
-        routeGroup.MapGet("/v1/card", async (HttpRequest request, CancellationToken cancellationToken) =>


If this code is removed, how can the agent card be requested?

SergeyMenshykh · 2025-08-01T12:13:39Z

src/A2A/Server/AgentCardProvider.cs

+        /// <param name="agentCard">The valid agent card to initialize with.</param>
+        /// <exception cref="ArgumentNullException">Thrown when agentCard is null.</exception>
+        /// <exception cref="ArgumentException">Thrown when any required property of agentCard is null or empty.</exception>
+        public AgentCardProvider(AgentCard agentCard)


In case I want to build my agent card dynamically, I'll need to inherit from the class to override the GetAgentCardAsync method. However, in my class, I'll also have to add the constructor public MyAgentCardProvider(AgentCard agentCard) : base(agentCard) that would force me to provide an agent card I don't have yet, and the class is supposed to build it for me.

I can see two options to fix this:

Introduce an interface or abstract class that both AgentCardProvider and MyAgentCardProvider will implement or inherit from. Pros: DI friendly. Cons: A new, unnecessary model class will need to be added increasing the public API surface of the SDK, resulting in more potentially breaking changes when it needs to change.

Model the agent card provider as a callback function and refactor the MapWellKnownAgentCard(this IEndpointRouteBuilder endpoints, Func<Task<AgentCard>> agentCardProvider, [StringSyntax("Route")] string agentPath) to use it. Pros: Simple. Cons: Not DI friendly.

I agree w/ the above; I'm - of course - for Opt 1 (it follows what I had proposed) but I hear the concern about public surface area as well...

We can start simply with option 2 and implement option 1 later, if and when needed.

In case I want to build my agent card dynamically, I'll need to inherit from the class to override the GetAgentCardAsync method. However, in my class, I'll also have to add the constructor public MyAgentCardProvider(AgentCard agentCard) : base(agentCard) that would force me to provide an agent card I don't have yet, and the class is supposed to build it for me.

Great catch. I've added a parameter less protected constructor and a test that shows how to use it.

Introduce an interface or abstract class that both AgentCardProvider and MyAgentCardProvider will implement or inherit from. Pros: DI friendly. Cons: A new, unnecessary model class will need to be added increasing the public API surface of the SDK, resulting in more potentially breaking changes when it needs to change.

With the updated form the implementation gives us the benefits of the abstract class without its disadvantages (the need of providing an implementation and users discovering its existence)

Model the agent card provider as a callback function and refactor the MapWellKnownAgentCard(this IEndpointRouteBuilder endpoints, Func<Task<AgentCard>> agentCardProvider, [StringSyntax("Route")] string agentPath) to use it. Pros: Simple. Cons: Not DI friendly.

Func is very simple, but on the other hand it limits us to only one method. What if we need a new one? With a spec evolving as quickly as A2A I would prefer to have future-proof solutions from the beginning.

I'm not seeing where the latest rev handles the scenario where I want to build my card dynamically (call MCP servers to set up skills collection, etc.)... I'd have to do all that before creating the Provider instance, and then use the provider in the extension method call. Since all this happens during DI container setup, doing async to build my card first is not fun.

I think this is why an Interface is a better choice here, with - perhaps - a default impl that looks like what's in this PR now, but named something like StaticAgentCardProvider.

src/A2A.AspNetCore/A2AEndpointRouteBuilderExtensions.cs

brandonh-msft · 2025-08-01T19:15:12Z

src/A2A/Server/AgentCardProvider.cs

+        /// <param name="agentCard">The valid agent card to initialize with.</param>
+        /// <exception cref="ArgumentNullException">Thrown when agentCard is null.</exception>
+        /// <exception cref="ArgumentException">Thrown when any required property of agentCard is null or empty.</exception>
+        public AgentCardProvider(AgentCard agentCard)


I agree w/ the above; I'm - of course - for Opt 1 (it follows what I had proposed) but I hear the concern about public surface area as well...

src/A2A/Models/AgentCard.cs

src/A2A/Server/AgentCardProvider.cs

wrong button

Blackhex · 2025-08-27T11:39:10Z

samples/AgentServer/EchoAgent.cs

    }

-    private Task<AgentCard> GetAgentCardAsync(string agentUrl, CancellationToken cancellationToken)
+    public AgentCard Card


Shouldn't the library hint its users how agent implementations should look like by providing abstract agent class demonstrating what are the common patterns? Such class could either have AgentCard Card as abstract property or implement AgentCardProvider. app.MapWellKnownAgentCard() could then accept agent instance instead of card, attaching agent instance to TaskManager instance could be simplified, etc.

One of the original design goals was to impose no requirements on the implementation of the agent. An existing agent should be able to adapted to "talk A2A". Requiring an agent to implement a specific base class would force people to create a "proxy agent" to adapt existing agents. That feels pretty intrusive.

Thank you for explaining the original intent. The suggestion was meant as an option or a showcase of "good practice" not a requirement though.

Blackhex

I like the idea in general. I just think it can go one step further.

Blackhex · 2025-08-27T11:52:44Z

samples/AgentServer/EchoAgent.cs

+        get
        {
-            return Task.FromCanceled<AgentCard>(cancellationToken);
+            var capabilities = new AgentCapabilities()


Why not inlining it into AgentCard instance initializer? (The same applies to other agent implementations in samples/ folder.)

src/A2A/Models/AgentCapabilities.cs

Blackhex · 2025-08-27T12:17:21Z

src/A2A/Server/AgentCardProvider.cs

+        /// <exception cref="ArgumentException">Thrown when any required property of <paramref name="agentCard"/> is invalid.</exception>
+        public static AgentCard Validate(AgentCard agentCard)
+        {
+            if (agentCard is null)


Please, consider moving this logic into a separate class used here (that can even be set as a parameter of the provider constructor). Technically speaking having it here breaks SRP.

Could these validations be done in the agent card itself?

Blackhex · 2025-08-27T12:18:52Z

src/A2A/Server/AgentCardProvider.cs

+        /// <param name="agentCard">The valid agent card to initialize with.</param>
+        /// <exception cref="ArgumentNullException">Thrown when agentCard is null.</exception>
+        /// <exception cref="ArgumentException">Thrown when any required property of agentCard is null or empty.</exception>
+        public AgentCardProvider(AgentCard agentCard) => _agentCard = Validate(agentCard);


Why two constructors are needed? Wouldn't single constructor with optional argument defaulting to null be more conscise?

Blackhex · 2025-08-27T12:33:21Z

src/A2A.AspNetCore/A2AEndpointRouteBuilderExtensions.cs

+            {
+                return Results.Ok(await agentCardProvider.GetAgentCardAsync(uriBuilder.ToString(), cancellationToken));
+            }
+            catch (Exception ex)


If the example agent implementation implementing the AgentCardProvider mentioned in the previous comment would be utilized, this error handling (and this application-specific message display) could be offloaded to the user buisiness logic.

Blackhex · 2025-08-27T12:35:42Z

samples/AgentServer/EchoAgent.cs

    }

-    private Task<AgentCard> GetAgentCardAsync(string agentUrl, CancellationToken cancellationToken)
+    public AgentCard Card


Thank you for explaining the original intent. The suggestion was meant as an option or a showcase of "good practice" not a requirement though.

Blackhex · 2025-08-27T12:40:38Z

src/A2A.AspNetCore/A2AEndpointRouteBuilderExtensions.cs

-        // /v1/card endpoint - Agent discovery
-        routeGroup.MapGet("/v1/card", async (HttpRequest request, CancellationToken cancellationToken) =>


My understanding of the specification is that this endpoint should implement Extended Authenticated Agent Card https://a2a-protocol.org/dev/specification/#356-method-mapping-reference-table

Blackhex · 2025-08-27T12:50:14Z

src/A2A/Server/AgentCardProvider.cs

+            {
+                throw new ArgumentException("Agent card must define a non-empty ProtocolVersion.", nameof(agentCard));
+            }
+            else if (agentCard.Capabilities is null)


On a second thought, shouln't for example this validation be handled by the nullability of the property?

i had noticed we are doing null checks elsewhere in the codebase as well; I believe this is because netstandard 2 doesn't support nullable.

…agentCardProvider # Conflicts: # src/A2A.AspNetCore/A2AEndpointRouteBuilderExtensions.cs

feat: introduce AgentCardProvider, validate AgentCard and remove ITas…

0a1ba62

…kManager.OnAgentCardQuery

adamsitnik requested review from brandonh-msft and SergeyMenshykh August 1, 2025 10:42

gemini-code-assist bot reviewed Aug 1, 2025

View reviewed changes

adamsitnik commented Aug 1, 2025

View reviewed changes

src/A2A.AspNetCore/A2AEndpointRouteBuilderExtensions.cs Show resolved Hide resolved

adamsitnik commented Aug 1, 2025

View reviewed changes

gemini-code-assist bot reviewed Aug 1, 2025

View reviewed changes

src/A2A/Models/AgentCard.cs Show resolved Hide resolved

src/A2A/Server/AgentCardProvider.cs Show resolved Hide resolved

adamsitnik commented Aug 1, 2025

View reviewed changes

src/A2A/Models/AgentCapabilities.cs Show resolved Hide resolved

adamsitnik commented Aug 1, 2025

View reviewed changes

src/A2A/Server/AgentCardProvider.cs Show resolved Hide resolved

SergeyMenshykh reviewed Aug 1, 2025

View reviewed changes

brandonh-msft reviewed Aug 1, 2025

View reviewed changes

address code review feedback

5af8c77

brandonh-msft previously approved these changes Aug 27, 2025

View reviewed changes

brandonh-msft self-requested a review August 27, 2025 02:52

Blackhex reviewed Aug 27, 2025

View reviewed changes

brandonh-msft mentioned this pull request Sep 8, 2025

feat: Implement Extended Authenticated Agent Card handling #178

Draft

11 tasks

Merge branch 'main' of https://github.com/a2aproject/a2a-dotnet into …

249e2ca

…agentCardProvider # Conflicts: # src/A2A.AspNetCore/A2AEndpointRouteBuilderExtensions.cs

brandonh-msft linked an issue Sep 8, 2025 that may be closed by this pull request

Allow For Dynamic Agent Card #46

Open

Merge branch 'main' into agentCardProvider

d043607

		// /v1/card endpoint - Agent discovery
		routeGroup.MapGet("/v1/card", async (HttpRequest request, CancellationToken cancellationToken) =>

feat: introduce AgentCardProvider #130

Are you sure you want to change the base?

feat: introduce AgentCardProvider #130

Uh oh!

Conversation

adamsitnik commented Aug 1, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Blackhex Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brandonh-msft Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brandonh-msft Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

brandonh-msft Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Blackhex Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Blackhex left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Blackhex Aug 27, 2025 •

edited

Loading

brandonh-msft Aug 1, 2025 •

edited

Loading

brandonh-msft Aug 27, 2025 •

edited

Loading

brandonh-msft Aug 1, 2025 •

edited

Loading

Blackhex Aug 27, 2025 •

edited

Loading

Blackhex Aug 27, 2025 •

edited

Loading

Blackhex Aug 27, 2025 •

edited

Loading