Skip to main content

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.

​
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 — 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

StrategyPatternHow It WorksBest For
supervisorCoordinator delegatesA coordinator agent reasons about the user’s message and delegates subtasks to entity agents by calling delegate_to_ tools. The coordinator synthesizes entity responses into a final answer.Multi-domain support (billing + tech + sales), complex routing, dynamic task decomposition
sequentialPipelineEntity 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
parallelFan-out + mergeAll 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 multiple entities in sequence or use the results from one delegation to inform the next. The coordinator’s own ReAct loop runs for up to 25 steps.
Orchestration flow: User → Coordinator → delegates to Agent A and Agent B → results merge → Coordinator synthesizes → Final Response.
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 — for example, “Handles billing inquiries, invoices, and payment issues” rather 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 pipelineAgent 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 — 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. 
# 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",
    },
)

​
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.
EventDescription
startOrchestration run started — includes run_id and session_id
orchestration_startedExecution has begun with the configured strategy
delegation_startedSupervisor: coordinator is delegating a task to an entity agent
delegation_completedSupervisor: entity agent finished its subtask
sequential_stepSequential: an agent in the pipeline has started/completed
tool_call / tool_resultAn entity agent is calling/receiving a tool
chunkText chunk from the final response
completeOrchestration run finished — includes content, usage, steps
errorAn error occurred during execution

​
Limits

ConstraintDefaultNotes
Coordinator max steps25Supervisor strategy: how many ReAct steps the coordinator gets
Entity max steps10Per-entity ReAct step limit, configurable in entity config
Max orchestration depth3Prevents recursive delegation loops (coordinator → entity → sub-delegation)
Parallel merge modelgpt-4.1-miniConfigurable via orchestration settings. Used to combine parallel agent outputs.

​
Next Steps

Orchestration Guide

Create an orchestration and run it step by step.

Agents & Tools

Understand the ReAct loop and tool system that powers each entity.

Workflows

For deterministic multi-step pipelines, use workflows instead.

Orchestrations API Reference

Full endpoint documentation.