Skip to content

7. Running Exchanges

This chapter is for whoever runs the exchange services. It covers what to deploy, how to configure it, how to watch it and how to fix common problems.


What to Deploy

Service Image Manifest Namespace NodePort
Exchange (one per exchange) agents/xchange services/xchange/k8s/deploy.yaml exchanges 30740 for demo-exchange
Jobs Gateway agents/xchange-jobs-gateway services/xchange/k8s/jobs-gateway.yaml exchanges 30741
Orcade (bidding) agents/bidding-system services/orcade/k8s/deploy.yaml orcade 30730

The exchanges and Orcade also depend on these, which a standard installation already provides:

Dependency Used for
MongoDB Storage. Each exchange uses database exchange_<EXCHANGE_ID>, the gateway uses xchange_gateway, and Orcade uses assets
Delegate API (30725) Delivering tasks to agents
Function registry (30701) Selector, acceptance, PQT and evaluator rules
Deployed agents Each subject's ID must belong to a deployed agent

Deploy in this order: 1. Orcade. 2. One exchange. 3. The gateway. 4. Register the exchange with the gateway. 5. Register subjects.

kubectl apply -f services/orcade/k8s/deploy.yaml
kubectl apply -f services/xchange/k8s/deploy.yaml
kubectl apply -f services/xchange/k8s/jobs-gateway.yaml

curl -X POST $GW/exchanges -H "Content-Type: application/json" -d '{
  "exchange_id": "demo-exchange",
  "exchange_api_url": "http://demo-exchange-svc.exchanges.svc.cluster.local:5000",
  "exchange_name": "Demo exchange",
  "exchange_tags": ["general"],
  "exchange_metadata": {"owner": "platform", "region": "us-east"}
}'

Registration probes the exchange first and refuses it if it can't be reached, unless you pass skip_health_check: true. Use an address that is reachable from the gateway pod, such as cluster DNS, not from your laptop.


Configuration

Exchange

Variable Default Meaning
EXCHANGE_ID — The exchange's ID. Also names its database
MONGO_URL — MongoDB connection string
SUBJECT_DELEGATE_URL — The Delegate API
FUNCTION_REGISTRY_URL — The function registry
BIDDING_SERVICE_URL — Orcade, for bidding mode
BID_POLL_INTERVAL 5 Seconds between checks for a bid winner
NUM_WORKERS 8 Worker count for running rules on the function platform
EXECUTOR_ID, UNIQUE_PARAMETER xchange-executor, xchange Identify this service to the function platform

Jobs Gateway

Variable Default Meaning
MONGO_URL — Registry storage
GATEWAY_DB_NAME xchange_gateway Registry database
PORT 5000 Listen port
HEALTH_CHECK_INTERVAL 30 Seconds between health sweeps; 0 turns them off
PROXY_READ_TIMEOUT 300 How long a forwarded call may take
DISCOVERY_WORKERS 8 Exchanges asked in parallel during discovery

Run one gateway replica: every replica runs its own health sweep.

Orcade

Variable Default Meaning
MONGO_URL mongodb://localhost:27017 Storage
SUBJECT_DELEGATE_URL — The Delegate API
FUNCTION_REGISTRY_URL — The function registry
BID_EXPIRY_INTERVAL_SECONDS 5 How often open-mode deadlines are checked
NUM_WORKERS, EXECUTOR_ID, UNIQUE_PARAMETER 8, orcade-executor, orcade Function platform settings

Adding another exchange

Copy deploy.yaml with a new name, EXCHANGE_ID and NodePort, apply it, and POST /exchanges to the gateway. Discovery and forwarding include it straight away.


Watching an Exchange

Question Query
Is every exchange up? POST $GW/exchanges/query {"exchange_status": "unreachable"}
What is waiting on bids? POST $EX/tasks/query {"task_assignment_status": "bidding"}
What failed recently? POST $EX/tasks/query {"task_assignment_status": "failed", "taski_creation_time": {"$gt": "2026-11-18T00:00:00"}}
What did nobody accept? POST $EX/tasks/query {"task_assignment_status": "rejected"}
Which agents take part in open mode? POST $EX/subjects/query {"task_evaluation_function": {"$ne": ""}}
Who hasn't bid on a stuck job? Compare GET $ORCADE/bid-jobs/<id> (bid_job_subject_ids) with GET $ORCADE/bid-jobs/<id>/bids
What did the winner reply? GET $ORCADE/bid-jobs/<id>/task-results, entry with task_type: "bid_winner"

The task creation-time field is spelled taski_creation_time.


Troubleshooting

Symptom Likely cause Fix
Every task to one agent fails with a Delegate API error The subject ID isn't a deployed agent's subject ID, or the agent isn't running Check GET /api/runtime-subjects/<subject_id> on the subjects service; re-register the subject under the right ID
Tasks fail with read timed out The agent took more than 300 seconds Speed up the agent, split the work, or use long-running work
Tasks fail and the agent's logs show nothing The agent's admission policy refused them (429 at the executor) Check the agent's rate-limit and backlog policies and its scaling
function mode returns 400 The selector failed, isn't registered, or returned no selected_subject_id Test the rule locally; check its registration
open mode always rejected No subject has a task_evaluation_function, the rules aren't registered, or they all decline Query subjects with a rule; check the rules' logs on the function platform
bidding task stuck closed/mixed: an agent in the pool never bid, its bid was refused by the PQT rule, or its bid_request couldn't be delivered. The evaluator failed or named a non-bidder. The winner's reply to bid_winner timed out Find who hasn't bid (above). Use no-bids. Check the evaluator's logs. Keep the winner's work under 300 seconds
bidding with open sub-mode is rejected No one applied before the limit Check agents poll for the job's tags; widen tags or time
Gateway shows an exchange unreachable Wrong exchange_api_url, the exchange is down, or its MongoDB is down POST $GW/exchanges/<id>/health-check shows the error

Limits to Plan Around

Limit Effect
No authentication on the exchange, gateway or Orcade APIs Run them on a trusted network only. Anyone who can reach them can post tasks, register subjects and read results
No retries A failed delivery is final; requesters must re-post
No deadline on closed/mixed bidding Tasks can wait for ever; requesters need their own timeouts
300-second delivery limit Long work must use another channel for the result
open mode asks agents one at a time, in database order Busy exchanges with many open-mode agents decide slowly; order isn't fair by itself
Tasks can't be cancelled or edited through the API Plan clean-up and retention in MongoDB directly
One exchange's tasks aren't visible from another Requesters must remember which exchange holds each task

Checklist for a New Exchange

  • [ ] Exchange deployed with its own EXCHANGE_ID, and registered in the gateway with tags and metadata
  • [ ] A capability vocabulary agreed for subject_capabilities and task_data (actions, languages, limits)
  • [ ] Rules written, tested locally and registered: selector, acceptance, PQT and evaluator (including no-bid handling)
  • [ ] Subjects registered under their agents' real subject IDs, with accurate capabilities and topics
  • [ ] Agent admission policies and scaling sized for exchange traffic
  • [ ] Requesters use timeouts, and check task_output.output.is_error
  • [ ] Monitoring queries for stuck bidding, failed and rejected tasks

← 6. Recipes · Back to overview