Skip to content

2. Posting Work

This chapter is for requesters: agents, workflow steps, services or people that want work done through an exchange. It covers: - choosing where to post; - posting in each mode; - waiting for and reading the result; - handling failures.

All exchange endpoints reply with {"ok": true, "data": ...} or {"ok": false, "error": "..."}.


Where to Post

Post either to an exchange directly (http://<exchange>:5000) or through the Jobs Gateway by exchange ID (http://<gateway>:30741/exchanges/<exchange_id>/api). The gateway forwards calls unchanged, so every example below works either way. Using the gateway means requesters only need one address.

Finding an exchange that can do the work

curl -X POST $GW/discover -H "Content-Type: application/json" -d '{
  "status": "healthy",
  "subject_topics": ["contract-review"],
  "subject_query": {"subject_capabilities.languages": {"$in": ["fr"]}}
}'
{
  "ok": true,
  "data": {
    "exchanges": [
      { "exchange_id": "legal-exchange", "exchange_tags": ["legal"], "...": "...",
        "matching_subject_ids": ["contract-reviewer-fr-1", "contract-reviewer-fr-2"] }
    ],
    "unreachable": []
  }
}
/discover field Filters
tags Exchanges with any of these exchange_tags
status Usually "healthy", to skip exchanges that failed their last health check
query Any filter on the exchange record, e.g. {"exchange_metadata.region": "eu-west"}
subject_topics Exchanges with at least one subject whose topics include any of these
subject_query Any filter on subject records, e.g. capabilities

Exchanges are sorted by how many subjects match, most first. Those that couldn't be asked are listed in unreachable, so an exchange with no matching subjects can be told apart from one that couldn't be reached.


Posting a Task

POST /tasks with:

Field Required Meaning
task_assignment_type Yes direct, function, open or bidding
task_data Yes The work, in the shape the receiving agents expect. See Designing task_data
task_metadata.task_assignment Per mode Mode settings (below)
task_id No Your own ID; generated if omitted

The response is 201 with the stored task. Keep its task_id; the result comes later.

direct: a named agent

curl -X POST $EX/tasks -H "Content-Type: application/json" -d '{
  "task_assignment_type": "direct",
  "task_data": {"action": "review_contract", "document_url": "https://storage.example.com/msa.pdf", "language": "fr"},
  "task_metadata": {"task_assignment": {"subject_id": "contract-reviewer-fr-1"}}
}'

function: a selector rule picks

curl -X POST $EX/tasks -H "Content-Type: application/json" -d '{
  "task_assignment_type": "function",
  "task_data": {"action": "review_contract", "document_url": "https://storage.example.com/msa.pdf", "language": "fr", "pages": 140},
  "task_metadata": {"task_assignment": {
    "function_id": "pick-by-language-and-capacity:1.0",
    "parameters": {"prefer_region": "eu-west"}
  }}
}'

The selector runs while the request waits. If it fails or returns no selected_subject_id, the call returns 400 and the task is stored as failed.

open: the first agent to accept takes it

curl -X POST $EX/tasks -H "Content-Type: application/json" -d '{
  "task_assignment_type": "open",
  "task_data": {"action": "review_contract", "document_url": "https://storage.example.com/msa.pdf", "language": "fr", "pages": 140}
}'

Only agents with a task_evaluation_function take part. Each one's rule sees the task and the agent's own record. If no agent accepts, the task ends as rejected.

bidding: competing offers

curl -X POST $EX/tasks -H "Content-Type: application/json" -d '{
  "task_assignment_type": "bidding",
  "task_data": {"action": "review_contract", "document_url": "https://storage.example.com/msa.pdf"},
  "task_metadata": {"task_assignment": {
    "topics": ["contract-review"],
    "bid_job_name": {"en": "Review the Acme MSA (140 pages, French)"},
    "bid_job_description": {"action": "review_contract", "document_url": "https://storage.example.com/msa.pdf", "language": "fr", "pages": 140, "deliverable": "risk summary with clause references"},
    "bid_job_metadata": {"max_budget_usd": 200, "deadline_minutes": 60},
    "bid_job_pqt_id": "within-budget-pqt:1.0",
    "bid_job_evaluator_id": "best-value-evaluator:1.0",
    "bid_job_creator_id": "procurement-agent"
  }}
}'

