Skip to content

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:

  1. Register every exchange once, with its URL, tags and metadata.
  2. Discover: POST /discover filters 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 its matching_subject_ids.
  3. 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

Back to overview · Next: 2. Posting Work →