> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powabase.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Multi-Agent Orchestration
> Orchestrations coordinate multiple agents to solve complex tasks. Three execution strategies (Supervisor, Sequential, and Parallel) give you different patterns for multi-agent collaboration, from autonomous delegation to pipeline processing to concurrent fan-out with merged results.
## What is an Orchestration?
An Orchestration is a container that groups multiple agents (entities) and runs them using a coordination strategy. Each entity agent has its own system prompt, tools, and knowledge bases, and the orchestration handles how they interact. You choose a strategy that matches your use case: Supervisor for autonomous delegation, Sequential for pipeline processing, or Parallel for concurrent execution with merged results.
## Execution Strategies
| Strategy | Pattern | How It Works | Best For |
| ---------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| supervisor | Coordinator delegates | Multi-domain support (billing + tech + sales), complex routing, dynamic task decomposition | |
| sequential | Pipeline | Entity agents run in order (sorted by position). Each agent receives the previous agent's output as its input. The final agent's output is the orchestration result. | Multi-stage processing: extract → analyze → summarize → format |
| parallel | Fan-out + merge | All entity agents run concurrently on the same input. If multiple agents produce results, a merge agent (gpt-4.1-mini) combines them into a single coherent response. | Independent analysis from multiple perspectives, parallel research tasks |
### Supervisor Strategy
The Supervisor strategy creates a coordinator agent that has access to a delegation tool for each entity agent. When a user message arrives, the coordinator reasons about which entity should handle it and calls the appropriate delegate\_to\_{name} tool with a task description. The entity agent runs with its own tools and knowledge bases (up to 10 ReAct steps by default) and returns its result. The coordinator can delegate to several entities in sequence, or feed the result of one delegation into the next. Its own ReAct loop runs for up to 25 steps.
Each delegation creates a child execution context with an incremented depth (max depth: 3, preventing infinite recursive delegation). The child context gets a budget allocation from the parent's remaining token budget. Entity agents share the parent's abort signal, so cancelling the orchestration cancels all active entity runs.
The coordinator's system prompt is auto-generated from the entity role descriptions. Write specific, non-overlapping role descriptions to help the coordinator make clear routing decisions. "Handles billing inquiries, invoices, and payment issues" routes better than "Handles customer questions."
### Sequential Strategy
The Sequential strategy runs entity agents one after another in position order. The first agent receives the user's message as input. Each subsequent agent receives the previous agent's output as its input. If any agent in the chain fails, the entire orchestration fails immediately. This is ideal for multi-stage processing pipelines where each stage transforms or enriches the data.
**Example: Document processing pipeline**
Agent 1 (Extractor): extracts key facts from a document. Agent 2 (Analyzer): identifies risks and opportunities from the extracted facts. Agent 3 (Writer): produces a formatted executive summary from the analysis.
### Parallel Strategy
The Parallel strategy runs all entity agents concurrently on the same input using a thread pool. Each agent processes the user's message independently with its own tools and knowledge bases. If there is only one entity, its output is returned directly. If there are multiple entities, after all agents complete, a merge agent (gpt-4.1-mini by default, configurable via orchestration settings) combines their outputs into a single coherent response. If any agent fails, the entire orchestration fails.
## Entity Configuration
Each entity in an orchestration has a role description and optional configuration. The role description is critical for the Supervisor strategy, since it tells the coordinator what the entity specializes in. For Sequential and Parallel, the role is descriptive metadata. Entity config can override max\_steps (default 10) to control how many ReAct iterations the entity agent runs.
```python Python theme={null}
# Create an orchestration with the supervisor strategy
response = requests.post(
f"{BASE_URL}/api/orchestrations",
headers=headers,
json={
"name": "Customer Support Team",
"strategy": "supervisor",
},
)
orch = response.json()
orch_id = orch["id"]
# Add entity agents with clear role descriptions
requests.post(
f"{BASE_URL}/api/orchestrations/{orch_id}/entities",
headers=headers,
json={
"agent_id": billing_agent_id,
"role": "Handles billing inquiries, invoices, payments, and refund requests",
},
)
requests.post(
f"{BASE_URL}/api/orchestrations/{orch_id}/entities",
headers=headers,
json={
"agent_id": tech_agent_id,
"role": "Handles technical issues, API errors, integration problems, and setup questions",
},
)
```
```typescript TypeScript theme={null}
// Create an orchestration with the supervisor strategy
const orchRes = await fetch(`${BASE_URL}/api/orchestrations`, {
method: "POST",
headers,
body: JSON.stringify({
name: "Customer Support Team",
strategy: "supervisor",
}),
});
const orch = await orchRes.json();
// Add entity agents with clear role descriptions
await fetch(`${BASE_URL}/api/orchestrations/${orch.id}/entities`, {
method: "POST",
headers,
body: JSON.stringify({
agent_id: billingAgentId,
role: "Handles billing inquiries, invoices, payments, and refund requests",
}),
});
await fetch(`${BASE_URL}/api/orchestrations/${orch.id}/entities`, {
method: "POST",
headers,
body: JSON.stringify({
agent_id: techAgentId,
role: "Handles technical issues, API errors, integration problems, and setup questions",
}),
});
```
```bash cURL theme={null}
# Create orchestration
curl -X POST '{BASE_URL}/api/orchestrations' \
-H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{"name": "Customer Support Team", "strategy": "supervisor"}'
# Add billing agent entity
curl -X POST '{BASE_URL}/api/orchestrations/{orch_id}/entities' \
-H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{"agent_id": "{billing_agent_id}", "role": "Handles billing inquiries, invoices, and payments"}'
```
## Streaming Events
Orchestration streaming exposes the full execution flow via SSE. For the Supervisor strategy, you see delegation events as the coordinator routes tasks to entities. For Sequential, you see step events as each agent runs. For Parallel, events from concurrent agents may interleave.
| Event | Description |
| ------------------------- | --------------------------------------------------------------- |
| start | Orchestration run started — includes run\_id and session\_id |
| orchestration\_started | Execution has begun with the configured strategy |
| delegation\_started | Supervisor: coordinator is delegating a task to an entity agent |
| delegation\_completed | Supervisor: entity agent finished its subtask |
| sequential\_step | Sequential: an agent in the pipeline has started/completed |
| tool\_call / tool\_result | An entity agent is calling/receiving a tool |
| chunk | Text chunk from the final response |
| complete | Orchestration run finished — includes content, usage, steps |
| error | An error occurred during execution |
## Limits
| Constraint | Default | Notes |
| ----------------------- | ------------ | -------------------------------------------------------------------------------- |
| Coordinator max steps | 25 | Supervisor strategy: how many ReAct steps the coordinator gets |
| Entity max steps | 10 | Per-entity ReAct step limit, configurable in entity config |
| Max orchestration depth | 3 | Prevents recursive delegation loops (coordinator → entity → sub-delegation) |
| Parallel merge model | gpt-4.1-mini | Configurable via orchestration settings. Used to combine parallel agent outputs. |
## Next Steps
Create an orchestration and run it step by step.
Understand the ReAct loop and tool system that powers each entity.
For deterministic multi-step pipelines, use workflows instead.
Full endpoint documentation.