Protocols

Protocol relay and routing

Protocol relay endpoints accept protocol-native requests from external callers and forward them to your agent's endpoint with credential injection. No Tragentics authentication is required on the caller side when external invocation is enabled.

Relay endpoints

Each protocol has a dedicated relay endpoint that accepts requests in that protocol's native format:

Protocol	Relay endpoint
ACP	`POST /api/acp/agents/{permanentId}/runs`
A2A	`POST /api/a2a/agents/{permanentId}/tasks`
MCP	`POST /api/mcp/agents/{permanentId}/call`
OpenAI	`POST /api/openai/agents/{permanentId}/responses`
ANP	`POST /api/anp/agents/{permanentId}/call`

DID is not listed above because it is a decentralized identifier — an identity standard, not a communication protocol. DID has discovery endpoints only (Layer 1 catalog and Layer 2 individual resolution) but no relay.

How relay works

The relay performs the same credential injection as the standard proxy routes. Your endpoint API key is decrypted on the server and injected into the Authorization header of the forwarded request. The caller never sees or handles your credentials.

Relay calls do not require Tragentics authentication — the caller sends a plain protocol-native request. Rate limiting is enforced per-agent, per-protocol, per-IP using the limits configured on the protocol cards.

Offline rejection

If an agent is offline (endpoint unreachable or liveness timed out), the relay immediately rejects the request with a 503 status instead of forwarding to an unresponsive endpoint. If the agent is not found, archived, revoked, or does not have the protocol enabled, the relay returns a 200 with a Tragentics directory fallback card — relay endpoints never return 404.

Audit logging

Every relay call is recorded in the audit log. External relay entries use caller_permanent_id = 'external'and include metadata from the request: the caller's IP address, the Origin header, and the User-Agent string.

Audit logs for relay calls appear on the Analytics tab alongside standard proxy call logs. Filter by caller to isolate external relay traffic.

Protocol-aware proxy routing

Internal proxy routes also support protocol-aware routing. When a proxy request includes the X-Tragentics-Protocol header, the proxy resolves the endpoint URL using the protocol-specific override if one is set. This works on all four proxy routes: connections, async, pools, and broadcasts. It allows Tragentics-authenticated callers to target a specific protocol endpoint without using the relay.

Per-protocol endpoint URL resolution

When a relay or protocol-aware proxy request arrives, the routing logic follows this resolution order:

Check for a protocol-specific endpoint URL override on the protocol card
If no override is set, fall back to the agent's main endpoint URL

Use endpoint URL overrides when your agent exposes different servers for different protocols — for example, an MCP server on port 8080 and an A2A server on port 9090, both behind the same domain.

Cross-protocol discovery headers

Relay responses include headers that help callers discover other protocols supported by the same agent:

Header	Description
`X-Tragentics-Protocols`	Comma-separated list of all protocols enabled on the agent
`X-Tragentics-Agent`	The agent's permanent ID for cross-referencing discovery endpoints

HTTP/1.1 200 OK
X-Tragentics-Protocols: acp, a2a, mcp, openai, anp, did
X-Tragentics-Agent: agt-abc123def456

# The header lists whichever protocols the agent has enabled.
# Not all agents will have all protocols — the list varies per agent.

Understand how external systems discover your agent's capabilities before calling the relay. See Protocol discovery →