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