Struct Agent 

pub struct Agent<O: Serialize + Send + Sync + 'static = ()> { /* private fields */ }

Builder for configuring and constructing a runnable agent.

Type parameter O is the optional structured output type (use () for unstructured text).

Implementations

impl<O: Serialize + Send + Sync + 'static> Agent<O>

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

Create a new agent builder.

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

Set a human-readable description.

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

Set the primary model name.

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

Set a fallback model used when the primary is rate-limited or unavailable.

pub const fn effort(self, effort: EffortLevel) -> Self

Set the reasoning effort level.

pub const fn thinking(self, thinking: ThinkingConfig) -> Self

Configure extended thinking / chain-of-thought.

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

Add a tool available to the agent.

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

Restrict the agent to only these tool names (allowlist).

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

Exclude specific tools by name (denylist within allowlist).

pub fn plugin(self, plugin: impl Plugin + 'static) -> Self

Add a plugin.

pub fn middleware(self, mw: impl Middleware + 'static) -> Self

Add a middleware component.

pub fn hooks(self, hooks: HookRegistry) -> Self

Configure hooks.

pub const fn output_mode(self, mode: OutputMode) -> Self

Set the structured output mode.

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

Provide a JSON Schema for structured output validation.

pub const fn tool_output_format(self, format: OutputFormat) -> Self

Set the default serialization format for tool and VFS output.

Controls how structured data is rendered before being passed back to the LLM as tool results. Defaults to OutputFormat::Json. Individual tools can override this per-call.

pub const fn get_tool_output_format(&self) -> OutputFormat

Returns the configured tool output format.

pub const fn max_turns(self, turns: u32) -> Self

Set the maximum number of agent turns per run.

pub const fn max_budget(self, budget_usd: f64) -> Self

Set the maximum cumulative cost budget (USD).

pub fn system_prompt(self, config: SystemPromptConfig) -> Self

Configure the system prompt.

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

Set the permission mode.

pub fn permission_rule(self, rule: PermissionRule) -> Self

Add a permission rule.

pub fn sandbox(self, config: SandboxConfig) -> Self

Configure the sandbox.

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

Set an environment variable available to the agent.

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

Set the working directory for the agent.

pub const fn debug(self) -> Self

Enable debug mode (verbose logging).

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

Write debug output to a file.

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

Register an MCP server by name.

pub fn before_agent<F>(self, f: F) -> Self

where F: Fn(&RunContext) -> BoxFuture<'static, Result<(), AgentError>> + Send + Sync + 'static,

Register a before-agent callback.

pub fn after_agent<F>(self, f: F) -> Self

where F: Fn(&RunContext, &Result<(), AgentError>) -> BoxFuture<'static, ()> + Send + Sync + 'static,

Register an after-agent callback.

pub fn on_model_error<F>(self, f: F) -> Self

where F: Fn(&RunContext, &AgentError) -> BoxFuture<'static, ModelErrorAction> + Send + Sync + 'static,

Register a model error callback.

pub fn agent_name(&self) -> &str

Agent name.

pub fn agent_description(&self) -> &str

Agent description.

pub fn model_name(&self) -> &str

Primary model identifier.

pub fn fallback_model_name(&self) -> Option<&str>

Fallback model identifier, if configured.

pub const fn max_turn_count(&self) -> Option<u32>

Maximum turns, if set.

pub const fn budget_limit(&self) -> Option<f64>

Maximum budget (USD), if set.

pub const fn is_debug(&self) -> bool

Whether debug mode is enabled.

Trait Implementations

impl<O: Serialize + Send + Sync + 'static> Debug for Agent<O>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<O: Default + Serialize + Send + Sync + 'static> Default for Agent<O>

fn default() -> Agent<O>

Returns the “default value” for a type.