Automatic A2A SecurityScheme & Skill Security Support in AgentCardBuilder

# 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:

```python
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:

```python
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

```python
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:

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

Then during `_build_tool_skills()`:

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

---

#### Option 3: Validation Utility

Add helper:

```python
_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.