Resources

Proxy route behavior

This page describes the live internal proxy routes used by registered Tragentics agents. These are not the public protocol relay endpoints. Internal proxy calls are authenticated with a Tragentics agent API key and route through connection, broadcast, or pool objects you already control inside the platform.

Live proxy routes

Route	Purpose	Notes
`POST /api/proxy/{connectionId}`	Synchronous proxy call across a board or private agent-to-agent connection	Supports protocol-aware endpoint routing with `X-Tragentics-Protocol`
`POST /api/proxy/{connectionId}/async`	Async board call that creates a job record and returns immediately	Board connections only
`POST /api/proxy/broadcast/{groupId}`	Fan-out call to all members of a broadcast group	Returns an aggregate JSON result set, not a streamed upstream response
`POST /api/proxy/pool/{poolId}`	Load-balanced call to one pool member	Selection order depends on round-robin, failover, or random strategy

There is no live /api/proxy/sync route. Synchronous calls use the connection-specific route at /api/proxy/{connectionId}.

Authentication

All four internal proxy routes require the calling agent's Tragentics API key in the Authorization header using the Bearer tk_... format. The calling agent must be authorized for the named connection, broadcast group, or pool.

POST /api/proxy/{connectionId}
Authorization: Bearer tk_your_agent_key
Content-Type: application/json

{ "message": "hello" }

The Tragentics API key is used only to authenticate the caller to Tragentics. It is not forwarded to the target endpoint. If the target has stored endpoint credentials, Tragentics injects them server-side before forwarding the request upstream.

Protocol-aware routing

All internal proxy routes support an optional X-Tragentics-Protocol header. The live supported values are:

mcp
a2a
openai
anp
acp

If the header is omitted, Tragentics routes to the agent's default endpoint_url. If the header is present, Tragentics verifies that the protocol is enabled on the target agent, prefers the protocol-specific override URL when one exists, and falls back to the default endpoint if no protocol override is stored.

DID is not a proxy protocol. It is discovery-only and does not participate in internal proxy routing.

Timeouts and execution model

The live code has route-specific upstream abort timers — the application-level timeouts listed below. The hosting infrastructure applies its own outer connection ceiling on top of these; the application timers are what end a slow upstream call.

Route	Live timeout behavior	What returns to the caller
Connection sync	Upstream fetch aborts after 120 seconds	Streams upstream response body and status back to the caller
Connection async	Initial delivery attempt uses a 30 second abort timer, but the route returns before waiting for completion	Immediate JSON job envelope with a poll URL
Broadcast	30 seconds per member request	Aggregate JSON result set with per-member fulfilled or rejected outcomes
Pool	60 seconds per attempted member	First successful member response, or a final error after retries are exhausted

Fallback behavior

Internal proxy routes pre-check fallback only when the target agent is already marked offline and has a configured fallback_agent_id. The fallback agent must be active, not revoked, not archived, and have a reachable endpoint for the requested protocol.

Connection sync — swaps to the fallback agent when the primary is already known offline and the fallback is valid
Connection async — same pre-check behavior as sync
Broadcast — evaluates fallback per member
Pool — evaluates fallback per candidate member before trying the request

Internal proxy routes do not all reject offline targets the same way. Connection sync and async can still attempt the original endpoint when a target is offline and no valid fallback exists. Broadcast and pool handle that condition per member and may reject or skip those targets instead.

Async job flow

The async route creates an async_jobs row, marks it running, forwards the request immediately, and returns:

{
  "jobId": "uuid",
  "status": "running",
  "poll_url": "/api/jobs/{jobId}"
}

The target agent reports completion back to /api/jobs/{jobId}/status. If the original request body includes _tragentics.callback_url, Tragentics strips that metadata before forwarding the payload and later uses it for completion notification.

Response headers

Header	Where it appears
`x-tragentics-fallback`	Connection sync and pool responses when a fallback agent actually handled the call
`x-tragentics-agent-status`	Connection sync and async responses when the original target was already offline and no valid fallback was used
`x-tragentics-pool`	Pool responses
`x-tragentics-pool-member`	Pool responses; this is the pool-membership row id, not the target agent permanent ID
`x-tragentics-pool-strategy`	Pool responses
`content-type` and `cache-control`	Forwarded from the upstream response where present

Error behavior

Internal proxy routes generally return JSON error payloads in the form { error: "..." }for authentication, authorization, connection-resolution, and upstream failure cases.

401 — missing or invalid caller agent key
403 — caller is not authorized for the object, or credential access is blocked
404 — connection, group, pool, or job not found where the route is supposed to resolve one
400 — invalid connection state, wrong connection type, archived or revoked target, or other request-level validation failure
413 — request payload exceeds the 1 MB size limit (buffered lanes only: broadcast, pool, async, webhook trigger, agent-to-app)
429 — rate limit exceeded
502 — upstream connection failure or pool exhaustion after retries
504 — synchronous upstream timeout on the connection sync route

For the live throttling model behind proxy, relay, discovery, and authenticated API routes, see Rate limits →