Agent Gateway Protocol (AGP): Practical Tutorial and Specification

Agent Gateway Protocol (AGP) Practical Tutorial

This guide walks you through the Agent Gateway Protocol (AGP)—what it is, the problems it solves, its core specification, and how to run a working simulation. The keyword Agent Gateway Protocol is used throughout to aid discoverability.

What is the Agent Gateway Protocol (AGP)

The Agent Gateway Protocol (AGP) is a hierarchical routing layer for multi-agent systems that enhances the flat A2A mesh by introducing domain-oriented gateways and policy-based routing. Inspired by BGP, the Agent Gateway Protocol routes Intents to squads based on declared Capabilities, costs, and policies, enabling scalable, secure, and compliant orchestration across Autonomous Squads.

• Agent Gateway Protocol emphasizes:
  • Capability announcements from squads
  • Intent routing with policy constraints
  • Cost-aware path selection
  • Hierarchical domains for enterprise-scale organization (e.g., Finance, Engineering, HR)

What problems does Agent Gateway Protocol solve

• Scalability: Flat meshes become noisy and inefficient at scale. Agent Gateway Protocol introduces hierarchical gateways and route aggregation.
• Policy compliance: Sensitive workloads require policy enforcement (e.g., PII handling, security levels, geo). Agent Gateway Protocol matches intents with announced policies.
• Cost optimization: Multiple providers can fulfill the same capability; Agent Gateway Protocol chooses the lowest-cost route that satisfies constraints.
• Robustness: Agent Gateway Protocol defines explicit error codes for missing routes, policy violations, and stale tables to ensure predictable behavior.

Agent Gateway Protocol Specification (Overview)

Capability Announcement

Squads announce the capabilities they provide, including version, cost, and policy.

{
  "capability": "financial_analysis:quarterly",
  "version": "1.5",
  "cost": 0.05,
  "policy": {
    "requires_auth": "level_3"
  }
}

Fields:

• capability (string): function/skill key (e.g., "financial_analysis:quarterly").
• version (string): interface/schema version.
• cost (number, optional): estimated cost metric (USD, tokens, etc.).
• policy (object): key-value policy attributes (e.g., PII, security level, geo).

Intent Payload

Clients express goals and constraints; gateways find compliant routes.

{
  "target_capability": "billing:invoice:generate",
  "payload": {
    "customer_id": 123,
    "amount": 99.99
  },
  "policy_constraints": {
    "requires_pii": true
  }
}

Fields:

• target_capability (string): capability to fulfill.
• payload (object): input arguments.
• policy_constraints (object, optional): client-required constraints to match against announced policies.

Routing Structures

• AGPTable: maps capability → list of RouteEntry.
• RouteEntry fields: path (destination), cost (for selection), policy (for matching constraints).

Agent Declaration in Agent Card

Gateways MUST declare their role and supported versions via the A2A extension mechanism:

{
  "uri": "https://github.com/a2aproject/a2a-samples/tree/main/extensions/agp",
  "params": {
    "agent_role": "gateway",
    "supported_agp_versions": ["1.0"]
  }
}

Error Codes (JSON-RPC)

• -32200 AGP_ROUTE_NOT_FOUND — No announced route for the requested capability.
• -32201 AGP_POLICY_VIOLATION — Routes found, but none satisfy policy constraints.
• -32202 AGP_TABLE_STALE — Routing table is outdated; refresh required.

Detailed Specification (Augmented from spec.md)

CapabilityAnnouncement — Fields and Semantics

Example:

{
  "capability": "financial_analysis:quarterly",
  "version": "1.5",
  "cost": 0.05,
  "policy": {
    "requires_auth": "level_3"
  }
}

Intent — Fields and Semantics

Example:

{
  "target_capability": "billing:invoice:generate",
  "payload": {
    "customer_id": 123,
    "amount": 99.99
  },
  "policy_constraints": {
    "requires_pii": true
  }
}

Routing Data Structures

• RouteEntry
  • path (string): Destination Squad/API path (e.g., Squad_Finance/gateway).
  • cost (number): Cost metric for route selection.
  • policy (object): Destination policies used for constraint matching.
• AGPTable
  • Maps capability → [RouteEntry]. Maintained by the Agent Gateway Protocol gateway from announcements.

Agent Declaration (Agent Card Extension)

Gateways must declare their role and supported Agent Gateway Protocol versions via the A2A extension mechanism:

