agent_sdk_rs/
lib.rs

1//! # agent-sdk-rs
2//!
3//! **Pure-Rust SDK for tool-using agents with explicit control flow.**
4//! Minimal by design: one agent loop, explicit completion, and provider adapters with a shared interface.
5//!
6//! ## Why this crate?
7//! | Capability | `agent-sdk-rs` | Typical abstraction-heavy frameworks | Why this helps agents |
8//! |---|---|---|---|
9//! | Agent core | Explicit loop in [`Agent::query_stream`] | Hidden planners / wrappers | Fewer moving parts, easier debugging |
10//! | Action space | User-defined tools via [`ToolSpec`] JSON schema | Fixed or opinionated primitives | Start broad, then restrict by policy |
11//! | Completion semantics | Optional explicit `done` via [`ToolOutcome::Done`] + [`AgentBuilder::require_done_tool`] | Implicit stop when no tool calls | Prevents premature "done" |
12//! | Provider interface | One trait ([`ChatModel`]) and swappable adapters | Provider-specific runtime behavior | Swap models without rewriting agent logic |
13//! | Reliability guards | Retries/backoff + max-iteration limit + schema validation | Often ad-hoc in app code | Safer autonomous runs |
14//!
15//! ## Philosophy
16//! This crate follows the "small loop, large action space, explicit exit" direction described by Browser Use:
17//! - [The Bitter Lesson of Agent Frameworks](https://browser-use.com/posts/bitter-lesson-agent-frameworks)
18//! - [browser-use/agent-sdk](https://github.com/browser-use/agent-sdk)
19//!
20//! In this crate, that maps to:
21//! - Tools define capability surface ([`ToolSpec`]).
22//! - The run loop is explicit and inspectable via events ([`AgentEvent`]).
23//! - Completion can be explicit with `done` mode ([`ToolOutcome::Done`]).
24//! - Model adapters stay thin and replaceable ([`ChatModel`], [`AnthropicModel`], [`GoogleModel`], [`GrokModel`]).
25//!
26//! ## Quickstart
27//! ```rust,no_run
28//! use agent_sdk_rs::{Agent, AnthropicModel};
29//!
30//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
31//! let model = AnthropicModel::from_env("claude-sonnet-4-5")?;
32//! let mut agent = Agent::builder().model(model).build()?;
33//!
34//! let answer = agent.query("Summarize the task in one line.").await?;
35//! println!("{answer}");
36//! # Ok(())
37//! # }
38//! ```
39//!
40//! ## Streaming events
41//! ```rust,no_run
42//! use agent_sdk_rs::{Agent, AgentEvent, GoogleModel};
43//! use futures_util::StreamExt;
44//!
45//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
46//! let model = GoogleModel::from_env("gemini-2.5-flash")?;
47//! let mut agent = Agent::builder().model(model).build()?;
48//! let stream = agent.query_stream("Solve this step by step.");
49//! futures_util::pin_mut!(stream);
50//!
51//! while let Some(event) = stream.next().await {
52//!     match event? {
53//!         AgentEvent::ToolCall { tool, .. } => println!("tool: {tool}"),
54//!         AgentEvent::FinalResponse { content } => println!("final: {content}"),
55//!         _ => {}
56//!     }
57//! }
58//! # Ok(())
59//! # }
60//! ```
61//!
62//! ## Explicit `done` mode
63//! For autonomous runs, require an explicit completion signal:
64//! ```rust,no_run
65//! use agent_sdk_rs::{Agent, AnthropicModel};
66//! use agent_sdk_rs::tools::claude_code::all_tools;
67//!
68//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
69//! let model = AnthropicModel::from_env("claude-sonnet-4-5")?;
70//! let mut agent = Agent::builder()
71//!     .model(model)
72//!     .tools(all_tools())
73//!     .require_done_tool(true)
74//!     .max_iterations(64)
75//!     .build()?;
76//!
77//! let _ = agent.query("Inspect the repo and summarize open risks.").await?;
78//! # Ok(())
79//! # }
80//! ```
81//!
82//! ## Evidence in this repository
83//! - Done-tool stop semantics and max-iteration guard: `src/agent/tests.rs`
84//! - Dependency override behavior for tools: `src/agent/tests.rs`
85//! - Tool schema and argument validation: `src/tools/mod.rs`
86//! - Provider adapters with the same core interface: `src/llm/`
87
88/// Agent loop, config, event stream, and query helpers.
89pub mod agent;
90/// Error types returned by schema validation, tools, providers, and agent runtime.
91pub mod error;
92/// Provider abstraction and model adapters.
93pub mod llm;
94/// Tool specification, dependency injection, and built-in Claude-code-style tools.
95pub mod tools;
96
97/// Agent runtime API.
98pub use agent::{
99    Agent, AgentBuilder, AgentConfig, AgentEvent, AgentRole, AgentToolChoice, StepStatus, query,
100    query_stream,
101};
102/// Error values exposed by the SDK.
103pub use error::{AgentError, ProviderError, SchemaError, ToolError};
104/// Model adapters and model-interface types.
105pub use llm::{
106    AnthropicModel, AnthropicModelConfig, ChatModel, GoogleModel, GoogleModelConfig, GrokModel,
107    GrokModelConfig, ModelCompletion, ModelMessage, ModelToolCall, ModelToolChoice,
108    ModelToolDefinition, ModelUsage,
109};
110/// Tool and dependency primitives.
111pub use tools::{DependencyMap, ToolOutcome, ToolSpec};
agent_sdk_rs/lib.rs

agent_sdk_rs/
lib.rs
