Task Delegation¶
No single agent is good at everything. When an agent decomposes a goal into sub-tasks, some of those sub-tasks are better handled by another agent: one with a specialised skill, access to a particular tool or dataset, spare capacity, or a better track record. Task delegation is the mechanism that lets an agent hand a sub-task to another agent, keep track of it while it runs, and collect the result, without the two agents having to share a process, a cluster, or even an owner.
Why it matters¶
- Specialisation — a generalist agent can orchestrate, while specialist agents do the work they are best at.
- Parallelism — independent sub-tasks can be sent to several agents at once instead of being executed one by one.
- Scale and resilience — work is spread across the network; a slow or failed delegate can be detected and the sub-task reassigned.
- Accountability — every delegation is a persisted record with a status history and a final result, so you can audit who did what.
How it works¶
- The delegating agent (the sender) decides which agent should receive a sub-task. The target can be known up front, or chosen through auction/bidding, a DSL-based plan-and-retrieve step, or a social-choice vote (see Social Choice & Voting).
- A delegation record is created through the REST API, and the target agent is notified over NATS with a
delegation_taskevent. - The target agent works on the sub-task, updating the record's status as it progresses.
- The result is submitted back through REST or a
delegation_resultNATS event, and the sender picks it up. Results can optionally be checked by the Verification System.
For the internal architecture (delegation pipeline, external response handler, state synchronisation layer) see Agent Task Delegation — Architecture.
At a Glance¶
The Agents Task Delegation system allows one agent (the sender) to delegate sub-tasks to another agent (the target) in a distributed, event-driven environment. It provides:
- REST APIs to create, update, query, and delete delegation records.
- Status tracking for live workflow stages.
- NATS-based real-time communication to send tasks and receive results.
A typical client workflow is:
- Create a delegation via REST API.
- Notify the target agent by publishing a
delegation_taskevent on NATS. - Track progress through REST queries or WebSocket updates.
- Submit results via REST or publish a
delegation_resultevent.
Registering Delegation System in Subject Specification¶
The delegation system can be registered as a sub-module in an agent’s Subject Specification by adding an entry of type SubSystemItem.
This configuration tells the agent where to reach the Delegations API, how to connect to the NATS messaging bus, and what defaults to apply when a delegation request does not specify all parameters.
Data Class Reference¶
@dataclass
class SubSystemItem:
sub_system_id: str
sub_system_type: str = ""
sub_system_config: Dict[str, Any] = field(default_factory=dict)
Minimal Required Configuration¶
Below is the minimal JSON block you need to include in the subject specification to enable the delegation system.
{
"sub_system_id": "delegation-system-01",
"sub_system_type": "delegation-system",
"sub_system_config": {
"api_base_url": "http://delegations-api.default.svc.cluster.local:8080/delegations",
"nats_url": "nats://nats.default.svc.cluster.local:4222",
"default_workflow_level": 1,
"default_delegation_type": "manual",
"default_deadline_seconds": 3600
}
}
Field Descriptions¶
| Field | Location | Type | Description |
|---|---|---|---|
| sub_system_id | root | str |
Unique identifier for this subsystem entry in the subject spec. |
| sub_system_type | root | str |
Must be "delegation-system" for the delegation sub-module. |
| sub_system_config.api_base_url | config | str |
Base REST API URL for the Delegations service. All HTTP calls (create, update, query) will be sent here. |
| sub_system_config.nats_url | config | str |
NATS server connection string used for sending and receiving real-time delegation events. |
| sub_system_config.default_workflow_level | config | int |
Default workflow stage for delegations when none is specified in a request. |
| sub_system_config.default_delegation_type | config | str |
Default delegation type (manual, system, auction, etc.) when not specified. |
| sub_system_config.default_deadline_seconds | config | int |
Default allowed time (in seconds) before a delegated task expires. |
Example in a Subject Specification¶
If your Subject Specification is a JSON or YAML file that lists subsystems, you would add this as one entry in the sub_systems list:
{
"subject_id": "agent-alpha",
"subject_type": "agent",
"sub_systems": [
{
"sub_system_id": "delegation-system-01",
"sub_system_type": "delegation-system",
"sub_system_config": {
"api_base_url": "http://delegations-api.default.svc.cluster.local:8080/delegations",
"nats_url": "nats://nats.default.svc.cluster.local:4222",
"default_workflow_level": 1,
"default_delegation_type": "manual",
"default_deadline_seconds": 3600
}
}
]
}
This ensures that when the agent needs to delegate a sub-task, it knows exactly where to send the API requests and how to communicate over NATS for event-driven updates, with safe defaults for workflow level, delegation type, and deadlines.
Import and Setup¶
REST Client¶
You can use requests or any HTTP library of your choice.
import requests
BASE_URL = "http://<delegations-api-url>/delegations"
NATS Client¶
Use the provided NATSAPI helper or nats-py directly.
from delegation_tasks_pusher import NATSAPI
nats = NATSAPI(nats_url="nats://localhost:4222")
Usage Guide¶
Creating a Delegation¶
payload = {
"task_id": "task123",
"sub_task_id": "sub456",
"workflow_level": 1,
"delegation_type": "manual",
"target_subject_id": "agentB",
"sender_subject_id": "agentA",
"sub_task_data": {"param": "value"}
}
resp = requests.post(f"{BASE_URL}", json=payload)
print(resp.json())
Expected Output:
{
"success": true,
"message": "Delegation created successfully"
}
Sending a Delegation Event¶
nats.push_event(
topic="agentB",
sender_subject_id="agentA",
event_type="delegation_task",
event_data={
"task_id": "task123",
"sub_task_id": "sub456",
"delegation_id": "del789",
"data": {"info": "Execute this subtask"}
}
)
Listening for Delegation Events¶
import asyncio
import json
from nats.aio.client import Client as NATS
async def on_message(msg):
data = json.loads(msg.data.decode())
print(f"Received: {data}")
async def main():
nc = NATS()
await nc.connect("nats://localhost:4222")
await nc.subscribe("agentB", cb=on_message)
await asyncio.sleep(100)
asyncio.run(main())
Fetching a Delegation by ID¶
delegation_id = "del789"
resp = requests.get(f"{BASE_URL}/{delegation_id}")
print(resp.json())
Querying Delegations¶
query_payload = {"target_subject_id": "agentB"}
resp = requests.post(f"{BASE_URL}/query", json=query_payload)
print(resp.json())
Updating Delegation Status¶
status_payload = {
"state": "in_progress",
"time": 1717390000,
"deadline": 1717400000
}
status_key = "execution"
delegation_id = "del789"
resp = requests.put(f"{BASE_URL}/{delegation_id}/status/{status_key}", json=status_payload)
print(resp.json())
Submitting Final Result¶
result_payload = {
"state": "done",
"delegation_result": "Execution completed successfully"
}
resp = requests.put(f"{BASE_URL}/submit_result/del789", json=result_payload)
print(resp.json())
Receiving Results via NATS¶
If the target agent uses NATS to send back a result:
nats.push_event(
topic="agentA",
sender_subject_id="agentB",
event_type="delegation_result",
event_data={
"delegation_id": "del789",
"result": "Execution completed successfully"
}
)
Deleting a Delegation¶
delegation_id = "del789"
resp = requests.delete(f"{BASE_URL}/{delegation_id}")
print(resp.json())