{
  "uri": "https://github.com/a2aproject/a2a-samples/tree/main/extensions/agp",
  "params": {
    "agent_role": "gateway",
    "supported_agp_versions": ["1.0"]
  }
}

Error Codes (Operational Semantics)

• -32200 AGP_ROUTE_NOT_FOUND: No route for target_capability. Caller may retry later, or issue a discovery/announcement request out-of-band.
• -32201 AGP_POLICY_VIOLATION: Routes exist, but none satisfy policy_constraints. Caller should relax constraints or target a different capability.
• -32202 AGP_TABLE_STALE: Table is outdated. Gateway SHOULD refresh from peers before re-attempting routing; on failure, return error.

Routing Algorithm (Policy-First, Cost-Second)

Agent Gateway Protocol recommends a deterministic selection strategy:

1. Filter candidates by target_capability in the AGPTable. If none, return -32200.
2. Policy sufficiency check per candidate route:
   • Numeric thresholds: candidate.policy.value >= constraint.value (e.g., security_level).
   • Boolean flags: candidate.policy.flag == true when constraint requires it (e.g., requires_PII).
   • Arbitrary attributes: exact match unless domain-specific matcher is defined (e.g., geo).
   • If no candidate satisfies all constraints, return -32201.
3. Among compliant candidates, pick the lowest cost.
4. If the AGPTable is known stale, perform refresh. If refresh fails, return -32202.

Tie-breakers (if multiple minimal-cost routes):

• Prefer most recent announcement, then lexicographical path (stable ordering), unless domain-specific policy defines otherwise.

Table Maintenance and Freshness

• Ingress announcements: Gateways ingest CapabilityAnnouncements from squads/peer gateways.
• Expiry/refresh: Announcements SHOULD include TTL/versioning out-of-band; on expiry, routes are removed and -32202 becomes likelier.
• Partial staleness: Gateways MAY mark individual capabilities stale rather than the entire table to minimize impact.

Security and Compliance Considerations

• Least-privilege routing: Express the minimum necessary policy_constraints in intents; let Agent Gateway Protocol enforce.
• PII/Data residency: Use explicit flags like requires_PII, attributes like geo to restrict routing domains.
• Auditability: Log intent routing decisions, rejected candidates, and returned error codes.

Versioning and Backward Compatibility

• Capabilities carry a version field to stabilize contracts between squads and clients.
• Gateways SHOULD support multiple versions concurrently and favor the newest matching version unless overridden by policy.

Extended Flow (Sequence Diagram)

sequenceDiagram
  autonumber
  participant Client
  participant Gateway
  participant SquadA as Squad A (Eng)
  participant SquadB as Squad B (Vendor)

  Client->>Gateway: Intent(target_capability, payload, policy_constraints)
  Gateway->>Gateway: Lookup AGPTable[target_capability]
  alt No routes
    Gateway-->>Client: Error -32200 (AGP_ROUTE_NOT_FOUND)
  else Candidate routes exist
    Gateway->>Gateway: Filter by policy sufficiency
    alt None compliant
      Gateway-->>Client: Error -32201 (AGP_POLICY_VIOLATION)
    else Some compliant
      Gateway->>Gateway: Choose lowest cost (tie-breakers)
      Gateway->>SquadB: Forward request (if chosen)
      SquadB-->>Gateway: Response / Result
      Gateway-->>Client: Success
    end
  end

Operational Guidance

• Monitoring: Track rates of -32200/-32201/-32202 to detect topology gaps, policy drift, and staleness.
• SLOs: Define routing success latency and freshness budgets; instrument table refresh paths.
• Incident response: On systemic -32202, prioritize table refresh/fan-out; degrade gracefully to safest internal routes when possible.

Frequently Asked Questions (FAQ)

• Q: Is Agent Gateway Protocol a replacement for service discovery?
  • A: No. Agent Gateway Protocol is a policy-aware intent router; it can consume discovery data but focuses on capability/policy semantics.
• Q: How do I add a new domain squad?
  • A: Deploy the squad gateway, publish CapabilityAnnouncements, and ensure upstream gateways ingest them into the AGPTable.
• Q: Can I prioritize security over cost?
  • A: Yes. Encode higher security_level constraints in intents; Agent Gateway Protocol will only consider compliant routes even if more expensive.

Architecture and Flow

