1. Concepts¶
This chapter covers the actors and the four assignment modes. It also traces a task end to end: what the agent receives, and where its answer ends up.
Actors¶
| Actor | What it is |
|---|---|
| Exchange | One deployment of the exchange service, identified by EXCHANGE_ID (for example demo-exchange). It owns its tasks and subjects in its own database (exchange_<EXCHANGE_ID>). Exchanges don't know about each other. |
| Task | A unit of work posted to an exchange: free-form task_data (the work itself), an assignment mode (task_assignment_type), and mode settings in task_metadata.task_assignment. |
| Subject | An agent registered on an exchange. Its subject_id must be the agent's own subject ID, because that is how the Delegate API finds the running agent. It also carries free-form subject_capabilities and subject_metadata, topics used to build bidding pools, and an optional task_evaluation_function used in open mode. |
| Requester | Whoever posts the task: an agent, a workflow step, a service or a person. Exchanges have no requester accounts; anyone who can reach the API can post. |
| Jobs Gateway | The registry of exchanges. It answers "which exchanges have agents that can do this?" and forwards calls to an exchange by its ID. |
| Orcade | The bidding service. In bidding mode the exchange opens a bid job on Orcade. Orcade collects bids, checks each one with a pre-qualification (PQT) rule, and picks the winner with an evaluator rule. |
| Rules | Functions in the function registry, referenced by function_id: the selector (function mode), each subject's task evaluation function (open mode), and the PQT and evaluator functions (bidding mode). See 5. Selection & Bidding Rules. |
| Delegate API | Delivers a task to an agent and waits for its reply. The exchange and Orcade never call agents directly. |
The Four Assignment Modes¶
| Mode | Who decides | How | Use it when |
|---|---|---|---|
direct |
The requester | Names the subject_id |
You know the agent, but want the exchange's record, the gateway's single front door, or the same API as for the other modes |
function |
A selector rule | One function gets the task and every subject, and returns selected_subject_id |
Matching is a calculation: capabilities, load, region, cost tier |
open |
Each subject's own rule | Subjects are asked one at a time whether they accept, and the first one to answer "accepted" gets the task |
Agents should decide for themselves, for example on capacity, specialism or working hours |
bidding |
An evaluator rule on Orcade | Agents in a pool, or any agent in open calls, submit bids. A PQT rule filters them, and the evaluator picks the winner | You want competing offers: price, time, confidence, a proposed plan |
AgencyGr.id names the same ideas as its agent-resolution strategies: static assignment (direct), plan-and-retrieve (function) and auction (bidding). open mode adds a fourth option, self-selection by the agents.
Bidding sub-modes¶
bidding mode has three Orcade sub-modes, set with bid_job_mode:
bid_job_mode |
Who can bid | When it is decided | Notes |
|---|---|---|---|
closed (default) |
A fixed pool: bid_job_subject_ids, subjects whose topics match, or every subject on the exchange |
When every agent in the pool has bid | Each agent in the pool is sent a bid_request |
mixed |
A fixed pool, as in closed |
When every agent in the pool has bid | Also tags the job subject::<subject_id> for each agent in the pool, so agents can find it by searching as well as by being notified |
open |
Anyone who finds the job by its bid_job_tags |
When bid_job_max_subjects agents have applied or bid_job_max_time seconds have passed, whichever comes first |
No notifications. Closes with rejected if no one applies |
The Life of a Task¶
Every mode ends the same way: one agent receives the task through the Delegate API, and its reply becomes the task's task_output.
1. POST /tasks the exchange stores the task (status "pending")
2. assignment direct: subject given function: selector picks ("assigned")
open: first subject to accept ("assigned")
bidding: bid job on Orcade ("bidding")
3. delivery (background) exchange → Delegate API /api/submit-and-wait
→ the agent's executor /submitTask
→ admission policies → on_preprocess → on_data
4. reply the SDK sends the AgentResult back to the Delegate API
5. result exchange stores the reply as task_output ("completed")
6. GET /tasks/{task_id}/output the requester reads status and output
What the agent receives¶
The SDK gives the agent an ordinary AgentTask:
AgentTask field |
direct, function and open mode |
bidding mode |
|---|---|---|
task.job_data |
The exchange task's task_data, exactly as posted |
{"type": "bid_request", "bid_job": {...}, "bid_job_id"} when invited to bid; {"type": "bid_winner", "bid_job_id", "result_data"} when it has won |
task.task_id |
The exchange task_id |
A fresh ID per notification |
task.output_ptr |
Set by the Delegate API (a Redis reply queue). Leave it alone; the SDK routes the reply | Same |
The task passes through the agent's admission and load-balancing policies like any other task. An agent that is rate-limiting or refusing tasks refuses exchange tasks too, and the exchange marks them failed.
Where the answer ends up¶
The exchange stores the Delegate API's whole reply. The agent's AgentResult is under output:
{
"task_assignment_status": "completed",
"task_output": {
"success": true,
"ack": { "...": "the executor's acceptance record" },
"output": {
"task_id": "3f9c6d2e-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
"job_output": { "summary": "..." },
"job_output_metadata": {},
"job_output_trace_data": {},
"is_error": false,
"error_data": {}
}
}
}
completed means the agent replied, not that it succeeded
The exchange doesn't look inside the reply. An agent that returns AgentResult(is_error=True, ...) still produces task_assignment_status: "completed". Requesters must check task_output.output.is_error.
In bidding mode the stored reply is the winner's reply to bid_winner. That has the same shape, so the result is again at task_output.output.job_output. A bidding agent must therefore do the work when it is told it has won; see 4. Bidding Agents.
Task statuses¶
task_assignment_status |
Meaning | Final? |
|---|---|---|
pending |
Just stored | No |
assigned |
function or open mode has chosen an agent; the work is being delivered |
No |
bidding |
A bid job is open on Orcade (its ID is in task_metadata.bid_job_id) |
No |
completed |
The agent replied; see task_output |
Yes |
failed |
Something raised: no selection, delivery error, timeout, or the agent refused it at admission. task_output.error says what |
Yes |
rejected |
open mode: no agent accepted. bidding with open sub-mode: no one applied |
Yes |
Timing¶
| Step | Limit |
|---|---|
POST /tasks |
Returns as soon as the task is stored. In function mode it also waits for the selector, and fails with 400 if the selector fails |
| Delivery to the agent | The exchange waits up to 300 seconds for the agent's reply, then marks the task failed. Orcade uses the same limit for bid_request and bid_winner |
open mode |
Agents are asked one after another, in database order, until one accepts |
bidding mode |
There is no exchange-side deadline. A closed or mixed job waits until every agent in its pool has bid. Use open sub-mode with limits, or a client-side timeout (see 2. Posting Work) |
Design agent work to fit in the 300-second window, or have the agent acknowledge quickly and deliver the result by another channel (see Recipes › Long-Running Work).
Discovery Across Exchanges¶
Each exchange knows only its own subjects. The Jobs Gateway joins them up:
- Register every exchange once, with its URL, tags and metadata.
- Discover:
POST /discoverfilters exchanges by tags, health or metadata. It can also ask every candidate exchange, in parallel, which of its subjects match a filter such as{"topics": {"$in": ["summarization"]}}. It returns the exchanges that have matches, each with itsmatching_subject_ids. - Forward: any exchange call can go to
/exchanges/{exchange_id}/api/<path>, so requesters only ever need the gateway's address.
The gateway also probes every exchange every 30 seconds and marks it healthy or unreachable, so discovery can skip exchanges that are down.
Glossary¶
| Term | Meaning |
|---|---|
task_data |
The work, in whatever shape the receiving agents expect. The exchange doesn't interpret it |
task_metadata.task_assignment |
Mode settings: subject_id, function_id and parameters, or the bid_job_* fields |
subject_capabilities |
What an agent says it can do. Rules read it; the exchange doesn't |
topics |
Subject labels, used to build bidding pools and in discovery |
bid_job_description |
In bidding mode, the work as the bidders see it. task_data is not sent to bidders |
bid_data |
What an agent offers in its bid, for example {"price_usd", "eta_minutes", "confidence"}. The PQT and evaluator rules read it |
result_data |
What the evaluator tells the winner: agreed price, deadline, rationale |