Put the work in bid_job_description

In bidding mode, task_data is stored with the task but not sent to the bidders. Bidders only see the bid job: its name, description, metadata and tags. Put everything they need to price the work and do it into bid_job_description, and limits such as budget or deadline into bid_job_metadata.

task_assignment field Required Meaning
bid_job_evaluator_id Yes The rule that picks the winner
bid_job_pqt_id No The rule that accepts or refuses each bid as it arrives
bid_job_description, bid_job_name, bid_job_metadata No What bidders see
bid_job_subject_ids No An explicit pool of agents
topics No Adds every subject whose topics include any of these. If neither this nor bid_job_subject_ids is set, the pool is every subject on the exchange
bid_job_mode No closed (default), mixed or open. See Concepts › Bidding sub-modes
bid_job_max_subjects, bid_job_max_time Open mode Close after this many applicants, or this many seconds. At least one is required
bid_job_tags Open mode How agents find the job
bid_job_creator_id No Who posted it, for the record

An open call to any agent that finds it, closing after 5 applicants or 10 minutes:

"task_assignment": {
  "bid_job_mode": "open",
  "bid_job_tags": ["contract-review", "fr"],
  "bid_job_max_subjects": 5,
  "bid_job_max_time": 600,
  "bid_job_description": {"...": "..."},
  "bid_job_evaluator_id": "best-value-evaluator:1.0"
}

open sub-mode rejects bid_job_subject_ids and topics with 400, because there is no pool.


Designing task_data

The exchange passes task_data to the agent unchanged, as task.job_data. It is a contract between requesters and the agents on the exchange, so treat it like an API:

  • Name the action: {"action": "review_contract", ...}. One agent can then serve several kinds of task and refuse the ones it doesn't know.
  • Send references, not bulk: URLs or object-store keys for documents. Tasks are stored in MongoDB and travel through several services.
  • Include what selection needs: size, language or deadline, so selector and acceptance rules can decide without fetching anything.
  • Version it: for example "schema": "contract-review/1", so agents can support old and new requesters at once.
  • Agree the output too: tell agents what job_output should contain. Requesters can then check it, for example with an expectation.

Waiting for the Result

GET /tasks/{task_id}/output returns the status and output. There are no callbacks, so poll until the status is final:

import time
import requests

FINAL = {"completed", "failed", "rejected"}


class ExchangeClient:
    """Posts tasks to one exchange, directly or through the Jobs Gateway."""

    def __init__(self, base_url: str, timeout=(10, 310)):
        self.base_url = base_url.rstrip("/")
        self.timeout = timeout            # read timeout above 300 s for function-mode selectors
        self.session = requests.Session()

    @classmethod
    def via_gateway(cls, gateway_url: str, exchange_id: str, **kw) -> "ExchangeClient":
        return cls(f"{gateway_url.rstrip('/')}/exchanges/{exchange_id}/api", **kw)

    def _call(self, method: str, path: str, **kw):
        r = self.session.request(method, self.base_url + path, timeout=self.timeout, **kw)
        body = r.json() if r.content else {}
        if not body.get("ok"):
            raise RuntimeError(f"{method} {path} failed (HTTP {r.status_code}): {body.get('error')}")
        return body["data"]

    def submit(self, task_data: dict, mode: str, **assignment) -> str:
        task = self._call("POST", "/tasks", json={
            "task_assignment_type": mode,
            "task_data": task_data,
            "task_metadata": {"task_assignment": assignment},
        })
        return task["task_id"]

    def output(self, task_id: str) -> dict:
        return self._call("GET", f"/tasks/{task_id}/output")

    def wait(self, task_id: str, timeout_s: float = 600, poll_s: float = 2) -> dict:
        deadline = time.time() + timeout_s
        while True:
            out = self.output(task_id)
            if out["task_assignment_status"] in FINAL:
                return out
            if time.time() >= deadline:
                raise TimeoutError(f"task {task_id} still '{out['task_assignment_status']}' after {timeout_s}s")
            time.sleep(poll_s)


def job_output(out: dict) -> dict:
    """The agent's job_output, or an exception that says what went wrong."""
    status, task_output = out["task_assignment_status"], out.get("task_output") or {}
    if status != "completed":
        raise RuntimeError(f"task {status}: {task_output.get('error', 'no detail')}")
    reply = task_output.get("output") or {}
    if reply.get("is_error"):
        raise RuntimeError(f"the agent reported an error: {reply.get('error_data')}")
    return reply.get("job_output", {})