flowchart TD
  A[Squads Announce Capabilities<br/>capability, version, cost, policy] -->|build| B[AGP Table]
  C[Client Intent<br/>target_capability, payload,<br/>policy_constraints] --> D[Gateway]
  B --> D
  D --> E{Policy Match?}
  E -- No --> F[Error -32201<br/>AGP_POLICY_VIOLATION]
  E -- Yes --> G{Capability Known?}
  G -- No --> H[Error -32200<br/>AGP_ROUTE_NOT_FOUND]
  G -- Yes --> I{Choose Lowest Cost<br/>Compliant Route}
  I --> J[Forward to Squad Path]
  D --> K{Table Stale?}
  K -- Yes --> L[Refresh Table or -32202]
  L --> D

Code Example and Explanation

The following simulation demonstrates how the Agent Gateway Protocol performs policy-based, cost-aware routing. It initializes the AGP table, announces capabilities for three squads, then routes four intents with different constraints.

Source: extensions/agp/agp_run.py

Initialize routing table and gateway

from agp_protocol import AGPTable, AgentGatewayProtocol

corporate_agp_table = AGPTable()
corporate_gateway = AgentGatewayProtocol(
    squad_name='Corporate_GW', agp_table=corporate_agp_table
)

Announce capabilities

# Engineering Squad (secure, higher cost)
eng_announcement = CapabilityAnnouncement(
    capability='infra:provision:vm',
    version='1.0',
    cost=0.10,
    policy={'security_level': 5, 'requires_PII': True},
)
corporate_gateway.announce_capability(
    eng_announcement, path='Squad_Engineering/vm_provisioner'
)

# External Vendor (cheapest, lower security)
vendor_announcement = CapabilityAnnouncement(
    capability='infra:provision:vm',
    version='1.1',
    cost=0.05,
    policy={'security_level': 3, 'requires_PII': False},
)
corporate_gateway.announce_capability(
    vendor_announcement, path='External_Vendor/vm_provisioning_api'
)

# Finance Squad (standard analysis)
finance_announcement = CapabilityAnnouncement(
    capability='financial_analysis:quarterly',
    version='2.0',
    cost=0.15,
    policy={'security_level': 3, 'geo': 'US'},
)
corporate_gateway.announce_capability(
    finance_announcement, path='Squad_Finance/analysis_tool'
)

Route intents with different constraints

# Intent A — cost-driven, minimal policy
intent_a = IntentPayload(
    target_capability='infra:provision:vm',
    payload={'type': 'standard', 'user': 'bob'},
    policy_constraints={'security_level': 3},
)
corporate_gateway.route_intent(intent_a)

# Intent B — sensitive, requires PII and security level 5
intent_b = IntentPayload(
    target_capability='infra:provision:vm',
    payload={'type': 'sensitive', 'user': 'alice', 'data': 'ssn_data'},
    policy_constraints={'security_level': 5, 'requires_PII': True},
)
corporate_gateway.route_intent(intent_b)

# Intent C — unmatched policy (security level 7)
intent_c = IntentPayload(
    target_capability='infra:provision:vm',
    payload={'type': 'max_security'},
    policy_constraints={'security_level': 7},
)
corporate_gateway.route_intent(intent_c)

# Intent D — unknown capability
intent_d = IntentPayload(
    target_capability='hr:onboard:new_hire',
    payload={'employee': 'Charlie'},
    policy_constraints={},
)
corporate_gateway.route_intent(intent_d)

Expected outcomes:

• Intent A routes to External Vendor (lowest cost, policy OK).
• Intent B routes to Engineering (PII required, vendor rejected).
• Intent C fails with policy violation (-32201).
• Intent D fails with route not found (-32200).

How to Run the Simulation

Prerequisites: Python 3.9+.

Install dependencies (if using Poetry in extensions/agp):

cd extensions/agp
poetry install

Or ensure pydantic is available in your environment (per pyproject.toml).

Run the simulation:

python extensions/agp/agp_run.py

Best Practices for Agent Gateway Protocol

• Treat capability announcements as your control plane; keep them fresh and versioned.
• Encode minimum viable policies in announcements; enforce stricter constraints via client intents.
• Prefer explicit intent schemas per capability version to stabilize contracts.
• Monitor error code rates (-32200/-32201/-32202) to detect drift, policy gaps, or staleness.

Key Takeaways

• Agent Gateway Protocol turns multi-agent routing into a policy-driven, cost-aware, hierarchical system.
• Capability announcements and intent constraints are first-class citizens.
• Explicit errors provide operational clarity at scale.

A2A Extension List

• A2A Traceability Extension
• A2A Timestamp Extension
• A2A Secure Passport Extension
• A2A Agent Gateway Protocol