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

Type	Purpose
`AgentBuilder`	Configure model, instructions, tools, output, policy, capabilities, and subagents.
`AgentApp`	Application wrapper for sessions, subagent registry, and app-level helpers.
`AgentSession`	Multi-turn object that owns `AgentContext` next to a runtime agent.
`AgentContext`	Run/session evidence with explicit `runtime` and `tools` state components.
`AgentRuntimeBuilder`	Durable runtime builder for session stores, stream archives, and environment restore.
`SubagentRegistry`	Application-owned delegation registry for named child agents.

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()
    })
    .build();

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

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.
live_mcp_toolset(...) for host-backed live MCP discovery and calls.

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.

Keyboard shortcuts