Struct AgentBuilder 

pub struct AgentBuilder { /* private fields */ }

Fluent builder for constructing crate::Agent instances with custom configuration.

Use crate::Agent::builder() to create a new builder instance.

Implementations

impl AgentBuilder

pub async fn build(self) -> Result<Agent>

impl AgentBuilder

pub fn new() -> Self

Creates a new builder with default configuration.

pub fn agent_config(self, config: AgentConfig) -> Self

Sets the complete agent configuration, replacing all defaults.

pub fn provider_config(self, config: ProviderConfig) -> Self

Sets the API provider configuration (timeouts, beta features, etc.).

pub async fn auth(self, auth: impl Into<Auth>) -> Result<Self>

Configures authentication for the API.

Supported Methods

• Auth::from_env() - Uses ANTHROPIC_API_KEY environment variable
• Auth::api_key("sk-...") - Explicit API key
• Auth::claude_cli() - Uses Claude CLI OAuth (requires cli-integration feature)
• Auth::bedrock("region") - AWS Bedrock (requires aws feature)
• Auth::vertex("project", "region") - GCP Vertex AI (requires gcp feature)

Example

let agent = Agent::builder()
    .auth(Auth::from_env()).await?
    .build().await?;

pub fn oauth_config(self, config: OAuthConfig) -> Self

Sets OAuth configuration for token refresh.

pub fn supports_server_tools(&self) -> bool

Returns whether the current auth method supports server-side tools.

pub fn models(self, config: ModelConfig) -> Self

Sets both primary and small model configurations.

pub fn model(self, model: impl Into<String>) -> Self

Sets the primary model for main operations.

Default: claude-sonnet-4-5-20250514

pub fn small_model(self, model: impl Into<String>) -> Self

Sets the smaller model for quick operations (e.g., subagents).

Default: claude-haiku-4-5-20251001

pub fn max_tokens(self, tokens: u32) -> Self

Sets the maximum tokens per response.

Default: 8192. Values exceeding this require the 128k beta feature, which is automatically enabled when using ProviderConfig::with_max_tokens.

pub fn extended_context(self, enabled: bool) -> Self

Enables extended context window (1M tokens for supported models).

Requires the context-1m-2025-08-07 beta feature. Currently supported: claude-sonnet-4-5-20250929

pub fn tools(self, access: ToolAccess) -> Self

Sets tool access policy.

Options

• ToolAccess::all() - Enable all built-in tools
• ToolAccess::none() - Disable all tools
• ToolAccess::only(["Read", "Write"]) - Enable specific tools
• ToolAccess::except(["Bash"]) - Enable all except specific tools

pub fn tool<T: Tool + 'static>(self, tool: T) -> Self

Registers a custom tool implementation.

pub fn working_dir(self, path: impl Into<PathBuf>) -> Self

Sets the working directory for file operations.

pub fn max_iterations(self, max: usize) -> Self

Sets the maximum number of agentic loop iterations.

Default: 100

pub fn timeout(self, timeout: Duration) -> Self

Sets the overall execution timeout.

Default: 300 seconds

pub fn chunk_timeout(self, timeout: Duration) -> Self

Sets the timeout between streaming chunks.

This timeout detects stalled connections when no data is received for the specified duration during streaming responses.

Default: 60 seconds

For large projects or slow network conditions, consider increasing this value (e.g., 180 seconds).

pub fn auto_compact(self, enabled: bool) -> Self

Enables or disables automatic context compaction.

Default: true

pub fn compact_keep_messages(self, count: usize) -> Self

Sets the number of messages to preserve during compaction.

Default: 4

pub fn system_prompt(self, prompt: impl Into<String>) -> Self

Sets a custom system prompt, replacing the default.

pub fn system_prompt_mode(self, mode: SystemPromptMode) -> Self

Sets how the system prompt is applied.

pub fn append_system_prompt(self, prompt: impl Into<String>) -> Self

Appends to the default system prompt instead of replacing it.

pub fn output_style(self, style: OutputStyle) -> Self

Sets the output style for response formatting.

pub fn output_style_name(self, name: impl Into<String>) -> Self

Sets the output style by name (loaded from configuration).

pub fn output_schema(self, schema: Value) -> Self

Sets a JSON schema for structured output.

pub fn structured_output<T: JsonSchema>(self) -> Self

Enables structured output with automatic schema generation.

pub fn permission_policy(self, policy: PermissionPolicy) -> Self

Sets the complete permission policy.

pub fn permission_mode(self, mode: PermissionMode) -> Self

Sets the permission mode (permissive, default, or strict).

pub fn allow_tool(self, pattern: impl Into<String>) -> Self

Adds a rule to allow a tool or pattern.

pub fn deny_tool(self, pattern: impl Into<String>) -> Self

Adds a rule to deny a tool or pattern.

pub fn env(self, key: impl Into<String>, value: impl Into<String>) -> Self

Sets an environment variable for tool execution.

pub fn envs( self, vars: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>, ) -> Self

Sets multiple environment variables for tool execution.

pub fn allow_domain(self, domain: impl Into<String>) -> Self

Adds a domain to the network allowlist.

pub fn deny_domain(self, domain: impl Into<String>) -> Self

Adds a domain to the network blocklist.

pub fn sandbox_enabled(self, enabled: bool) -> Self

