A2A External Agent Interoperability.

The conductor ecosystem operates 38 agents in a closed communication loop. Agents dispatch to each other via the Task tool, validated by Gemini, governed by the approval framework — but this entire system is invisible to the outside world. No external agent can participate, and no internal agent can advertise its capabilities externally.

Multi-platform orchestration already happens in practice: Claude Code agents invoke Gemini CLI for validation, Codex CLI for secondary review, and shell scripts for infrastructure tasks. But this integration is ad-hoc shell scripting — no standard protocol, no authentication, no capability discovery, no governance enforcement.

The Agent Gateway sits between the conductor ecosystem and the external world. It exposes a unified HTTP interface that routes requests through protocol-specific adapters (A2A, MCP, REST) to internal agents. Every request passes through authentication, rate limiting, and governance checks before reaching any agent.

Protocol Adapters

Trust Levels

Five trust levels govern what external callers can access. Trust level determines which agents are callable, which operations are permitted, and what rate limits apply.

Supporting Components

Key architectural and design choices, with rationale for each decision.

• Only 15 of 38 agents exposed externally. The orchestrator (conductor), state management (conductor-checkpoint), security agents (conductor-ciso, conductor-pentest-coordinator), and the Gemini validator are internal-only. Exposing orchestration control to external callers would create a privilege escalation path. The 15 exposed agents are functional workers (builder, architect, QA, doc-gen) that produce bounded outputs.
• Async-first invocation model. Agent tasks can take seconds to minutes. Synchronous HTTP request/response would require long-lived connections and risk timeouts. Async dispatch (return task_id immediately, poll or webhook for result) is more resilient, enables queuing, and matches the existing conductor dispatch model.
• Three protocol adapters, not one. A2A serves the Google agent ecosystem. MCP Bridge serves the Claude Code ecosystem. REST serves everything else (scripts, bots, CI/CD). Forcing all callers through A2A would exclude non-Google agents; forcing all through REST would lose the rich capability discovery and streaming that A2A and MCP provide.
• Governance metadata in the context envelope, not out-of-band. Every external request carries governance metadata (trust level, session ID, approval chain) inside the request envelope rather than in HTTP headers or a separate governance channel. This ensures governance travels with the request through any intermediary and cannot be accidentally stripped.
• Standalone script fallback for gateway unavailability. If the FastAPI gateway is down, internal operations must continue. The standalone fallback enables direct agent invocation via shell scripts (the current approach), ensuring the gateway is an enhancement, not a single point of failure.
• FastAPI as the gateway framework. Python with FastAPI provides: async support (essential for agent dispatch), automatic OpenAPI schema generation (free documentation), middleware for auth/rate-limiting, and compatibility with the existing Python tooling in the ecosystem. Performance is adequate for the expected request volume (hundreds/day, not thousands/second).
• YAML registry as single source of truth. Agent capabilities are defined once in YAML (extending the existing capabilities.yaml). All four discovery mechanisms (static, HTTP, A2A Cards, MCP tools) derive from this single source. No capability can be advertised externally that is not defined in the registry.

A2A Interoperability connects to 10 systems, serving as the boundary layer between the conductor ecosystem and the external world.

Copy and paste this prompt into Claude Code to begin implementing A2A External Agent Interoperability. It references the architecture, protocols, and integration points defined in this PRD.

Build the A2A External Agent Interoperability system (PRD 17) for the
conductor plugin ecosystem.

## Context
38 agents operate in a closed loop. No external agents can participate,
no internal capabilities are advertised externally, and multi-platform
orchestration (Claude + Gemini + Codex) uses ad-hoc shell scripting.

## Architecture
Agent Gateway (FastAPI) with three protocol adapters:
- A2A Protocol Adapter: Google A2A spec compliance, Agent Cards, task
  lifecycle (submit/status/result/cancel), streaming, push notifications
- MCP Bridge: expose agents as MCP tools, SSE transport, auto-discovery
- REST API: POST /invoke/{agent}, GET /status/{task_id}, GET /result/{task_id}

## Agent Exposure
- 38 total agents, 15 externally callable
- Internal-only: conductor, conductor-checkpoint, conductor-ciso,
  conductor-pentest-coordinator, conductor-gemini-validator, and others
  that control orchestration or security
- Exposed: builder, architect, QA, doc-gen, code-reviewer, and other
  functional worker agents

## Trust Levels (5-tier authentication)
- Level 5 (local): same-machine, full access, unlimited rate
- Level 4 (remote): authenticated remote, full access, 100 req/min
- Level 3 (bot/n8n): API key auth, limited write, 30 req/min
- Level 2 (external): third-party A2A, advisory agents only, 10 req/min
- Level 0 (unknown): discovery endpoint only, no invocation

## Context Sharing Protocol
Standardized envelope for every cross-boundary request:
- Task payload (agent name, parameters, expected output)
- Governance metadata (session ID, trust level, approval chain)
- Provenance (caller identity, protocol, timestamp)
- Response routing (callback URL or poll configuration)

## Agent Discovery (4 mechanisms, 1 source of truth)
1. Static YAML registry (local file)
2. HTTP discovery endpoint (GET /api/v1/agents)
3. A2A Agent Cards (Google ecosystem)
4. MCP tool list (Claude Code ecosystem)
All derive from capabilities.yaml — single source of truth.

## Key Constraints
- Async-first: all invocations return task_id immediately
- Governance enforced on ALL external requests (same gates as internal)
- Standalone script fallback when gateway is unavailable
- FastAPI framework, configurable port (default 8420)
- All invocations logged to governance audit trail
- No governance bypass for any trust level

## Integration Points
- Dispatches to: Conductor (PRD 2)
- Enforces: Governance (PRD 5), Runtime Security (PRD 11)
- Reports: Agent Economics (PRD 10)
- Reads/Writes: Memory System (PRD 4)
- Publishes: Event-Driven (PRD 13)
- Clients: Telegram Bot, n8n workflows, remote instances

## Requirements
16 requirements (REQ-A2A-001 through REQ-A2A-016). MUST-priority items
are non-negotiable: FastAPI gateway, capability registry, A2A adapter,
MCP Bridge, REST API, trust levels, context envelopes, rate limiting,
governance audit, async dispatch, graceful degradation, and governance
enforcement for external callers.