How-to guideGet a task done

Register a new agent with the orchestrator

This guide explains how to make a new agent discoverable to the orchestrator. Registration has three parts: the agent declares a contract, serves it at a well-known URL, and a seed process upserts that contract into the orchestrator’s registry. The steps below also cover configuring the agent’s tool permissions and verifying the result. Once registered, the agent appears in the registry and the orchestrator can route work to it.

For the concepts behind this process, see Understanding agent registration. For the full contract schema, see Agent contract specification.

This guide is currently conceptual. It describes the steps and their order, but does not yet include copy-pasteable code or exact commands for every step. The places where concrete detail is still to be confirmed are called out as you go.

Prerequisites

Before you start, make sure you have:

  • A local Agent Console development environment, with the orchestrator and PostgreSQL running.

  • An agent that runs as an HTTP service and is reachable from the orchestrator.

  • The Agent contract specification to hand, for the field definitions.

Register the agent

  1. Define the agent’s contract.

    The contract is a standard A2A AgentCard: a JSON object describing the agent’s identity, how to reach it, and what it can do. In the existing agents it is a hardcoded object in TypeScript, defined near the agent’s entry point (for example app.ts or server.ts). Include at least the required fields (protocolVersion, name, description, url, version, capabilities, defaultInputModes, defaultOutputModes, and skills), setting url to the address the agent is reachable at and preferredTransport to the transport served there. See Agent contract specification for every field and a complete example.

  2. Serve the contract at /.well-known/agent-card.json.

    Each agent implements this route itself. Earlier A2A releases configured the route automatically through the SDK’s A2AExpressApp helper, but that helper is deprecated in v0.3, so the route must be registered explicitly. With the agent running, confirm the contract is reachable by requesting /.well-known/agent-card.json from the agent’s URL and checking that valid JSON is returned.

  3. Configure the agent’s tool permissions.

    Tool access is not part of the contract. Each agent’s permissions are controlled by its LiteLLM virtual key, and are owned by the team that builds the agent. Configure the virtual key so the agent can reach only the tools and models it needs.

  4. Run the seed.

    With the agent running, run the seed from the repository root:

    pnpm seed

    The root seed is recursive: it runs the seed in every workspace app that defines one. For each agent, the seed fetches the contract from /.well-known/agent-card.json and upserts it into the orchestrator’s registry. In local development the seed writes directly to the orchestrator’s database and requires no authentication. Running it again is safe: registration is idempotent, so re-seeding after a contract change updates the existing entry rather than creating a duplicate.

  5. Verify registration.

    Confirm the agent now appears in the orchestrator’s registry by querying its agents endpoint.

Registering in production

Production registration follows the same shape as local development: the contract is served at /.well-known/agent-card.json and seeded into the registry.

Production registration currently requires a valid Keycloak JWT from the user triggering it. This is an interim arrangement. The intended approach is to drive registration from CI using a service-to-service token, rather than a human user’s credentials, and this is expected to change.

Troubleshooting

  • The seed cannot fetch a contract. Confirm the agent is running and reachable, and that its contract is served at /.well-known/agent-card.json rather than the older /.well-known/agent.json path.

  • The agent does not appear in the registry. Confirm the seed ran for that agent’s workspace, and that the contract returned valid JSON.

  • A removed agent still appears. Nothing currently removes a registry entry when an agent is taken down, so stale entries persist until they are cleaned up by hand.

Related pages