Enables or disables sandbox isolation.

pub fn exclude_command(self, command: impl Into<String>) -> Self

Excludes a command from sandbox restrictions.

pub fn max_budget_usd(self, amount: f64) -> Self

Sets the maximum budget in USD.

pub fn tenant_id(self, id: impl Into<String>) -> Self

Sets the tenant ID for multi-tenant budget tracking.

pub fn tenant_budget_manager(self, manager: TenantBudgetManager) -> Self

Sets a shared tenant budget manager.

pub fn fallback_model(self, model: impl Into<String>) -> Self

Sets the model to fall back to when budget is exceeded.

pub fn fallback(self, config: FallbackConfig) -> Self

Sets the complete fallback configuration.

pub fn session_manager(self, manager: SessionManager) -> Self

Sets a custom session manager for persistence.

pub async fn fork_session(self, session_id: impl Into<String>) -> Result<Self>

Forks an existing session, creating a new branch.

pub async fn resume_session(self, session_id: impl Into<String>) -> Result<Self>

Resumes an existing session by ID.

pub fn messages(self, messages: Vec<Message>) -> Self

Sets initial messages for the conversation.

pub fn mcp_server( self, name: impl Into<String>, config: McpServerConfig, ) -> Self

Adds an MCP server configuration.

pub fn mcp_stdio( self, name: impl Into<String>, command: impl Into<String>, args: Vec<String>, ) -> Self

Adds an MCP server using stdio transport.

pub fn mcp_manager(self, manager: McpManager) -> Self

Sets an owned MCP manager.

pub fn shared_mcp_manager(self, manager: Arc<McpManager>) -> Self

Sets a shared MCP manager (for multi-agent scenarios).

pub fn mcp_toolset(self, toolset: McpToolset) -> Self

Registers an MCP toolset configuration for deferred loading.

pub fn with_tool_search(self) -> Self

Enables tool search with default configuration.

pub fn tool_search_config(self, config: ToolSearchConfig) -> Self

Sets the tool search configuration.

pub fn tool_search_threshold(self, threshold: f64) -> Self

Sets the tool search threshold as a fraction of context window (0.0 - 1.0).

pub fn tool_search_mode(self, mode: SearchMode) -> Self

Sets the search mode for tool search.

pub fn always_load_tools( self, tools: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Sets tools that should always be loaded immediately (never deferred).

pub fn shared_tool_search_manager(self, manager: Arc<ToolSearchManager>) -> Self

Sets a shared tool search manager.

pub fn skill_registry(self, registry: IndexRegistry<SkillIndex>) -> Self

Sets a complete skill registry.

pub fn skill(self, skill: SkillIndex) -> Self

Registers a single skill index.

pub fn rule_index(self, index: RuleIndex) -> Self

Adds a rule index for rule discovery.

pub fn memory_content(self, content: impl Into<String>) -> Self

Adds memory content (CLAUDE.md style).

pub fn local_memory_content(self, content: impl Into<String>) -> Self

Adds local memory content (CLAUDE.local.md style).

pub fn subagent_registry(self, registry: IndexRegistry<SubagentIndex>) -> Self

Sets a complete subagent registry.

pub fn subagent(self, subagent: SubagentIndex) -> Self

Registers a single subagent.

pub fn hook<H: Hook + 'static>(self, hook: H) -> Self

Registers an event hook.

impl AgentBuilder

pub async fn from_claude_code(self, path: impl AsRef<Path>) -> Result<Self>

Available on crate feature cli-integration only.

Initializes Claude Code CLI authentication and working directory.

This is the minimal setup. Use with_*_resources() methods to enable loading from specific levels. Resources are loaded during build() in a fixed order: Enterprise → User → Project → Local.

Example

let agent = Agent::builder()
    .from_claude_code("./project").await?
    .with_user_resources()
    .with_project_resources()
    .build()
    .await?;

pub fn with_enterprise_resources(self) -> Self

Available on crate feature cli-integration only.

Enables loading of enterprise-level resources during build.

Resources are loaded from system configuration paths:

• macOS: /Library/Application Support/ClaudeCode/
• Linux: /etc/claude-code/

This method only sets a flag; actual loading happens during build() in the fixed order: Enterprise → User → Project → Local.

pub fn with_user_resources(self) -> Self

Available on crate feature cli-integration only.

Enables loading of user-level resources during build.

Resources are loaded from ~/.claude/.

This method only sets a flag; actual loading happens during build() in the fixed order: Enterprise → User → Project → Local.

pub fn with_project_resources(self) -> Self

Available on crate feature cli-integration only.

Enables loading of project-level resources during build.

Resources are loaded from {working_dir}/.claude/. Requires from_claude_code() to be called first to set the working directory.

This method only sets a flag; actual loading happens during build() in the fixed order: Enterprise → User → Project → Local.

pub fn with_local_resources(self) -> Self

Available on crate feature cli-integration only.

Enables loading of local-level resources during build.

Loads CLAUDE.local.md and settings.local.json from the project directory. These are typically gitignored and contain personal/machine-specific settings. Requires from_claude_code() to be called first to set the working directory.

This method only sets a flag; actual loading happens during build() in the fixed order: Enterprise → User → Project → Local.

Trait Implementations

impl Default for AgentBuilder

fn default() -> AgentBuilder

Returns the “default value” for a type.