Networks & Routing
Agent pools
An agent pool routes each request to a single member based on a strategy — round-robin, failover, or random. Unlike broadcasts (which fan out to all members), pools select one member per call, providing load balancing and redundancy.
What is a pool
A pool has one orchestrator agent and one or more memberagents. When the orchestrator calls the pool endpoint, the platform selects a single member to receive the request. Which member is selected depends on the pool's routing strategy.
How a pool call is triggered
Tragentics does not schedule or initiate pool calls. The orchestrator is a running agent — a piece of code you own and operate. That code contains whatever logic decides when to call the pool: a timer, an incoming request, a processing event, or any other condition. When that condition is met, the orchestrator calls the Tragentics pool endpoint with its tk_... token and the payload. Tragentics selects a member and routes from there. The decision to call the pool always originates in your code — never in the platform.
Creating a pool
Open the Pools tab
Navigate to an agent's manage page and select the Pools tab. Click Create Pool.
Configure the pool
Enter a name, select a network, choose the orchestrator agent, and select a routing strategy (round-robin, failover, or random).
Add members
Add member agents to the pool. Member order matters for round-robin and failover strategies. Drag to reorder members to set the desired sequence.
Round-robin strategy
Round-robin cycles through members sequentially. The first call goes to member 1, the second to member 2, and so on. After the last member, it wraps back to member 1. An atomic position counter tracks the current position — concurrent calls are distributed evenly without collisions.
Member position determines the order. Reorder members in the Pools tab to change the cycling sequence. The position counter resets if a member is added or removed.
Failover strategy
Failover tries members in position order until one succeeds. The first member (position 1) is the primary — every request goes to it first. If it fails (timeout, error, or offline), the proxy tries member 2, then member 3, and so on until a member responds successfully or all members have been tried.
Random strategy
Random selects a member at random for each call. Every member has an equal probability of being selected regardless of position. Member order has no effect on selection — useful when all members are equivalent and you want simple load distribution without the predictability of round-robin. If the randomly selected member is unavailable, the proxy continues through the shuffled list until a member responds or all have been tried.
Adding and reordering members
Add members from the Pools tab — your own agents can be added directly, and external agents can be invited by permanent ID. Drag the grip handle to reorder members. Position matters for round-robin (cycling order) and failover (priority order). For random pools, position has no effect on selection.
Making a pool call
This call comes from within your orchestrator agent's running code — not from the dashboard, not from a browser. When your orchestrator's logic decides it's time to route a request, it fires this call using its own tk_... registration token and the pool ID you copied from the dashboard.
POST /api/proxy/pool/{poolId}
Authorization: Bearer tk_orchestrator_api_key
Content-Type: application/json
{"task": "Process this request"}The selected member's response is streamed directly back to your orchestrator — there is no aggregation. You receive exactly one response, from exactly one member, as if you had called that member directly. The response headers tell you which member handled the request and what strategy was used.
Response headers
Pool responses include headers that tell the caller which member handled the request and what strategy was used.
| Header | Description |
|---|---|
| x-tragentics-pool | The pool ID that handled the request |
| x-tragentics-pool-member | The permanent ID of the member agent that received the call |
| x-tragentics-pool-strategy | The routing strategy used (round-robin, failover, or random) |
| x-tragentics-fallback | Present if a fallback agent handled the request instead of the selected member |
Fallback within pools
Pool members can have individual fallback agents configured. When a pool selects a member that is offline, the proxy first checks if that member has a fallback. If it does, the fallback handles the request. If no fallback is configured (or the fallback also fails), the pool moves to the next member according to the strategy.
Testing pool calls
Each pool has a Test button in the Pools tab. Enter a JSON payload and your API key to send a test call. The response shows which member was selected, the strategy used, and the full response — helpful for verifying routing behavior before production use.
Pools on the Canvas
Pool edges use a dotted line style with a layers icon. Each member edge displays the member's position number, making the routing order visible at a glance.
Limits
- Maximum 20 members per pool
- Request payload capped at 1 MB — the platform holds the request body in memory so it can retry against the next member on failure; requests over the limit are rejected with HTTP 413
- The selected member's response is streamed back to the caller without buffering — no response size limit applies
- Per-member upstream timeout of 60 seconds
Next
Automate agent calls on a schedule. See Scheduled calls →