Multi-Agent

Multi-Agent

Agiwo supports two public ways to compose agents: agent-as-tool composition and scheduler-managed orchestration.

Choose the right level

Use Agent.as_tool() when

• one agent should delegate focused sub-work to another
• the child can behave like a normal tool call
• you do not need persistent child state between turns

Use Scheduler when

• roots must stay alive across multiple inputs
• agents need waiting and wake conditions
• you need explicit steering, cancellation, or shutdown
• the runtime should manage child lifecycles directly

Agent-as-tool

from agiwo.agent import Agent, AgentConfig
from agiwo.llm import OpenAIModel

researcher = Agent(
    AgentConfig(
        name="researcher",
        description="Research specialist",
        system_prompt="Research thoroughly and cite sources.",
    ),
    model=OpenAIModel(name="gpt-5.4"),
)

orchestrator = Agent(
    AgentConfig(
        name="orchestrator",
        description="Delegates focused research",
        system_prompt="Delegate independent research tasks to the researcher tool.",
    ),
    model=OpenAIModel(name="gpt-5.4"),
    tools=[researcher.as_tool()],
)

This is the simplest public composition path when the delegated unit should look like a functional tool.

Scheduler-managed orchestration

from agiwo.scheduler import Scheduler

async with Scheduler() as scheduler:
    route = await scheduler.route_root_input(
        "Research two competing approaches and compare them.",
        agent=orchestrator,
        persistent=False,
    )
    result = await scheduler.wait_for(route.state_id)
    print(result.response)

For longer-lived roots:

route = await scheduler.route_root_input(
    "Manage the research pipeline",
    agent=orchestrator,
    persistent=True,
)
state_id = route.state_id

await scheduler.wait_for(state_id)
await scheduler.enqueue_input(state_id, "Now focus on pricing.")

Scheduler runtime tools

Agents running under the scheduler automatically get orchestration tools such as:

• spawn_child_agent
• fork_child_agent
• sleep_and_wait
• query_spawned_agent
• cancel_agent
• list_agents
• retrospect_tool_result

These are runtime-owned tools. You do not register them manually on the agent.

Common patterns

Specialist delegation

One orchestrator delegates bounded work to specialist agents via Agent.as_tool().

Persistent supervisor

One root stays alive and coordinates work over time through scheduler tools.

Fan-out and synthesis

Multiple worker agents gather or analyze in parallel, then another run synthesizes the results.