5. Selection & Bidding Rules¶
The decisions in an exchange are made by rules that you write. The exchange and Orcade call them by function_id, and they run in the function registry:
| Rule | Mode | Called | Input | Must return |
|---|---|---|---|---|
| Selector | function |
Once per task, while POST /tasks waits |
{"task_data", "subjects": [every subject]}, plus parameters |
{"selected_subject_id"} |
| Task evaluation | open |
Once per agent, in turn, until one accepts | {"task_data", "subject": <this agent>} |
{"status": "accepted"} to accept |
| Pre-qualification (PQT) | bidding |
On every bid, as it arrives | {"bid_job", "bid"} |
{"accepted": true} to keep the bid |
| Evaluator | bidding |
Once per job, when bidding is complete | {"bid_job", "bids": [...]} |
{"winner_subject_id", "status", "result_data"} |
Writing and Registering a Rule¶
A rule is either:
- An
AIOSv1PolicyRuleclass, run by the function platform as a stateless job or a stateful deployment. This is the same format as agent policies:
class AIOSv1PolicyRule:
def __init__(self, rule_id, settings, parameters):
self.rule_id, self.settings, self.parameters = rule_id, settings, parameters # static configuration
def eval(self, parameters, input_data, context):
... # input_data as in the table above
return {...}
- Any HTTP endpoint (
is_external=True). The registryPOSTsinput_dataas JSON, and the endpoint returns the output, optionally wrapped in{"data": ...}.
Register the rule in the function registry under a function_id, such as best-value-evaluator:1.0, before any task or job refers to it. A missing rule fails at first use: a 400 for selectors, a refused bid for PQT rules, an agent that never accepts in open mode, or a bid job that never picks a winner.
Put tunables (thresholds, weights) in the rule's registered settings, and read them from self.settings. You can then change them by updating the registry entry, without changing code. Selectors also receive the task's task_assignment.parameters as parameters (not with external endpoints); the other rules receive no per-call parameters.
Selector (function mode)¶
Pick the best agent for this task from every subject on the exchange. This one filters by action and language, then prefers spare capacity and a region:
class AIOSv1PolicyRule:
"""Pick a capable agent: right action and language, enough page capacity, most spare slots."""
def __init__(self, rule_id, settings, parameters):
self.rule_id, self.settings, self.parameters = rule_id, settings, parameters
def eval(self, parameters, input_data, context):
task, subjects = input_data["task_data"], input_data["subjects"]
prefer_region = (parameters or {}).get("prefer_region")
def capable(s):
c = s.get("subject_capabilities", {})
return (task.get("action") in c.get("actions", [])
and task.get("language", "en") in c.get("languages", [])
and task.get("pages", 0) <= c.get("max_pages", 0))
candidates = [s for s in subjects if capable(s)]
if not candidates:
raise ValueError("no capable subject") # POST /tasks returns 400, task marked failed
def rank(s):
c, m = s.get("subject_capabilities", {}), s.get("subject_metadata", {})
return (c.get("available_slots", 1), m.get("region") == prefer_region)
return {"selected_subject_id": max(candidates, key=rank)["subject_id"]}
The exchange doesn't check that selected_subject_id is one of the subjects it sent. A wrong ID fails later, at delivery.
Task Evaluation (open mode)¶
Each agent carries its own acceptance rule (task_evaluation_function on its subject record). Agents with no rule never take part. See the full example in Working on an Exchange › Accepting Work in open Mode.
- Agents are asked in database order, and the first
"accepted"wins. For fairness or load spreading, write rules that decline when the agent is busy (available_slots == 0), rather than relying on order. - A rule that raises counts as a decline.
- Return a
reasonwhen declining. It isn't stored, but it shows in the function platform's logs.
Pre-Qualification (bidding mode)¶
The PQT rule runs on each bid as it arrives. A refused bid is not stored, and the bidder gets 409. This one keeps bids within budget and confidence, and accepts no-bids, so closed jobs can still complete:
class AIOSv1PolicyRule:
"""Keep bids that are complete, within budget and confident enough. Always keep no-bids."""
def __init__(self, rule_id, settings, parameters):
self.rule_id, self.settings, self.parameters = rule_id, settings, parameters
def eval(self, parameters, input_data, context):
job, bid = input_data["bid_job"], input_data["bid"]["bid_data"]
if bid.get("no_bid"):
return {"accepted": True}
for key in ("price_usd", "eta_minutes", "confidence"):
if key not in bid:
return {"accepted": False, "reason": f"missing {key}"}
budget = (job.get("bid_job_metadata") or {}).get("max_budget_usd")
if budget is not None and bid["price_usd"] > budget:
return {"accepted": False, "reason": "over budget"}
if bid["confidence"] < self.settings.get("min_confidence", 0.6):
return {"accepted": False, "reason": "confidence too low"}
return {"accepted": True}
Refusing a bid in a closed job
A refused bid is not stored, so in closed and mixed jobs the refused agent still counts as "not yet bid", and the job can't be decided. Either accept every complete bid and let the evaluator disqualify, or make sure agents can bid again. They can, because a refused bid leaves nothing on file.
Evaluator (bidding mode)¶
The evaluator sees the job and every stored bid, and names the winner. Whatever it puts in result_data is sent to the winner with bid_winner, so include the agreed terms. This one scores by value, skips no-bids, and records why it chose the winner:
class AIOSv1PolicyRule:
"""Best value: weighted price, speed and confidence. Skips no-bids."""
def __init__(self, rule_id, settings, parameters):
self.rule_id, self.settings, self.parameters = rule_id, settings, parameters
def eval(self, parameters, input_data, context):
job, bids = input_data["bid_job"], input_data["bids"]
w = {"price": 0.5, "speed": 0.2, "confidence": 0.3, **self.settings.get("weights", {})}
real = [b for b in bids if not b["bid_data"].get("no_bid")]
if not real:
# winner_subject_id must match a bid, so name the first bidder and say there is no award.
return {"winner_subject_id": bids[0]["bid_subject_id"], "status": "no_valid_bids",
"result_data": {"award": False, "reason": "every agent declined"}}
cheapest = min(b["bid_data"]["price_usd"] for b in real) or 1.0
fastest = min(b["bid_data"]["eta_minutes"] for b in real) or 1.0
def score(b):
d = b["bid_data"]
return (w["price"] * cheapest / max(d["price_usd"], 0.01)
+ w["speed"] * fastest / max(d["eta_minutes"], 0.01)
+ w["confidence"] * d["confidence"])
best = max(real, key=score)
d = best["bid_data"]
return {
"winner_subject_id": best["bid_subject_id"],
"status": "resolved",
"result_data": {
"award": True,
"agreed_price_usd": d["price_usd"],
"deliver_within_minutes": d["eta_minutes"],
"score": round(score(best), 4),
"bids_considered": len(real),
},
}
winner_subject_idmust match one of the bids, or no winner is set and no one is notified.- When no bid is acceptable, name one bidder and set
"award": falseinresult_data. That agent'sbid_winnerhandler should checkawardand return an explanatoryjob_output, so the requester's task still completes. Otherwise the task stays inbidding. - Add other fields to
result_dataas needed: a deadline, a reference for a contract, or instructions for the work.
Testing Rules¶
Rules are plain classes, so test them locally before registering them:
rule = AIOSv1PolicyRule("best-value-evaluator:1.0", {"weights": {"price": 0.6}}, {})
job = {"bid_job_id": "job-1", "bid_job_metadata": {"max_budget_usd": 200}}
out = rule.eval({}, {"bid_job": job, "bids": [
{"bid_subject_id": "a", "bid_data": {"price_usd": 100, "eta_minutes": 5, "confidence": 0.9}},
{"bid_subject_id": "b", "bid_data": {"price_usd": 80, "eta_minutes": 12, "confidence": 0.7}},
{"bid_subject_id": "c", "bid_data": {"no_bid": True}},
]}, None)
assert out["winner_subject_id"] in {"a", "b"}