a2a-service

Agent-to-Agent (A2A) protocol service implementing Google's A2A specification (v0.3.0). Provides a discoverable agent card and a JSON-RPC endpoint that proxies chat requests to the BFF chat service, enabling external AI agents to interact with CROW's analytics engine.

Worker name: crow-a2a-service Domain (prod): a2a.crowai.dev Domain (dev): dev.a2a.crowai.dev

Architecture

The service acts as a thin A2A protocol adapter. When an external agent sends a task via JSON-RPC, the CrowAgentExecutor forwards the user message to the BFF chat service (/a2a/tasks/send), which runs the agentic loop with tool calls, and returns the response as an A2A artifact.

External Agent --> A2A Service (JSON-RPC) --> BFF Chat Service --> Gateway API

The service uses the @a2a-js/sdk library with DefaultRequestHandler, InMemoryTaskStore, and JsonRpcTransportHandler to handle protocol serialization and task lifecycle.

Agent Card

The agent card is served at /.well-known/agent-card.json and describes the agent's capabilities:

Field	Value
name	CROW A2A Agent
protocolVersion	0.3.0
version	0.1.0
url	{BASE_URL}/a2a/jsonrpc
pushNotifications	false
defaultInputModes	["text"]
defaultOutputModes	["text"]

Skills

Skill ID	Name	Description	Tags
chat	Chat	Chat with the agent	chat

Additional Interfaces

URL	Transport
{BASE_URL}/a2a/jsonrpc	JSONRPC
{BASE_URL}/a2a/rest	HTTP+JSON

Routes

Method	Path	Description
GET	/	Health text response
GET	/health	JSON health check
GET	/.well-known/agent-card.json	A2A agent card (discovery)
POST	/a2a/jsonrpc	A2A JSON-RPC endpoint (task execution)

JSON-RPC Endpoint

The /a2a/jsonrpc endpoint accepts standard JSON-RPC 2.0 requests. The transport handler supports both synchronous JSON responses and streaming SSE responses (when the handler returns an async generator).

Streaming response headers:

• Content-Type: text/event-stream
• Cache-Control: no-cache
• Connection: keep-alive

Error codes:

• -32700 -- Parse error (invalid JSON body)

Authentication

The service authenticates outbound requests to the BFF chat service using the INTERNAL_GATEWAY_KEY secret, sent as the X-API-Key header. Inbound requests from external agents are not authenticated at the service level (the BFF chat service validates the key).

The organizationId is passed via message metadata from the external agent.

Environment Variables

Variable	Example
ENVIRONMENT	dev
BASE_URL	https://dev.a2a.crowai.dev
AI_GATEWAY_ID	crow-ai-gateway
BFF_CHAT_URL	https://dev.internal.chat.crowai.dev

Secrets

Secret	Purpose
INTERNAL_GATEWAY_KEY	Authenticates requests to BFF chat service

Bindings

Binding	Type	Purpose
AI	Workers AI	Bound but not directly used by the service (available for future use)

Dependencies

• Inbound: external AI agents, dashboard integrations page
• Outbound: BFF chat service (/a2a/tasks/send)

Key Behaviors

• Stateless task store: Uses InMemoryTaskStore -- tasks are not persisted across requests
• Protocol compliance: Implements A2A protocol v0.3.0 with JSON-RPC transport
• Error resilience: Falls back to a default greeting if the BFF chat service is unreachable
• SSE streaming: Supports streaming responses via Server-Sent Events when the executor produces an async generator

Deployment

cd a2a-service
npx wrangler deploy          # prod
npx wrangler deploy --env dev  # dev