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
impl AgentBuilder
Sourcepub fn provider(self, provider: &str) -> Self
pub fn provider(self, provider: &str) -> Self
Set the provider (e.g., “claude”, “codex”, “gemini”, “copilot”, “ollama”).
Calling this method pins the provider — it will NOT be downgraded to
another provider in the tier list if its binary is missing or the
startup probe fails. Omit this call (or set provider via the config
file) to allow automatic downgrading.
Sourcepub fn model(self, model: &str) -> Self
pub fn model(self, model: &str) -> Self
Set the model (e.g., “sonnet”, “opus”, “small”, “large”).
Sourcepub fn system_prompt(self, prompt: &str) -> Self
pub fn system_prompt(self, prompt: &str) -> Self
Set a system prompt to configure agent behavior.
Sourcepub fn auto_approve(self, approve: bool) -> Self
pub fn auto_approve(self, approve: bool) -> Self
Enable auto-approve mode (skip permission prompts).
Sourcepub fn file(self, path: &str) -> Self
pub fn file(self, path: &str) -> Self
Attach a file to the prompt (text files ≤50 KB inlined, others referenced).
Sourcepub fn env(self, key: &str, value: &str) -> Self
pub fn env(self, key: &str, value: &str) -> Self
Add an environment variable for the agent subprocess.
Sourcepub fn json_schema(self, schema: Value) -> Self
pub fn json_schema(self, schema: Value) -> Self
Set a JSON schema for structured output validation.
Implies json().
Sourcepub fn session_id(self, id: &str) -> Self
pub fn session_id(self, id: &str) -> Self
Set a specific session ID (UUID).
Sourcepub fn output_format(self, format: &str) -> Self
pub fn output_format(self, format: &str) -> Self
Set the output format (e.g., “text”, “json”, “json-pretty”, “stream-json”).
Sourcepub fn input_format(self, format: &str) -> Self
pub fn input_format(self, format: &str) -> Self
Set the input format (Claude only, e.g., “text”, “stream-json”).
No-op for Codex, Gemini, Copilot, and Ollama. See docs/providers.md
for the full per-provider support matrix.
Sourcepub fn replay_user_messages(self, replay: bool) -> Self
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.
exec_streaming auto-enables this flag, so most
callers never need to set it manually. No-op for non-Claude providers.
Sourcepub fn include_partial_messages(self, include: bool) -> Self
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. Defaults to false.
When false (the default), streaming surfaces one assistant_message
event per complete assistant turn. When true, the agent instead emits
a stream of token-level partial assistant_message chunks as the model
generates them — use this for responsive, token-by-token UIs over
exec_streaming. No-op for non-Claude providers.
Sourcepub fn show_usage(self, show: bool) -> Self
pub fn show_usage(self, show: bool) -> Self
Show token usage statistics.
Sourcepub fn timeout(self, duration: Duration) -> Self
pub fn timeout(self, duration: Duration) -> Self
Set a timeout for exec. If the agent doesn’t complete within this duration, it will be killed and an error returned.
Sourcepub fn mcp_config(self, config: &str) -> Self
pub fn mcp_config(self, config: &str) -> Self
Set MCP server config for this invocation (Claude only).
Accepts either a JSON string ({"mcpServers": {...}}) or a path to a JSON file.
No-op for Codex, Gemini, Copilot, and Ollama — those providers manage
MCP configuration through their own CLIs or do not support it. See
docs/providers.md for the full per-provider support matrix.
Sourcepub fn on_progress(self, handler: Box<dyn ProgressHandler>) -> Self
pub fn on_progress(self, handler: Box<dyn ProgressHandler>) -> Self
Set a custom progress handler for status reporting.
Sourcepub async fn exec(self, prompt: &str) -> Result<AgentOutput>
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.
Sourcepub async fn exec_streaming(self, prompt: &str) -> Result<StreamingSession>
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, --output-format stream-json,
and --replay-user-messages.
§Default emission granularity
By default assistant_message events are emitted once per complete
assistant turn — you get one event when the model finishes speaking,
not a stream of token chunks. For responsive, token-level UIs call
include_partial_messages(true)
on the builder before exec_streaming; the session will then emit
partial assistant_message chunks as the model generates them.
The default is kept false so existing callers that render whole-turn
bubbles are not broken. See docs/providers.md for the full
per-provider flag support matrix.
§Event lifecycle
The session emits a unified
Event::Result at the end of every
agent turn — not only at final session end. Use that event as the
authoritative turn-boundary signal. After a Result, the session
remains open and accepts another
send_user_message for the next
turn. Call
close_input followed by
wait to terminate the session cleanly.
Do not depend on replayed user_message events to detect turn
boundaries; those only appear while --replay-user-messages is set.
§Examples
use zag_agent::builder::AgentBuilder;
use zag_agent::output::Event;
let mut session = AgentBuilder::new()
.provider("claude")
.exec_streaming("initial prompt")
.await?;
// Drain the first turn until Result.
while let Some(event) = session.next_event().await? {
println!("{:?}", event);
if matches!(event, Event::Result { .. }) {
break;
}
}
// Follow-up turn.
session.send_user_message("do something else").await?;
while let Some(event) = session.next_event().await? {
if matches!(event, Event::Result { .. }) {
break;
}
}
session.close_input();
session.wait().await?;Sourcepub async fn run(self, prompt: Option<&str>) -> Result<()>
pub async fn run(self, prompt: Option<&str>) -> Result<()>
Start an interactive agent session.
This takes over stdin/stdout for the duration of the session.
Sourcepub async fn continue_last(self) -> Result<()>
pub async fn continue_last(self) -> Result<()>
Resume the most recent session.