Struct AgentBuilder

Source

pub struct AgentBuilder { /* private fields */ }

Expand description

Builder for configuring and running agent sessions.

Use the builder pattern to set options, then call a terminal method (exec, run, resume, continue_last) to execute.

Implementations§

Source §

impl AgentBuilder

Source

pub fn new() -> Self

Create a new builder with default settings.

Source

pub fn provider(self, provider: &str) -> Self

Set the provider (e.g., “claude”, “codex”, “gemini”, “copilot”, “ollama”).

Source

pub fn model(self, model: &str) -> Self

Set the model (e.g., “sonnet”, “opus”, “small”, “large”).

Source

pub fn system_prompt(self, prompt: &str) -> Self

Set a system prompt to configure agent behavior.

Source

pub fn root(self, root: &str) -> Self

Set the root directory for the agent to operate in.

Source

pub fn auto_approve(self, approve: bool) -> Self

Enable auto-approve mode (skip permission prompts).

Source

pub fn add_dir(self, dir: &str) -> Self

Add an additional directory for the agent to include.

Source

pub fn worktree(self, name: Option<&str>) -> Self

Enable worktree mode with an optional name.

Source

pub fn sandbox(self, name: Option<&str>) -> Self

Enable sandbox mode with an optional name.

Source

pub fn size(self, size: &str) -> Self

Set the Ollama parameter size (e.g., “2b”, “9b”, “35b”).

Source

pub fn json(self) -> Self

Request JSON output from the agent.

Source

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

Set a JSON schema for structured output validation. Implies json().

Source

pub fn json_stream(self) -> Self

Enable streaming JSON output (NDJSON format).

Source

pub fn session_id(self, id: &str) -> Self

Set a specific session ID (UUID).

Source

pub fn output_format(self, format: &str) -> Self

Set the output format (e.g., “text”, “json”, “json-pretty”, “stream-json”).

Source

pub fn input_format(self, format: &str) -> Self

Set the input format (Claude only, e.g., “text”, “stream-json”).

Source

pub fn replay_user_messages(self, replay: bool) -> Self

Re-emit user messages from stdin on stdout (Claude only).

Only works with --input-format stream-json and --output-format stream-json.

Source

pub fn include_partial_messages(self, include: bool) -> Self

Include partial message chunks in streaming output (Claude only).

Only works with --output-format stream-json.

Source

pub fn verbose(self, v: bool) -> Self

Enable verbose output.

Source

pub fn quiet(self, q: bool) -> Self

Enable quiet mode (suppress all non-essential output).

Source

pub fn show_usage(self, show: bool) -> Self

Show token usage statistics.

Source

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

Set the maximum number of agentic turns.

Source

pub fn on_progress(self, handler: Box<dyn ProgressHandler>) -> Self

Set a custom progress handler for status reporting.

Source

pub async fn exec(self, prompt: &str) -> Result<AgentOutput>

Run the agent non-interactively and return structured output.

This is the primary entry point for programmatic use.

Source

pub async fn exec_streaming(self, prompt: &str) -> Result<StreamingSession>

Run the agent with streaming input and output (Claude only).

Returns a StreamingSession that allows sending NDJSON messages to the agent’s stdin and reading events from stdout. Automatically configures --input-format stream-json and --replay-user-messages.

§Examples

use zag_agent::builder::AgentBuilder;

let mut session = AgentBuilder::new()
    .provider("claude")
    .exec_streaming("initial prompt")
    .await?;

session.send_user_message("do something").await?;

while let Some(event) = session.next_event().await? {
    println!("{:?}", event);
}

session.wait().await?;