agent-orchestrator-sdk

Orchestrate teams of LLM-powered agents in Rust. Coordinate multiple agent instances working together — one session acts as the team lead, coordinating work and assigning tasks. Teammates work independently, each with its own context, and communicate directly with each other.

The package is published as agent-orchestrator-sdk and imported in Rust code as agent_sdk. Additional usage docs live under docs/ in the repository.

When to use agent teams

Agent teams are most effective when parallel exploration adds real value:

• Research and review: multiple teammates investigate different aspects simultaneously, then share and challenge findings
• New modules or features: teammates each own a separate piece without stepping on each other
• Debugging with competing hypotheses: teammates test different theories in parallel
• Cross-layer coordination: changes spanning frontend, backend, and tests — each owned by a different teammate

Agent teams use more tokens than a single session. For sequential tasks, same-file edits, or highly dependent work, a single AgentLoop is more effective.

Compare: single agent vs agent team

	Single Agent (AgentLoop)	Agent Team (AgentTeam)
Context	One context window	Each teammate has its own context
Communication	N/A	Teammates message each other directly
Coordination	Sequential tool calls	Shared task list with self-coordination
Best for	Focused tasks, quick operations	Complex work requiring parallel exploration
Token cost	Lower	Higher: each teammate is a separate agent

Quick start

# Cargo.toml
[dependencies]
agent-orchestrator-sdk = "0.1"
tokio = { version = "1", features = ["full"] }

export ANTHROPIC_API_KEY="sk-ant-..."  # or OPENAI_API_KEY

Start your first agent team

Create a team, describe the teammates you want, add tasks, and run. The lead spawns teammates, they claim work from the shared task list, and coordinate on their own:

use agent_sdk::agent::team::AgentTeam;
use agent_sdk::config::{LlmConfig, AgentConfig};
use agent_sdk::types::task::Task;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let task1 = Task::new("gen", "Create config module", "...", "src/config.rs");
    let task2 = Task::new("gen", "Create server module", "...", "src/server.rs")
        .with_dependencies(vec![task1.id]);

    let result = AgentTeam::new(LlmConfig::default(), AgentConfig::default())
        .source_root(".")
        .work_dir("./output")
        .add_teammate("backend-dev", "You build Rust backend modules")
        .add_teammate("reviewer", "You review code for correctness")
        .add_task(task1)
        .add_task(task2)
        .run("Build a server project")
        .await?;

    println!("Tokens used: {}", result.total_tokens());
    Ok(())
}

For simple tasks that don't need a team, use run_single:

let result = AgentTeam::new(LlmConfig::default(), AgentConfig::default())
    .run_single("Explain this codebase")
    .await?;
println!("{}", result.final_content);

Interactive CLI

cargo run --bin agent                          # REPL mode
cargo run --bin agent -- "explain this code"   # One-shot
cargo run --bin agent -- -p openai -m gpt-4o   # OpenAI
cargo run --bin agent -- --allow-all-commands   # Unrestricted shell

Architecture

          ┌─────────────────────────────────────────────┐
          │                 Team Lead                    │
          │  Spawns teammates, coordinates work,        │
          │  approves plans, routes messages             │
          └──────────┬──────────────┬───────────────────┘
                     │              │
               ┌─────▼────┐  ┌─────▼────┐
               │Teammate 1│  │Teammate 2│  ... (N parallel)
               │AgentLoop │  │AgentLoop │
               └─────┬────┘  └─────┬────┘
                     │              │
                     │    ┌─────────┘    Teammates can
                     │    │              message each other
               ┌─────▼────▼──────────────────────────┐
               │          Shared Services             │
               │  TaskStore · MemoryStore · Mailbox   │
               └─────────────────────────────────────┘

An agent team consists of:

Component	Role
Team lead	The main session that creates the team, spawns teammates, and coordinates work
Teammates	Separate agent instances that each work on assigned tasks independently
Task list	Shared list of work items that teammates claim and complete
Mailbox	Messaging system for communication between all agents
Memory	Shared key-value store for inter-agent coordination

The lead is the intelligence — there is no separate planning step. You tell it what you want and it coordinates the team, just like Claude Code's agent teams.

Control your agent team

Specify teammates and roles

Each teammate gets its own context window and works independently:

AgentTeam::new(LlmConfig::default(), AgentConfig::default())
    .add_teammate("security-reviewer", "Review for security vulnerabilities")
    .add_teammate("perf-reviewer", "Review for performance issues")
    .add_teammate("test-checker", "Validate test coverage")

Add tasks with dependencies

Tasks are claimed by teammates from a shared task list. Dependencies are resolved automatically — blocked tasks unblock when their dependencies complete:

let schema = Task::new("analyze", "Parse API schema", "...", "schema.json")
    .with_priority(0);

let client = Task::new("codegen", "Generate client", "...", "client.rs")
    .with_dependencies(vec![schema.id])  // waits for schema
    .with_priority(1);

