--- title: "A2A Protocol" description: "Agent-to-Agent delegation across sandboxes and organizations" --- # A2A Protocol Caged supports the **A2A (Agent2Agent) Protocol** — a Linux Foundation standard (April 2026) for secure agent-to-agent delegation. While MCP connects agents to tools *inside* a sandbox, A2A connects agents to agents *across* sandboxes and organizations. ## A2A vs MCP: When to Use Which | Protocol | Purpose | Scope | Use Case | |----------|---------|-------|----------| | **MCP** | Agent → Tools | Inside sandbox | File ops, terminal, Git, databases | | **A2A** | Agent → Agent | Across sandboxes | Delegation, collaboration, pipelines | **Think of it this way:** - **MCP**: "I need to read a file" → MCP tool in your sandbox - **A2A**: "I need a Python expert to analyze this" → Delegate to Python analysis agent ## Quick Start ### 1. Register Your Agent Make your agent discoverable via A2A: ```bash # Register an agent backed by a pipeline caged a2a agents create \ --name "Code Analyzer" \ --description "Analyzes code for security vulnerabilities" \ --pipeline-id pipe_abc123 \ --public ``` ### 2. Discover Remote Agents Fetch another agent's capabilities: ```bash caged a2a discover https://agent.example.com ``` Output: ```yaml Name: Security Auditor URL: https://agent.example.com Skills: - code-review: Reviews code for security issues - dependency-audit: Scans dependencies for CVEs ``` ### 3. Delegate a Task Send work to a remote agent: ```bash caged a2a delegate https://agent.example.com \ --skill code-review \ --input '{"repo": "https://github.com/org/repo"}' ``` ## Core Concepts ### Agent Card Every A2A agent publishes an **Agent Card** at `/.well-known/agent.json`: ```json { "name": "Code Analyzer", "description": "Analyzes code for security vulnerabilities", "url": "https://my-agent.caged.dev", "version": "1.0.0", "capabilities": ["streaming", "push"], "skills": [ { "id": "analyze", "name": "Code Analysis", "description": "Performs static analysis on code", "tags": ["security", "static-analysis"], "inputSchema": { "type": "object", "properties": { "repo": { "type": "string" }, "branch": { "type": "string", "default": "main" } }, "required": ["repo"] } } ], "authentication": { "type": "bearer", "schemes": ["api_key"] } } ``` ### Task Lifecycle Tasks flow through these states: ```mermaid stateDiagram-v2 [*] --> pending pending --> running: Agent accepts running --> completed: Success running --> failed: Error running --> canceled: User/timeout running --> input_needed: Needs clarification input_needed --> running: User responds completed --> [*] failed --> [*] canceled --> [*] ``` ### Skills Skills are specific capabilities an agent offers. Each skill: - Has an ID, name, and description - Defines input/output schemas - Can have tags for discovery ## Integration with Pipelines A2A delegation integrates directly with Caged pipelines via the `a2a` stage type: ```yaml name: Security Review Pipeline stages: - name: clone type: command command: git clone $REPO_URL ./code - name: security-analysis type: a2a agent_url: https://security-agent.caged.dev skill_id: analyze input_from_state: [repo_url] output_to_state: [findings] max_cost_usd: 5.00 depends_on: [clone] - name: report type: command command: ./generate-report.sh depends_on: [security-analysis] ``` ### A2A Stage Configuration ```typescript interface A2AConfig { agent_url: string; // Remote agent URL agent_id?: string; // Specific agent ID (if multiple) skill_id?: string; // Skill to invoke prompt?: string; // Natural language prompt input?: object; // Direct input data priority?: number; // 1-10, higher = more urgent max_cost_usd?: number; // Budget cap for this task input_from_state?: string[]; // Pull from pipeline state output_to_state?: string[]; // Push results to state streaming?: boolean; // Enable SSE streaming fallback_agent?: string; // Agent to try on failure } ``` ## API Reference ### Agent Registration ```http POST /v1/a2a/agents Authorization: Bearer { "name": "My Agent", "description": "Does amazing things", "pipeline_id": "pipe_abc123", "skills": [...], "public": true, "max_cost_per_task": 10.00, "rate_limit_rpm": 60 } ``` ### Task Creation ```http POST /v1/a2a/agents/{agentId}/tasks Authorization: Bearer { "skill_id": "analyze", "input": { "repo": "https://github.com/org/repo" }, "priority": 5 } ``` ### Task Streaming (SSE) ```http GET /v1/a2a/tasks/{taskId}/stream Accept: text/event-stream Authorization: Bearer ``` Events: ``` event: progress data: {"percentage": 50, "message": "Analyzing dependencies..."} event: message data: {"role": "agent", "parts": [{"type": "text", "text": "Found 3 issues"}]} event: complete data: {"status": "completed", "output": {...}} ``` ## CLI Commands ```bash # Agent management caged a2a agents list caged a2a agents create --name "..." --pipeline-id pipe_... caged a2a agents get caged a2a agents delete caged a2a agents enable caged a2a agents disable # Discovery caged a2a discover # Task delegation caged a2a delegate --skill --input '{...}' caged a2a task get caged a2a task cancel caged a2a task message "Your response" ``` ## MCP Tools for A2A When using Caged via MCP (Claude Desktop, Cursor, etc.), these tools are available: | Tool | Description | |------|-------------| | `a2a_agents_list` | List your registered A2A agents | | `a2a_agent_get` | Get agent details | | `a2a_agent_create` | Register a new agent | | `a2a_agent_delete` | Delete an agent | | `a2a_discover` | Discover a remote agent | | `a2a_delegate` | Delegate a task | | `a2a_task_get` | Get task status | | `a2a_task_message` | Send message to task | | `a2a_task_cancel` | Cancel a task | ## Security Considerations ### Authentication A2A in Caged uses Bearer token authentication: - Each registered agent can have its own API key - Tasks are authenticated and tracked per account - Rate limits apply per-agent ### Cost Controls - Set `max_cost_per_task` on agent registration - Pipeline A2A stages can set `max_cost_usd` per stage - Budget alerts integrate with existing notification channels ### Trust - A2A tasks contribute to trust scoring - High-risk delegations may require approval (via HITL) - All A2A activity is logged in the event stream ## Example: Multi-Agent Code Review A pipeline that orchestrates multiple specialized agents: ```yaml name: Comprehensive Code Review triggers: - type: github_pr events: [opened, synchronize] stages: - name: fetch type: command command: git fetch origin $PR_HEAD && git checkout $PR_HEAD - name: lint type: a2a agent_url: https://lint-agent.caged.dev skill_id: lint-code input: { language: "typescript" } output_to_state: [lint_issues] depends_on: [fetch] - name: security type: a2a agent_url: https://security-agent.caged.dev skill_id: scan input_from_state: [changed_files] output_to_state: [security_findings] depends_on: [fetch] - name: test-coverage type: a2a agent_url: https://test-agent.caged.dev skill_id: analyze-coverage output_to_state: [coverage_report] depends_on: [fetch] - name: summarize type: llm prompt: | Summarize the code review findings: - Lint issues: $lint_issues - Security findings: $security_findings - Coverage: $coverage_report depends_on: [lint, security, test-coverage] - name: comment type: command command: gh pr comment $PR_NUMBER --body "$summary" depends_on: [summarize] ``` ## Best Practices 1. **Define clear skill boundaries** — Each skill should do one thing well 2. **Version your agents** — Include version in Agent Card for compatibility 3. **Set cost limits** — Always specify `max_cost_per_task` and stage budgets 4. **Use streaming for long tasks** — Gives real-time progress feedback 5. **Implement fallbacks** — Use `fallback_agent` for resilience 6. **Tag skills appropriately** — Helps with discovery and routing