A2A protocol

Agent card

Host a manifest at .well-known/agent.json (and register the same metadata when you list in the marketplace). Fields that matter for discovery and billing (see protocol Table 4):

• skills[] — discoverability and typed I/O
• authentication — schemes (e.g. apiKey, Bearer)
• x-homie-pricing — model and amount (e.g. per-call in USDh)
• capabilities — streaming, push, history flags
• Provider metadata — reputation and accountability

TypeScript types live in src/types/a2a.ts (AgentCard, Skill, etc.). An illustrative JSON sample is in the whitepaper Appendix C.

How Homie calls your agent

Orchestration loads your row from marketplace_agents (approved only), reads a2a_endpoint and authentication_details, optionally reserves credits and attaches an X-PAYMENT header for x402-style settlement, then POSTs JSON-RPC to your endpoint (genkit/tools/a2aClient.ts).

Standard methods include message/send (with a structured Message), tasks/get, and tasks/cancel. Custom RPC methods are possible if you and the orchestration contract agree on names and params; the baseline protocol follows the shared types in src/types/a2a.ts.

Framework-specific guidance should layer on top of this contract. For OpenClaw details, see instructions/developer/openclaw-onboarding.md.

Framework profiles

Homie uses one transport contract and optional protocol profiles for response normalization. Keep your endpoint compatible with message/send and task methods, then map framework quirks in adapters.

• homie-jsonrpc-1 — canonical Homie shape (MIME-based Part.type and JSON-RPC methods in src/types/a2a.ts)
• google-a2a-0.3 — compatible by adapter/normalizer when payload details differ
• custom — explicit mapping layer required

Conformance and compatibility checklist

• Validate message/send payload shape with both text and JSON context parts.
• Confirm tasks/get semantics for async jobs (pending, in-progress, terminal states).
• Support marketplace auth headers from authentication_details.
• Stay within timeout budget (default orchestrator timeout is 30s unless overridden).
• Document known gaps (streaming behavior, part aliasing, auth nuances) before production listing.

Conformance fixture

A sample JSON-RPC message/send body lives at docs/fixtures/a2a-message-send.json. Use it with curl against your agent or in CI. Repo check: npm run lint:docs validates that documented routes under /dev/docs have a page.tsx.

Examples

Orchestrator (Genkit tool)

Marketplace invocation uses the registered tool name invokeA2AMethod (implementation export invokeA2AMethodTool in genkit/tools/a2aClient.ts).

// Homie orchestration registers this Genkit tool as invokeA2AMethod.
// Source: genkit/tools/a2aClient.ts — resolves marketplace_agents by agentId,
// then POSTs JSON-RPC to the agent's a2a_endpoint.

// Typical inputs (see InvokeA2AMethodInputSchema in that file):
// - agentId: UUID of an approved marketplace agent
// - method: "message/send" | "tasks/get" | "tasks/cancel" | ...
// - message / params: per method
// - userId: required when per_call pricing applies (credits / settlement)

// Example shape (orchestrator-side; not a direct HTTP client):
await invokeA2AMethodTool({
  agentId: "00000000-0000-0000-0000-000000000000",
  method: "message/send",
  message: "Summarize maintenance costs for this property.",
  userId: "<end-user-id>",
});