let tests = Task::new("test", "Write tests", "...", "tests.rs")
    .with_dependencies(vec![client.id])
    .with_priority(2);

Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task.

Require plan approval

For complex or risky work, require teammates to plan before implementing:

AgentTeam::new(LlmConfig::default(), AgentConfig::default())
    .add_teammate_with_plan_approval(
        "architect",
        "Refactor the authentication module"
    )

The teammate generates a plan, sends it to the lead for review. The lead evaluates using the LLM and either approves (teammate implements) or rejects with feedback (teammate revises).

Teammate-to-teammate messaging

Teammates communicate directly through the message broker — not just through the lead:

use agent_sdk::types::message::*;

// Direct message to another teammate
let msg = Envelope::new(my_id, MessageTarget::Agent(other_id), MessageKind::TeammateMessage)
    .with_payload(serde_json::json!({ "content": "Found an issue in auth.rs" }));
broker.route(&msg)?;

// Broadcast to all teammates
let broadcast = Envelope::new(my_id, MessageTarget::Broadcast, MessageKind::ContextShare)
    .with_payload(serde_json::json!({ "topic": "conventions", "content": "Use snake_case" }));
broker.route(&broadcast)?;

Shutdown negotiation

When the lead requests shutdown, teammates can accept or reject:

• Accept: teammate is idle, shuts down gracefully
• Reject: teammate is still working, provides a reason and keeps going

Enforce quality gates with hooks

Hooks run at key points in the agent lifecycle. Return Reject to block an action and send feedback:

use agent_sdk::{Hook, HookEvent, HookResult};

struct RequireTestCoverage;

impl Hook for RequireTestCoverage {
    fn on_event(&self, event: &HookEvent) -> HookResult {
        match event {
            HookEvent::TaskCompleted { task, .. } => {
                if let Some(result) = &task.result {
                    if !result.notes.to_lowercase().contains("test") {
                        return HookResult::Reject {
                            feedback: "Must include test coverage".to_string(),
                        };
                    }
                }
                HookResult::Continue
            }
            HookEvent::TeammateIdle { tasks_completed, .. } if *tasks_completed == 0 => {
                HookResult::Reject { feedback: "Keep looking for work".to_string() }
            }
            _ => HookResult::Continue,
        }
    }
}

Hook	When it fires	Reject effect
TeammateIdle	Teammate has no more work	Keeps teammate active
TaskCreated	Task being added to store	Prevents task creation
TaskCompleted	Task being marked done	Prevents completion, task retries

Monitor agent events

Subscribe to events for logging, UI, or metrics:

let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<AgentEvent>();

tokio::spawn(async move {
    while let Some(event) = rx.recv().await {
        match event {
            AgentEvent::TeammateSpawned { name, .. } => println!("+ {name}"),
            AgentEvent::TaskStarted { title, .. } => println!("> {title}"),
            AgentEvent::TaskCompleted { tokens_used, .. } => println!("  done ({tokens_used} tokens)"),
            AgentEvent::PlanSubmitted { plan_preview, .. } => println!("  plan: {plan_preview}"),
            AgentEvent::PlanApproved { .. } => println!("  approved"),
            AgentEvent::ShutdownRequested { .. } => println!("  shutting down"),
            _ => {}
        }
    }
});

let result = AgentTeam::new(LlmConfig::default(), AgentConfig::default())
    .event_channel(tx)
    // ...
    .run("...")
    .await?;

Low-level API

AgentLoop (single agent)

The building block underneath everything. Use it for full control:

use std::sync::Arc;
use agent_sdk::{AgentLoop, create_client, LlmConfig};
use agent_sdk::tools::registry::ToolRegistry;
use agent_sdk::tools::fs_tools::ReadFileTool;
use uuid::Uuid;

let client = create_client(&LlmConfig::default())?;
let mut tools = ToolRegistry::new();
tools.register(Arc::new(ReadFileTool { source_root: ".".into(), work_dir: ".".into() }));

let mut agent = AgentLoop::new(
    Uuid::new_v4(), client, tools,
    "You are a coding assistant.".to_string(), 50,
);
let result = agent.run("Summarize main.rs".to_string()).await?;

Custom tools

Implement the Tool trait to give agents new capabilities:

use async_trait::async_trait;
use agent_sdk::{Tool, ToolDefinition, SdkResult};
use serde_json::json;

pub struct MyTool;

#[async_trait]
impl Tool for MyTool {
    fn definition(&self) -> ToolDefinition {
        ToolDefinition {
            name: "my_tool".to_string(),
            description: "Does something useful".to_string(),
            parameters: json!({
                "type": "object",
                "properties": { "input": { "type": "string" } },
                "required": ["input"]
            }),
        }
    }

    async fn execute(&self, args: serde_json::Value) -> SdkResult<serde_json::Value> {
        let input = args["input"].as_str().unwrap_or("");
        Ok(json!({ "output": format!("processed: {input}") }))
    }
}

