Get A2A Agent by ID

GET /admin/v1/a2a_agents/{id}

Get A2A Agent by ID

Get an upstream A2A agent resource by ID.

Parameters

• id (path, string, required): A2A agent resource ID, as assigned by the active resource source (a UUIDv5 derived from the entry name in file mode; the etcd key's ID segment otherwise).

Responses

• 200: OK
• id (string, required): Resource ID, as assigned by the active resource source.
• revision (integer, required): Monotonic resource revision: the etcd mod_revision of the entry, or the load generation in file mode.
• value (object, required): Stored upstream A2A agent configuration.
• allOf variant 1
• value.auth_type (object, optional): How the gateway authenticates to the upstream agent. The credential is held by the gateway and is not exposed to the calling client. The one case where the agent sees a caller-supplied credential instead is when forward_client_headers names the slot this auth_type fills, which substitutes the caller's own value for the gateway's rather than sending both.
• allOf variant 1
• oneOf variant 1: No authentication
• oneOf variant 2: Bearer token
• oneOf variant 3: API key
• value.display_name (string, optional): Accepted as an alternative spelling of name. Provide the label under exactly one of the two names.
• value.enabled (boolean, optional): Whether this agent is active. When false, it is not served and cannot be reached.
• value.forward_client_headers (array, optional): Inbound client headers forwarded to this agent, as single-* glob patterns matched case-insensitively against the header name ("x-trace-*", "authorization"). Empty — the default — forwards nothing. Applies to the agent-card fetch at /a2a/<name>/.well-known/agent-card.json as well as to every JSON-RPC method served at /a2a/<name>, so an agent receives them on message/send, message/stream and every task operation alike.

A header the caller sends more than once is forwarded with its first value only; the upstream receives one well-formed header rather than a list this gateway never interpreted. An HTTP/2 caller may split cookie across several header fields, and only the first of them is forwarded.

A header named here reaches the agent whatever the gateway would otherwise do with it. Naming the credential slot auth_type would fill — authorization for bearer, x-api-key for api_key — hands the agent the caller's own credential in place of the gateway's, never both. That is what lets an internal agent that already authorizes on the end user's Authorization keep doing so unchanged. An agent that validates the aud claim will reject a token minted for the gateway.

A credential slot, and traceparent / tracestate, are forwarded only when a pattern names them exactly — a glob such as "*" or "x-*" is a statement about the operator's own headers, not consent to hand a third party the caller's credential or to graft the caller's trace onto that party's telemetry.

Headers whose forwarding would break the exchange rather than change who it comes from are never forwarded whatever the patterns say: host, the hop-by-hop headers that describe the caller's own connection, the gateway's x-aisix-* namespace, the headers describing a body this gateway re-serializes (content-type, content-length, accept), and a2a-version, which is the gateway's own announcement of the wire version pinned in protocol_version and which a caller's value would override.

• value.name (string, optional): Operator-facing label, unique within the gateway. It is the path segment under which the agent is exposed to callers as /a2a/<name>, so it must be a single non-empty URL path segment. The name is interpolated into the advertised agent-card URL without percent-encoding, so /, ?, #, % and whitespace are rejected: a?b would advertise a URL whose path is just /a2a/a, and the lookup is an exact match on the stored name.
• value.protocol_version (object, optional): The A2A wire-format version this agent speaks. AISIX announces it to the agent in the A2A-Version header on every request, so it must match what the agent actually serves: an agent reads an absent or mismatched version as a protocol error and rejects the call.
• allOf variant 1
• oneOf variant 1: A2A 1.0
• oneOf variant 2: A2A 0.3
• value.secret (string,null, optional): Credential AISIX uses to authenticate to the upstream agent. For bearer, AISIX sends it as Authorization: Bearer <secret>; for api_key, AISIX sends it as x-api-key: <secret>. Leave unset for none.
• value.timeout_ms (integer,null, optional): Maximum time, in milliseconds, to wait for a single upstream operation, including fetching the agent card or invoking the agent. When omitted, AISIX applies a built-in default.
• value.url (string, required): The upstream agent's A2A service endpoint, such as https://agents.example.com/a2a, where AISIX sends JSON-RPC 2.0 requests over HTTP. AISIX looks for the agent card at the well-known path under this URL's own path first, then under its origin, so both an agent that owns its domain and one published under a path prefix are reachable without extra configuration.
• allOf variant 1
• allOf variant 2
• anyOf variant 1: name
• anyOf variant 2: display_name
• 401: Missing or invalid admin key
• error_msg (string, required): Human-readable error message.
• 404: Resource not found Response fields (application/json): identical to GET /admin/v1/a2a_agents/{id}, response 401 above.
• 500: Configuration store operation failed Response fields (application/json): identical to GET /admin/v1/a2a_agents/{id}, response 401 above.

cURL

curl -X GET 'http://127.0.0.1:3001/admin/v1/a2a_agents/{id}'