Skip to main content
You need a running A2A agent and its agent card URL. Bifrost must be able to reach both the card and the endpoints advertised in it. We used our library-research agent, which answers questions about software libraries, for these screenshots. Follow the steps with your own A2A agent and replace the example name, domain, and credentials with yours.

​
Register in the dashboard

1

Open the Agent Catalog

Open Agents → Agent Catalog and select New Agent.Give the registration a name such as library-research. Use lowercase letters, digits, and single hyphens. The name becomes part of the gateway URL.
For gRPC, agent names must be 63 characters or fewer because the name becomes a DNS label, such as library-research in library-research.a2a.example.com. Longer names can still use JSON-RPC and REST.
2

Fetch the agent card

Enter the complete agent card URL, including the path to the card, for example https://research.example.com/.well-known/agent-card.json. The base URL alone, such as https://research.example.com, is not enough. Select Fetch.
Before selecting Fetch, expand Card fetch options and enter the credentials required to read the card. Bifrost uses these credentials for card discovery. Configure credentials for sending work separately under Request authentication.
The preview shows the agent’s skills, interfaces, capabilities, and advertised authentication. Check that this is the agent you intended to register.
New agent registration with separate card fetch and request authentication controls
3

Check request authentication

The card’s requirements select the request authentication fields. Fill in the credentials your agent expects.

​
Authentication options

  • Configure manually lets you override an inaccurate card or choose a different authentication setup. Use TLS and certificates for a private CA or mutual TLS.
  • Forward Bifrost authentication passes the caller’s credentials to agents that use Bifrost for LLM or MCP calls. Enable it and configure your agent to reuse those credentials on its model and tool requests to preserve caller attribution.
The authentication guide explains auto-selection, overrides, and what happens when two credentials use the same header.
Card-selected Authorization header authentication with TLS and credential forwarding controls
4

Grant access and create

Select the virtual keys allowed to call the agent. Leave Allow any virtual key off for a restricted agent, or turn it on to allow identified callers without an explicit agent grant.Expand Advanced if you need to allow extension URIs for your A2A integration. Leave them empty for a basic registration. See Advanced registration options for their behavior.Select Create, then reopen the registration to copy its gateway endpoints. Point your client at the Bifrost agent card, rather than the original server card, so discovery returns the gateway routes.
Agent grants restrict authenticated callers. Enable inference authentication enforcement for a deployment that must reject anonymous calls. See access control.

​
Check your registered agent

Your agent appears in Agent Catalog after registration. Reopen it to review its access and copy the gateway endpoints.
A registered research agent in the Agent Catalog with one virtual-key grant
Open the agent’s action menu and select Edit. Under Gateway endpoints, use the copy button beside Agent card, JSON-RPC, REST, or gRPC. Give your client the gateway’s agent card URL for discovery, or the endpoint for its chosen transport.
Each request to the gateway’s agent card URL fetches the current card from your agent server, using the configured card-fetch authentication. Bifrost rewrites its endpoints and authentication requirements for gateway access before returning it. It does not return a cached registration-time card. If your server cannot provide the card, the request fails.
The edit form's Gateway endpoints section with copy buttons for the agent card and each transport

​
Register from deployment configuration

Add an agents entry to your configuration:
The virtual key must already exist or be declared in the deployment. Use its ID here, not its secret value. A runtime credential is only needed if your agent requires one.
Declarations reconcile by registration name at startup. Under the default split source of truth, removing an entry from the file does not delete its stored registration. With source_of_truth: "config.json", a present agents list is authoritative. See source of truth before mixing file and dashboard changes.
The API reference documents registration and card inspection endpoints. Management requests use dashboard or API authentication; that is separate from the credential used to call an agent.PUT /api/agents/{name} replaces the registration. Include the settings and collections you intend to keep. Omitting authentication, extension URIs, or virtual-key IDs can remove them. The registration name stays fixed; use a new registration if you need a different route name.

​
Make your first request

Use a virtual key granted access to this registration:
Then send a message over JSON-RPC. This example uses A2A v1 method names and JSON field names.
The agent may return a message or a task. See Messages, tasks, and events to continue the conversation or follow a task’s progress.

​
Advanced registration options

A2A extensions describe extra protocol behavior identified by a URI. Allow the extensions your integration needs and the agent supports in agents[].extension_uris. Your client must still request the extension through A2A negotiation. Adding an arbitrary URI does not implement it.If the card declares a required extension you have not allowed, registration or discovery can fail. A request for an unsupported extension is rejected before its protocol operation reaches the agent. Registration accepts at most 32 extension URIs, with each URI at most 2048 bytes; negotiated extension payloads are limited to 64 KiB.
Next, review Authentication for card fetching, agent credentials, and caller forwarding. Then configure Agent access for your callers.