A2A Integration Playbook
Connect your agent to AGNT's agent-to-agent protocol — from first handshake to production E2E tests.
Why this playbook
A2A (Agent-to-Agent) is the protocol that lets AGNT agents talk to external agents — yours included. It handles booking requests, availability checks, and cross-platform actions via structured envelopes with built-in retry logic.
Most A2A integration failures come from three sources: malformed envelopes, missing required fields, and timeout handling. This playbook walks you through the protocol from first principles, then builds production tests that catch all three failure modes.
If you're building a travel agent, a concierge bot, or any service that needs to book venues through AGNT, this is your starting point.
Prerequisites
- AGNT API key with A2A scope enabled
- Working knowledge of REST APIs and JSON schemas
- Claude Code or Codex CLI installed
- A local development environment (Node.js or Python)
Input requirements
| Input | Type | Required | Description |
|---|---|---|---|
| AGNT API key | string (Bearer token) | Yes | API key with A2A scope. Request A2A access from the developer dashboard if not already enabled. |
| Agent identifier | string | Yes | A unique identifier for your agent (e.g., 'my-concierge-bot'). Used in envelope headers for routing and logging. |
| Target language | string | No | TypeScript (default) or Python. Determines which SDK and test framework the prompts generate code for. |
Step-by-step workflow
Authenticate and explore the API surface
Open promptBefore diving into A2A, you need working API authentication and an understanding of AGNT's data shapes. This prompt scaffolds auth and makes exploratory calls to venues and bookings.
Pay attention to the venue response format — the `booking_methods` field tells you which venues support A2A vs direct booking. You'll filter for A2A-capable venues in step 2.
Build and debug A2A envelopes
Open promptThis prompt teaches the A2A envelope format by building one from scratch. You'll construct a booking request envelope, send it to AGNT's sandbox endpoint, and inspect the response — including the circuit breaker state and retry headers.
The prompt generates a reusable envelope builder function that handles serialization, required field validation, and response parsing. This becomes the foundation for your production integration.
Write end-to-end A2A integration tests
Open promptThe final step generates a comprehensive test suite that validates the full A2A lifecycle: send request → receive acknowledgment → poll for result → handle success/failure/timeout.
Tests cover the three most common integration failures: malformed envelopes (caught at send time), missing required fields (caught at validation), and timeouts (caught with exponential backoff). Run these in CI to catch regressions before they hit production.
Expected outputs
API client with auth
Authenticated API client with venue search and booking method filtering.
Produced by step 1A2A envelope builder
Reusable envelope construction function with validation, serialization, and response parsing.
Produced by step 2A2A E2E test suite
Integration tests covering the full A2A lifecycle with timeout, retry, and failure handling.
Produced by step 3Tool requirements
- Claude Code or Codex CLI
- AGNT API key (free tier)
- Node.js 20+ or Python 3.11+
Troubleshooting
Envelope rejected with 'invalid_schema' error
Sandbox returns 503 during peak hours
Circuit breaker trips after 3 failed requests
Share as social post
A2A Integration Playbook 3 steps, 60-90 minutes. Connect your agent to AGNT's agent-to-agent protocol — from first handshake to production E2E tests. https://agntdot.com/playbooks/a2a-integration-playbook
206 / 280 chars