Add tools to teammates via PromptBuilder::customize_tools.

TeamLead (direct control)

For full control over team orchestration:

use std::sync::Arc;
use agent_sdk::*;
use agent_sdk::config::AgentConfig;
use agent_sdk::agent::hooks::HookRegistry;
use agent_sdk::traits::prompt_builder::DefaultPromptBuilder;
use uuid::Uuid;

let lead = TeamLead {
    id: Uuid::new_v4(),
    task_store: Arc::new(TaskStore::new("./output".into())),
    broker: Arc::new(MessageBroker::new("./output/mailbox".into())?),
    llm_client: create_client(&LlmConfig::default())?,
    prompt_builder: Arc::new(DefaultPromptBuilder),
    config: AgentConfig::default(),
    source_root: ".".into(),
    work_dir: "./output".into(),
    memory_store: Arc::new(MemoryStore::new("./output/memory".into())?),
    event_tx: None,
    hooks: Arc::new(HookRegistry::new()),
    teammate_specs: vec![
        TeammateSpec { name: "worker-1".into(), prompt: "...".into(), require_plan_approval: false },
    ],
};
let summary = lead.run().await?;

Built-in tools

Tool	Description
read_file	Read file contents with optional offset/limit
write_file	Write/create files in the work directory
list_directory	List files and directories
search_files	Search by glob pattern and/or content regex
run_command	Execute shell commands (configurable whitelist)
read_memory / write_memory / list_memory	Shared key-value memory
get_task_context / list_completed_tasks	Inspect other agents' work

Configuration

LlmConfig

LlmConfig {
    provider: LlmProvider::Claude,        // Claude or OpenAi
    model: "claude-sonnet-4-20250514".into(),
    max_tokens: 4096,
    requests_per_minute: 50,
    tokens_per_minute: 80_000,
    api_key: None,       // falls back to ANTHROPIC_API_KEY / OPENAI_API_KEY
    api_base_url: None,  // falls back to env or default
}

AgentConfig

AgentConfig {
    max_parallel_agents: 4,      // concurrent teammates
    poll_interval_ms: 200,       // task polling interval
    max_task_retries: 3,         // retries before permanent failure
    max_loop_iterations: 50,     // max ReAct iterations per task
    max_context_tokens: 200_000, // context window budget
}

Environment variables

Variable	Description
ANTHROPIC_API_KEY / OPENAI_API_KEY	API key (required)
LLM_PROVIDER	claude or openai (auto-detected from keys)
LLM_MODEL / ANTHROPIC_MODEL / OPENAI_MODEL	Model override
ANTHROPIC_API_BASE_URL / OPENAI_API_BASE_URL	Custom endpoint

Best practices

Give teammates enough context

Teammates don't inherit the lead's conversation. Include details in task descriptions and context:

Task::new("review", "Security review", "Review src/auth/ for vulnerabilities...", "review.md")
    .with_context(json!({ "app_uses": "JWT in httpOnly cookies", "focus": ["token handling"] }))

Choose appropriate team size

Start with 3-5 teammates. 5-6 tasks per teammate keeps everyone productive. Three focused teammates often outperform five scattered ones.

Size tasks appropriately

• Too small: coordination overhead exceeds benefit
• Too large: teammates work too long without check-ins
• Just right: self-contained units that produce a clear deliverable

Avoid file conflicts

Two teammates editing the same file leads to overwrites. Break work so each teammate owns different files.

Examples

cargo run --example single_agent    # Direct AgentLoop with custom tools
cargo run --example multi_agent     # Team with tasks and dependencies
cargo run --example named_team      # Named teammates with roles + hooks + plan approval

Project structure

src/
  lib.rs                # Public API re-exports
  config.rs             # LlmConfig, AgentConfig
  error.rs              # SdkError, TaskId, AgentId
  types/                # ChatMessage, Task, Envelope, MemoryEntry, FileChange
  traits/               # LlmClient, Tool, PromptBuilder traits
  llm/                  # Claude + OpenAI clients, rate limiter
  agent/
    team.rs             # AgentTeam — high-level entry point
    team_lead.rs        # TeamLead orchestrator
    teammate.rs         # Teammate worker (plan mode, shutdown negotiation)
    agent_loop.rs       # ReAct loop (Reason + Act)
    hooks.rs            # Hook system (TeammateIdle, TaskCreated, TaskCompleted)
    events.rs           # AgentEvent enum
    context.rs          # Per-agent context
    memory.rs           # MemoryStore
  task/                 # TaskStore, dependency graph, file locking
  mailbox/              # MessageBroker, file-based mailboxes
  tools/                # Built-in tools (fs, search, command, memory, context)
  bin/agent.rs          # Interactive CLI
examples/
  single_agent.rs       # Direct AgentLoop usage
  multi_agent.rs        # Team with tasks
  named_team.rs         # Named teammates + hooks + plan approval

License

MIT