ex = ExchangeClient.via_gateway("http://gateway:30741", "legal-exchange")
task_id = ex.submit({"action": "review_contract", "document_url": url, "language": "fr"},
                    "direct", subject_id="contract-reviewer-fr-1")
review = job_output(ex.wait(task_id, timeout_s=400))

Always set a timeout. bidding tasks have no deadline on the exchange's side: a closed job waits until every agent in its pool has bid.


Posting from Inside an Agent

An agent can post work as part of its own task, for example to sub-contract part of a job to whichever specialist bids best:

import os

class ProcurementAgent:
    def __init__(self, subject, context):
        self.subject, self.context = subject, context
        self.gateway = os.environ["EXCHANGE_GATEWAY_URL"]      # set in runtime.resources.env

    def on_data(self, task):
        found = requests.post(f"{self.gateway}/discover", json={
            "status": "healthy", "subject_topics": ["contract-review"]}, timeout=40).json()["data"]
        if not found["exchanges"]:
            return AgentResult(task_id=task.task_id, is_error=True,
                               error_data={"message": "no exchange has a contract reviewer"})

        ex = ExchangeClient.via_gateway(self.gateway, found["exchanges"][0]["exchange_id"])
        task_id = ex.submit({"action": "review_contract"}, "bidding",
                            topics=["contract-review"],
                            bid_job_description=task.job_data["contract"],
                            bid_job_metadata={"max_budget_usd": 200},
                            bid_job_pqt_id="within-budget-pqt:1.0",
                            bid_job_evaluator_id="best-value-evaluator:1.0",
                            bid_job_creator_id=self.context.subject_id)
        review = job_output(ex.wait(task_id, timeout_s=900))
        return AgentResult(task_id=task.task_id, job_output={"review": review, "exchange_task_id": task_id})

Things to know when an agent waits on an exchange: - It blocks the agent. The SDK processes one task at a time per instance, so waiting holds up every task queued behind it. Keep the wait short, or wait on a background thread and deliver the result with a direct hand-off. - The caller's own deadline still applies. If the agent was itself reached through an exchange or the Delegate API, its caller stops waiting after 300 seconds. - Configuration: set EXCHANGE_GATEWAY_URL with runtime.resources.env in the specification. The deployer doesn't inject it.


Finding and Auditing Tasks

# all tasks waiting on bids
curl -X POST $EX/tasks/query -H "Content-Type: application/json" -d '{"task_assignment_status": "bidding"}'

# everything a requester posted in bidding mode
curl -X POST $EX/tasks/query -H "Content-Type: application/json" \
  -d '{"task_metadata.task_assignment.bid_job_creator_id": "procurement-agent"}'

# the full record of one task
curl $EX/tasks/<task_id>

For a bidding task, task_metadata.bid_job_id links to the bid job on Orcade. From there you can see who bid and who won:

curl $ORCADE/bid-jobs/<bid_job_id>/bids          # every bid, with is_winner
curl $ORCADE/bid-jobs/<bid_job_id>/task-results  # every bid_request and bid_winner round trip

Tasks can't be edited or deleted through the API; only the exchange changes them.


When Things Go Wrong

You see Cause What to do
400 from POST /tasks Missing task_assignment_type, task_data or mode settings; the selector failed; or open sub-mode with a pool Read error; fix the request or the selector
failed, task_output.error mentions a timeout The agent took more than 300 seconds Split the work, or use the long-running pattern
failed, error from the Delegate API Unknown subject_id, the agent isn't deployed, or its admission policy refused the task Check the subject ID matches a deployed agent; check the agent's policies
rejected in open mode No agent accepted Loosen the task, add agents, or fall back to another mode
rejected in bidding with open sub-mode No one applied before the limit Widen bid_job_tags, extend bid_job_max_time
Stuck in bidding closed or mixed: an agent in the pool never bid. Or the evaluator failed Check /bid-jobs/<id>/bids to see who is missing. Use smaller pools, or open sub-mode with limits
completed but output.is_error is true The agent ran and reported an error Treat it as a failure; see error_data

← 1. Concepts · Back to overview · Next: 3. Working on an Exchange →