Automatic A2A SecurityScheme & Skill Security Support in AgentCardBuilder

[djanito]

Feature Request: Automatic A2A SecurityScheme & Skill Security Support in AgentCardBuilder

🔴 Required Information

Is your feature request related to a specific problem?

Yes.

When generating an A2A agent card using AgentCardBuilder, the current implementation does not properly support A2A security features, specifically:

1. The builder does not guide or enforce proper handling of SecurityScheme definitions required by the A2A protocol.
2. The AgentSkill.security property (for declaring required scopes per skill) is not supported or auto-generated.
3. Tool-level or skill-level authentication requirements cannot be expressed in the generated AgentCard.

This makes the automatically generated agent cards incomplete for secured A2A deployments, especially when:

• Using OAuth2 scopes per tool
• Requiring API keys
• Supporting bearer tokens (JWT)
• Requiring mutual TLS
• Defining skill-specific access control policies

Currently, security_schemes can be passed manually into AgentCardBuilder, but:

• There is no automatic extraction or validation.
• There is no linkage between defined SecurityScheme objects and AgentSkill.security.
• There is no support for declaring per-tool security requirements.

This forces developers to manually post-process or override the generated AgentCard to be A2A compliant.

---

Describe the Solution You'd Like

Enhance AgentCardBuilder to fully support A2A security by:

1️⃣ Proper SecurityScheme Handling

Support structured creation and validation of:

SecurityScheme(
    type="http" | "apiKey" | "oauth2" | "mutualTLS",
    scheme="bearer",
    bearerFormat="JWT",
    description="..."
)

The builder should:

• Accept structured security scheme definitions
• Validate required fields depending on type
• Automatically include them in the generated AgentCard
• Optionally infer them from tool metadata if available

---

2️⃣ Skill-Level Security Support

Support populating:

AgentSkill(
    ...
    security=[{ "oauth2": ["scope1", "scope2"] }]
)

Specifically:

• Allow tools to declare required scopes
• Automatically propagate tool-level security metadata to the generated AgentSkill
• Allow global security requirements to be inherited by all skills
• Ensure generated cards comply with the A2A protocol security specification

---

3️⃣ Security Propagation Strategy

Proposed behavior:

Level	Behavior
AgentCard	Contains declared security_schemes
AgentSkill	Contains security referencing declared schemes
Tool	Can optionally declare required scopes
Default behavior	If global security defined, apply to all skills unless overridden

---

Impact on your work

This is critical for production deployments where:

• Agents are exposed through authenticated A2A endpoints
• OAuth2 scopes control tool-level access
• Enterprise environments require strict authentication
• Zero-trust architecture requires skill-level authorization

Without this feature:

• Generated agent cards are not compliant with secured A2A usage
• Manual post-processing is required
• Security configuration becomes error-prone

This is important for upcoming secure multi-agent deployments.

---

🟡 Recommended Information

Describe Alternatives You've Considered

Current workaround:

• Manually building AgentCard
• Manually overriding generated skills
• Manually injecting security_schemes
• Patching AgentCardBuilder

These approaches:

• Break automatic generation
• Increase maintenance burden
• Create divergence from ADK updates

---

Proposed API / Implementation

Option 1: Extend AgentCardBuilder constructor

AgentCardBuilder(
    agent=my_agent,
    security_schemes={
        "oauth2": SecurityScheme(
            type="oauth2",
            description="OAuth2 authentication"
        )
    },
    default_skill_security={
        "oauth2": ["agent.read"]
    }
)

---

Option 2: Tool-level security declaration

Allow tools to optionally define:

class MyTool(BaseTool):
    required_scopes = ["calendar.read"]
    security_scheme = "oauth2"

Then during _build_tool_skills():

AgentSkill(
    ...
    security=[{
        tool.security_scheme: tool.required_scopes
    }]
)

---

Option 3: Validation Utility

Add helper:

_validate_security_schemes(schemes: Dict[str, SecurityScheme])

To ensure:

• Required fields per type
• No orphan skill security references
• A2A compliance

---

Additional Context

The A2A specification defines:

SecurityScheme

• type: "http" | "apiKey" | "oauth2" | "mutualTLS"
• scheme
• bearerFormat
• description

Skill

• security: array of security requirement objects

Currently, AgentCardBuilder:

• Accepts security_schemes
• Does not connect them to skills
• Does not auto-generate or validate security structures

This enhancement would make ADK-generated A2A cards fully compliant and production-ready.