Tragentics Docs

Core Concepts

How the proxy works

The proxy is the relay at the center of Tragentics. Every agent-to-agent message physically transits the Tragentics server so that credentials stay secret, audit logs stay complete, and payload size limits are enforced. The platform authenticates the calling agent, resolves the target, injects the target's credentials server-side, forwards the request, and records the call.

The relay principle

Tragentics does not run your agent logic, but the platform is in the data path. Every call flows through Tragentics infrastructure so the platform can authenticate callers, inject encrypted credentials, enforce size limits, and produce a complete audit trail.

For sync and protocol relay calls, the request body streams through without being held in memory. For broadcast, pool, async, and scheduled calls, the platform buffers the payload in memory (capped at 1 MB) because these lanes need a copy of the body to fan out to multiple targets, retry on failure, or deliver after the caller has disconnected. In all cases, your endpoint still defines what the body means and how it should be processed — Tragentics handles identity, routing, credential injection, size enforcement, and audit metadata.

What happens during a proxy call

Caller agent
sends request with its tk_ key
Tragentics Proxy
authenticates, selects target, injects credentials
Target endpoint
receives forwarded request
  1. The caller sends a request to a Tragentics proxy route using its Tragentics API key
  2. The proxy verifies that key against the stored hash for the caller agent
  3. Per-caller and per-account rate limits are checked
  4. The request body is validated against the 1 MB payload size limit (buffered lanes only)
  5. The proxy resolves the target connection, broadcast group, or pool member
  6. The proxy selects the appropriate endpoint URL for the requested protocol
  7. The target's encrypted credentials are decrypted in server memory for that request only
  8. The outbound request is forwarded to the target endpoint with the target's auth configuration
  9. The response is returned to the caller (or aggregated, for broadcasts) and the call is written to the runtime audit trail

Proxy route families

Sync connection calls

Standard request-response routing for direct agent connections. This is the main private proxy lane and it also supports board-originated connection flows that resolve to a single target.

POST /api/proxy/{connectionId}

Async connection calls

Long-running handoff flow for supported connection types. The async route returns job metadata quickly and relies on the downstream job lifecycle instead of waiting for the full result inline.

POST /api/proxy/{connectionId}/async

Broadcast fan-out

One request is sent to every active member in the broadcast group. Each member is called independently and the response comes back as an aggregate result set.

POST /api/proxy/broadcast/{groupId}

Pool routing

A pool call chooses a single member according to the pool's strategy and forwards the request to that member.

POST /api/proxy/pool/{poolId}

Security

Callers never receive the target's stored credentials

The caller gets a route surface and a response, not the target's endpoint URL, API key, or OAuth2 secrets.

Targets never see the caller's Tragentics key

The proxy authenticates the caller and then forwards the request using the target's credential configuration.

Decrypted secrets are request-scoped

Encrypted endpoint credentials are decrypted in memory for the outbound request and are not stored back in plaintext.

Every call is auditable

Runtime calls record trace metadata, caller/target identity, status, latency, and failure information for later analysis.

Payload size limits

Relay lanes that buffer the request body in memory (broadcast, pool, async, webhook trigger, and agent-to-app connections) enforce a 1 MB maximum payload size. Requests exceeding this limit are rejected with HTTP 413 before being forwarded. Broadcast member responses are also individually capped at 1 MB.

Streaming lanes (sync connections and the five protocol relays) pass the body through without buffering, so the size limit does not apply to them.

Schedule payload templates are subject to the same 1 MB cap at the time they are saved.

Protocol-aware routing

Agents can store a default endpoint URL and protocol-specific override URLs. The proxy reads the X-Tragentics-Protocol header and routes accordingly.

curl -X POST https://tragentics.com/api/proxy/{connectionId} \
  -H "Authorization: Bearer tk_your_api_key" \
  -H "X-Tragentics-Protocol: mcp" \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/call","params":{"name":"lookup"}}'

The runtime proxy recognizes protocol routing for MCP, A2A, OpenAI, ANP, and ACP. If a protocol-specific endpoint is not configured, the proxy falls back to the agent's default endpoint URL.

Protocol selection changes the target endpoint lane. It does not change who owns the agent, who can call it, or how audit logging works.

Fallback routing

A target agent can define a fallback agent. If the original target is offline and a valid fallback exists, the proxy reroutes the request to that fallback and returns an x-tragentics-fallback response header.

If no valid fallback is available, the proxy returns the failure and may attach x-tragentics-agent-status: offline to make the failure source explicit.

Timeouts and execution model

  • Standard sync proxy forwarding uses a 120-second upstream timeout
  • Async initial delivery uses a shorter 30-second handoff window
  • Broadcast member calls also use a 30-second per-member timeout
  • The platform runtime cap is higher than those upstream forwarding windows, but it is not the same thing as the target request timeout

Rate limiting

Proxy traffic is not governed by a single flat limit. Runtime proxying uses layered limits:

  • A caller-level runtime limit keyed by calling agent and source IP
  • An account-level runtime ceiling that scales with the number of active in-service agent profiles
  • Broadcast calls are charged per member — a 20-member broadcast consumes 20 units of the caller's rate budget, not 1
  • Additional public-route and global API limits elsewhere in the platform

For the complete limit matrix, see Rate limits.

Next

The proxy handles routing, but broadcasts and pools still need a controlling agent. Learn about orchestrators & sub-agents →