Sixty seconds: card + task handler

Start with the Agent contract and host guide. The integration below assumes AssistantAgent is your declared contract and AgentBuilder is its application-specialized builder. agentRuntime is the result of binding that contract to your live host and verified principal.

Generate the static Agent Card from the contract:

import { AgentA2a } from 'foldkit-agent-a2a'

const card = AgentA2a.agentCard(AssistantAgent, {
  name: 'Todos',
  description: 'A todo list',
  url: 'https://todos.example/a2a',
  securitySchemes: {
    bearer: { type: 'http', scheme: 'bearer' },
  },
  security: [{ bearer: [] }],
})

Serve it from AgentA2a.AGENT_CARD_PATH (/.well-known/agent-card.json). Generating the card starts no HTTP server. Its security declaration describes your endpoint; your HTTP layer must authenticate requests and bind the principal.

Then serve task calls through the bound runtime:

const served = AgentA2a.handler({ agent: agentRuntime })

await served.handle({
  jsonrpc: '2.0',
  id: 1,
  method: 'message/send',
  params: {
    message: {
      kind: 'message',
      role: 'user',
      messageId: 'm-1',
      parts: [
        {
          kind: 'data',
          data: {
            skill: 'delete_todo',
            input: { id: 'todo-1' },
          },
        },
      ],
    },
  },
})

Call served.close() when the host shuts down. The handler keeps tasks in memory; it is not a durable workflow store or a replacement for the application journal.

One A2A skill maps to one exposed capability. The request still goes through the same runtime checks as WebMCP, MCP, Agent Native, or an in-process caller.

Static card, dynamic application#

An Agent Card is static metadata, while Foldkit capability availability may depend on the current Model.

The card therefore describes declared capabilities, not a promise that every skill can run in every Model state:

• a capability with available(model) is tagged conditional;
• a capability with authorize is tagged authorized;
• both are still checked against the live runtime at invocation time.

This preserves the contract's dynamic authority boundary without making the published Agent Card depend on one transient Model snapshot.