discussion: [optionally] support multiple AgentCards per pod.

[usize]

Feature Description

Some agent authors have expressed a desire to host multiple [sub]agents within a single pod. They would like a way of representing these sub agents and discovering them. Currently, this is not possible as we assume a single AgentCard per pod and a single AgentCard itself may not be a suitable format for presenting multiple sub-agents.

Proposed Solution

Annotations to denote multiple AgentCard endpoints

Currently, the agent card controller recognizes candidate workloads via a webhook: protocol.kagenti.io/a2a.

This attempts to pull AgentCard metadata from the A2A spec's well known agentcard endpoint.

We could extend this via Kubernetes Annotations, to produce a map of non-detault endpoints or additional ports to explore for agentcards.

Open Questions

• What if there's a single entrypoint e.g. an orchestrator agent that fronts an agentic workflow and it hosts its own AgentCard. How do we differentiate the entrypoint agent from the subagents hidden in the workflow? A new field in the schema?

Want to contribute?

• I would like to work on this issue.

Additional Context

No response

[usize]

cc: @varshaprasad96 @kevincogan

[grs]

What if the AgentCard referenced a port on a Service, rather than a Deployment or StatefulSet? At present it refernces a Deployment or StatefulSet but assumes a Service of the same name as the workload and uses the first port on that for actually retrieving the agent card. Is there any need for it to directly reference the workload rather than the port on the service through which it retrieves the card?

[kevincogan]

A few thoughts on the open question:

1. How the discovery approach interacts with the security controllers:

Both the annotation-based approach and the Service:port approach would work for discovery, but they interact differently with the existing security and NetworkPolicy logic.

If each AgentCard targets a different Service:port, the NetworkPolicy controller works correctly as is because each card maps to a distinct policy. If multiple AgentCards target the same workload, the NetworkPolicy controller would need updating. It currently creates a single <workloadName>-signature-policy and decides permissive vs restrictive based on whichever card reconciles last. With multiple cards per workload, we would need it to aggregate verification status across all cards before making that decision. The AgentCard controller already has AND-aggregation logic for the workload label (aggregateVerifiedState), so the pattern exists. It just is not used by the NetworkPolicy controller yet.

Either way, sub-agents in the same pod share a SPIFFE identity and network namespace, so the existing signature verification and identity binding apply at the pod level regardless of how many AgentCards exist. The security outcome is the same. The difference is how much controller work is needed to get there.

Another option to consider: keep one AgentCard CR per workload and store discovered sub-agent cards in a status.discoveredAgents array on the parent CR. That would avoid the webhook and NetworkPolicy changes entirely, but the tradeoff is that sub-agents would not be independently addressable as their own kubectl get agentcard resources.

2. Differentiating entrypoint vs sub-agents:

Once the operator can discover multiple agent cards per pod, each sub-agent would have its own card with its own name, skills, and URL. That gives you differentiation at the discovery level. The remaining question is how the operator models the relationship between them. A field like parentRef on the AgentCard spec (pointing to the orchestrator's AgentCard) could let the operator track which cards are part of the same workflow and which is the entrypoint. That would also be useful for any downstream consumer that needs to understand the topology.

3. Case where multiple AgentCards may not be needed:

If the sub-agents are not independently addressable (for example, agents in a CrewAI crew or LangGraph workflow running as a single process), they do not have their own A2A endpoints to fetch from. The A2A spec already handles this: the orchestrator's single card with its skills array describes the full set of capabilities. Worth considering whether some of the use cases raised fall into this category, since it would not require operator changes.

4. Upstream alignment:

The A2A spec community discussed the same multi-agent per host discovery problem back in April 2025 (a2aproject/A2A#178, Discussion #166). Their guidance at the time was different path or different port per agent, with registries for enterprise scenarios. There has not been much activity on it since, but worth keeping in mind in case the next spec revision addresses it.

[usize]

@grs as per a2aproject/A2A#166 it seems we should support both multiple ports and multiple paths.

But to your deeper point, annotations for configuration are... suspect. We have a few options here.

To @kevincogan 's point, I know @varshaprasad96 is working on an AgentRuntime CRD which is meant to store configuration relevant to our agents, and that may be a good place to store a list of endpoints where agentcards can be found.

Additional labels seem suspect to me here, because we need to represent an arbitrary number of possible endpoints. So the naming scheme may be... ugly.

A ConfigMap is another option.

What do we think?

[grs]

I agree, separate agent cards only makes sense for an agents that are independently addressable.

Allowing path as an additional a discriminator also makes sense.

From the perspective of the AgentCard CRD, a reference to the service (required), the name of a port on that service (required) and a path (optional), would be sufficient to identify an addressable agent. (If extending beyond A2A, the spec could also specify the protocol).

Verifying any signatures in the agent card data is useful. That can be done in my view in a generic way, as intended by the A2A specification. If we start out only supporting verification for inline CA chains, that's fine. It shouldn't matter at that stage what that chain is. The task is simply verifying that the signature is valid, and identifying the root of the chain. A separate step is then asserting on the desired root.

An invalid signature or assertion on the desired root should in my view merely be flagged clearly in the status of the AgentCard (optionally preventing the agent card data being displayed, though the value of that is I think marginal if the violation is clear enough).

In my view, any automation of NetworkPolicy should be an entirely separate layer. This could reference AgentCard status, but would I think also take other aspects in to account. A very important part is for it to be explicit and transparent, ideally by being controlled through a distinct CRD with a status that clearly indicates any restrictions applied to make understanding connectivity issues simpler.

Though I don't see any use case that would require more than one AgentCard for the same service+port+path combination, I also do not see why that should in itself cause any problem (beyond unnecessary duplication, which could perhaps be highlighted in a status message). The agent card data (and hence signature) should be the same for each duplicate card and they would each have their own status subresource.

Separate to the structure of the AgentCard CRD is the idea of auto-created AgentCard CRDs. A question there is whether that is intended to be a simple convenience that supports only basic cases (with cases not handled there falling back to explicit creation of the CRD), or whether it is desired to be essentially an alternative way of defining the spec of any AgentCard (through labeling and annotation).