Agent SDK

starweaver-agent is the application-facing SDK crate. New applications should import common contracts from starweaver_agent::prelude; lower-level protocols live under explicit starweaver_agent::advanced::{context, model, runtime, session, stream, tools} namespaces. Root re-exports remain as a 0.x compatibility facade and are not the boundary for new stable API growth.

#![allow(unused)]
fn main() {
use starweaver_agent::prelude::*;
}

Main types

SDK layers

flowchart TD
    builder["AgentBuilder"]
    app["AgentApp"]
    session["AgentSession"]
    context["AgentContext"]
    runtime["starweaver-runtime::Agent"]
    store["SessionStore and StreamArchive"]
    env["EnvironmentProvider"]

    builder --> runtime
    builder --> app
    app --> session
    session --> context
    session --> runtime
    runtime --> store
    context --> env

Builder shape

#![allow(unused)]
fn main() {
use std::sync::Arc;

use starweaver_agent::{AgentBuilder, AgentRuntimePolicy, TestModel, UsageLimits};

async fn example() -> Result<(), starweaver_agent::AgentError> {
let agent = AgentBuilder::new(Arc::new(TestModel::with_text("ok")))
    .agent_identity("support", "Support Agent")
    .instruction("Answer with the support policy.")
    .usage_limits(UsageLimits {
        request_limit: Some(4),
        ..UsageLimits::default()
    })
    .policy(AgentRuntimePolicy {
        max_steps: 8,
        ..AgentRuntimePolicy::default()
    })
    .model_correction_retries(Some(3))
    .build();

let result = agent.run("hello").await?;
assert_eq!(result.output, "ok");
Ok(())
}
}

model_correction_retries is a run-wide aggregate ceiling shared by model-correctable tool and output failures. It defaults to 3, is independent of category budgets, and can be disabled with None. Transport recovery, internal tool execution retry, steering, and goal continuation are separate failure domains and do not consume it.

Runtime capabilities

Capabilities are extension hooks around the runtime loop. Use them for host policy, request preparation, tool filtering, output validation, usage snapshots, trace recording, and custom sideband events.

Common SDK capability sources:

• default_filter_capabilities for context compaction and media upload preparation.
• EnvironmentContextCapability for filesystem/shell context injection.
• SkillDiscoveryCapability for scanned skill packages.
• Custom AgentCapability implementations for product policy.

First-party bundles

starweaver-agent includes bundles that can be attached without making the runtime crate depend on product-specific implementations:

• filesystem_tools() for list, view, glob, grep, and file mutation helpers.
• shell_tools() for provider-scoped shell execution and background process handles.
• task_tools() for model-visible task tracking.
• user_input_tools() for ask_user_question, a structured clarifying-question tool that waits for host/user input through the standard HITL flow.
• context_tools() for context handoff, notes, and explicit thinking tools.
• host_io_tools() for host-backed search, fetch, scrape, download, and remote media reading.
• skill_tools(...) for discovered skill packages.
• codeact_tools(...) for bounded synchronous JavaScript composition over eligible Strict tools.
• recipe_tools(...) for context-prepared, file-backed high-level recipes pinned through the active environment provider.
• live_mcp_toolset(...) for host-backed live MCP discovery and calls.

See CodeAct and Recipes for executor limits, tool eligibility, recipe layout, and product defaults.

Choosing the entry point

• Use AgentBuilder::build() for a reusable runtime agent.
• Use AgentBuilder::build_app() for app-owned sessions and subagents.
• Use AgentRuntimeBuilder when you need durable stores, stream archives, environment restore, or service runtime wiring.
• Use direct APIs such as model_request and tool_call when you want Starweaver’s protocol mapping without the full agent loop.