anyagent

https://github.com/spotta85/anyagent-rs
Admin
anyagent provides a unified Rust interface to discover, manage, and interact with coding agents...
Tokens:25,248
Snippets:225
Trust Score:6.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup development environment

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/contributing.mdx

Clone the repository and install the 'just' command runner to manage development tasks.

```bash
git clone https://github.com/spotta85/anyagent-rs && cd anyagent-rs
cargo install just        # the dev front door; `just` lists every command
just check                # fmt, clippy, offline tests
```

--------------------------------

### Run repository examples

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/quickstart.mdx

Commands to run the provided example programs against installed agents.

```bash
cargo run --example chat -- claude      # prompt, stream, answer, steer
cargo run --example sessions -- claude  # several sessions at once, then resume
cargo run --example probe               # what's installed, logged in, and capable
```

--------------------------------

### Discover and select agents

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Initializes the runtime, scans for available agents, and displays them in the UI. It distinguishes between installed agents and those requiring installation.

```rust
let runtime = Runtime::new();
runtime.prewarm();                      // start scanning while the window opens

let report = runtime.discover().await;
for agent in &report.agents {
    ui.agent_row(&agent.name, agent.auth.as_ref());   // auth here is a best-effort offline guess
}
for missing in &report.missing {
    ui.install_row(&missing.name, &missing.install_hint);
}
let agent = report.require(&chosen_id)?.clone();
```

--------------------------------

### Runtime::discover()

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/core-api.mdx

Performs an instant, read-only scan of the machine to identify installed agents and provide installation hints for missing ones.

```APIDOC
## Runtime::discover()

### Description
Performs an instant, read-only scan of the machine to identify installed agents and provide installation hints for missing ones.

### Returns
- **DiscoveryReport** - A report containing installed agents and missing agents with install hints.
```

--------------------------------

### Execute a single agent turn in src/main.rs

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/quickstart.mdx

A complete example showing how to discover an agent, open a session, prompt it, and stream the response.

```rust
use anyagent::{EventKind, Runtime, SessionOptions};
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = Runtime::new();

    // 1. Find what's on this machine, then insist on one of them.
    let report = runtime.discover().await;
    let agent = report.require("claude")?;

    // 2. Open a session: a command handle and an event stream.
    let (session, mut events) = runtime.open(agent, SessionOptions::in_dir(".")).await?;

    // 3. Prompt, then drain events until the turn ends.
    session.prompt("explain this repo").await?;
    while let Some(event) = events.next().await {
        match event?.kind {
            EventKind::TextDelta { text, .. } => print!("{text}"),
            EventKind::TurnEnded { .. } => break,
            _ => {}
        }
    }

    session.close().await?;
    Ok(())
}
```

--------------------------------

### Start codex app-server

Source: https://github.com/spotta85/anyagent-rs/blob/main/tests/fixtures/codex/README.md

The command used to initialize the codex app-server with a specific workspace and temporary home directory.

```bash
codex app-server            # cwd = workspace, CODEX_HOME = a temp dir
```

--------------------------------

### SessionOptions

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/core-api.mdx

Configuration builder for initializing an agent session. Use these methods to define the environment, permissions, and initial settings before starting the agent.

```APIDOC
## SessionOptions

### Description
Builder pattern to configure an agent session before it starts. Start with `in_dir` and chain additional options.

### Methods
- **in_dir(path)** - Required - Sets the working directory for the agent.
- **configure(id, value)** - Optional - Sets a config option (e.g., "model", "effort", "fast", "mode") before the first turn.
- **resume(token)** - Optional - Reopens an earlier session.
- **fork_from(token, at)** - Optional - Branches a new session off an old one.
- **mcp_server(server)** - Optional - Provides an MCP server (stdio, HTTP, SSE).
- **permission_mode(mode)** - Optional - Sets mode to `Ask` or `AutoApprove`.
- **config_home(dir)** - Optional - Sets a separate config directory.
- **quiet_window(dur)** - Optional - Sets duration of silence before completion is inferred.
- **stall_after(dur)** - Optional - Sets silence duration before a stall diagnostic.
- **record_wire(path)** - Optional - Dumps raw protocol traffic to a JSONL file.
```

--------------------------------

### Handling Agent Requests

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/core-api.mdx

Example of matching on incoming requests to provide answers for permissions or questions using session.answer.

```rust
use anyagent::{Answer, PermissionChoice, QuestionAnswer, Request};

match request {
    Request::Permission(r) => {
        // r.options is what this agent actually offers; answers outside it are rejected
        session.answer(r.id, Answer::Permission(PermissionChoice::AllowOnce)).await?;
    }
    Request::Question(r) => {
        // one QuestionAnswer per question, in order
        let answers = r.questions.iter().map(|_| QuestionAnswer::Text("yes".into())).collect();
        session.answer(r.id, Answer::Question(answers)).await?;
    }
}
```

--------------------------------

### Manual ACP Agent Installation

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/agents.mdx

Build an agent installation manually using AgentInstallation::acp when no catalog entry is available. Note that verified quirks like launch flags and auth hints are not provided.

```rust
use anyagent::{AgentInstallation, Runtime, SessionOptions};

let agent = AgentInstallation::acp(
    "my-agent",                    // display name
    "/usr/local/bin/my-agent",     // executable
    vec!["acp".into()],            // args that put it in ACP mode
);
let (session, events) = Runtime::new().open(&agent, SessionOptions::in_dir(".")).await?;
```

--------------------------------

### Install ACP agent via AgentInstallation

Source: https://github.com/spotta85/anyagent-rs/blob/main/README.md

Use this method to register an ACP-compatible agent that is not explicitly listed in the catalog.

```rust
AgentInstallation::acp(name, path, args)
```

--------------------------------

### Retrieve and iterate over plan usage

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Demonstrates how to fetch plan usage for a specific agent and iterate over usage data for all installed agents to populate a dashboard.

```rust
let usage = runtime.plan_usage(&agent).await?;        // plan name, 5-hour and weekly windows
for entry in runtime.plan_usage_all().await {          // every installed agent, for a dashboard
    ui.card(&entry.agent.name, entry.usage);
}
```

--------------------------------

### Discover and validate agents

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/core-api.mdx

Use the runtime discovery method to scan for installed agents and handle missing ones using the returned report.

```rust
let report = runtime.discover().await;
let agent = report.require("codex")?;          // AgentError::NotInstalled if absent
for missing in &report.missing {               // MissingAgent { name, install_hint, .. }
    println!("{}: {}", missing.name, missing.install_hint);
}
```

--------------------------------

### Install anyagent dependencies

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/quickstart.mdx

Add the required dependencies to your Rust project using cargo.

```bash
cargo add anyagent futures tokio --features tokio/rt-multi-thread,tokio/macros
```

--------------------------------

### Antigravity Upgrade UI Offer

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/agents.mdx

Rust code snippet used to offer an installation upgrade to the user when only the headless agy wire is detected.

```rust
if let Some(upgrade) = &agent.upgrade {
    ui.offer_install(&upgrade.name, &upgrade.install_hint);
}
```

--------------------------------

### Prompting with text and attachments

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Sends text and file attachments to a session, handling the resulting DeliveryKind to determine if the turn started, was steered, or was queued.

```rust
let delivery = session
    .prompt(Input::text("what's wrong here?").attach("screenshot.png"))
    .await?;
match delivery.kind {
    DeliveryKind::Started { turn_id } => {}      // session was idle; a turn began
    DeliveryKind::Steered { turn_id } => {}      // a turn was running; this went into it
    DeliveryKind::Queued { position } => {}      // a turn was running; this waits its turn
}
```

--------------------------------

### session.prompt(input)

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Sends text, slash commands, or file attachments to the agent session. The returned Delivery object indicates whether the prompt started a new turn, steered an existing one, or was queued.

```APIDOC
## session.prompt(input)

### Description
Sends an input (text or file attachment) to the agent. The behavior depends on the current session state.

### Parameters
- **input** (Input) - Required - The content to send, which can include text and file attachments.

### Returns
- **Delivery** - An object containing the kind of delivery (Started, Steered, or Queued) and the associated turn_id or position.
```

--------------------------------

### Fork session from history

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Creates a new session starting from an existing session's history, leaving the original session untouched. Use None for message_id to fork from the end of the history.

```rust
let options = SessionOptions::in_dir(".").fork_from(token, Some(message_id));  // None = from the end
let (branch, branch_events) = runtime.open(&agent, options).await?;
```

--------------------------------

### Initialize and interact with an agent

Source: https://github.com/spotta85/anyagent-rs/blob/main/README.md

Demonstrates the core flow of discovering an agent, opening a session, sending a prompt, and streaming the response events.

```rust
use anyagent::{EventKind, Runtime, SessionOptions};
use futures::StreamExt;

let runtime = Runtime::new();
let report = runtime.discover().await;
let agent = report.require("claude")?;
let (session, mut events) = runtime.open(agent, SessionOptions::in_dir(".")).await?;

session.prompt("explain this repo").await?;
while let Some(event) = events.next().await {
    match event?.kind {
        EventKind::TextDelta { text, .. } => print!("{text}"),
        EventKind::TurnEnded { .. } => break,
        _ => {}
    }
}
session.close().await?;
```

--------------------------------

### runtime.open(&agent, options)

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Spawns an agent process and establishes a live conversation session.

```APIDOC
## runtime.open(&agent, options)

### Description
Spawns the agent process, performs a handshake, and returns a session handle and an event stream for communication.

### Method
Async Method

### Parameters
- **agent** (Agent) - Required - The agent to open.
- **options** (SessionOptions) - Required - Configuration options for the session, such as the config home directory.

### Response
- **session** (Session) - Handle for sending commands.
- **events** (Events) - Stream for receiving agent events.
```

--------------------------------

### Run live harness tests with just

Source: https://github.com/spotta85/anyagent-rs/blob/main/contributions.md

Execute live harness tests for wire or adapter changes, providing the output in the pull request.

```bash
just live <harness> <feature>
```

--------------------------------

### Runtime::open(&agent, options)

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/core-api.mdx

Spawns an agent session and returns the Session and Events handles for communication.

```APIDOC
## Runtime::open(&agent, options)

### Description
Spawns the agent and returns the two halves of the communication channel: the Session for sending commands and the Events stream for reading agent output.

### Parameters
- **agent** (AgentInstallation) - The agent to spawn.
- **options** (SessionOptions) - Configuration options for the session.

### Returns
- **(Session, Events)** - A tuple containing the session controller and the event stream.
```

--------------------------------

### Configure MCP servers with SessionOptions

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Shows how to register stdio, HTTP, and SSE MCP servers within the session options.

```rust
let options = SessionOptions::in_dir(".")
    .mcp_server(McpServer::stdio("local", "/usr/bin/my-server", ["--stdio"]))
    .mcp_server(McpServer::http("remote", "https://example.com/mcp").with("Authorization", "Bearer …"))
    .mcp_server(McpServer::sse("stream", "https://example.com/sse"));
```

--------------------------------

### Monitor usage with runtime.plan_usage_all

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Iterates through usage entries to update the UI with quota information per agent.

```rust
for entry in runtime.plan_usage_all().await {              // one call, every installed agent
    match entry.usage {
        Ok(usage) => ui.quota_card(&entry.agent.name, usage),   // plan name, 5-hour and weekly windows
        Err(_) => {}                                            // no subscription or no PlanUsage capability
    }
}
```

--------------------------------

### Runtime and Session Capabilities

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

A summary of available methods for runtime management, session control, and event monitoring.

```text
Runtime   discover · probe · open · generate · plan_usage
Session   prompt · answer · configure · cancel · rollback · compact · close
Events    text · tools · plans · requests · status · usage · turn boundaries
```

--------------------------------

### Discover Agents with runtime.discover()

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Finds all supported agents on the machine by checking environment variables, PATH, and known directories. Use report.require to select a specific agent or return an AgentError if missing.

```rust
let report = runtime.discover().await;
for agent in &report.agents {
    println!("{} at {}", agent.name, agent.executable_path.display());
}
for missing in &report.missing {
    println!("{} not installed: {}", missing.name, missing.install_hint);
}
let agent = report.require("claude")?;   // AgentError::NotInstalled if absent
```

--------------------------------

### Run project checks with just

Source: https://github.com/spotta85/anyagent-rs/blob/main/contributions.md

Execute the required project checks before submitting a pull request.

```bash
just check
```

--------------------------------

### Open a Session with SessionOptions

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Configures session options based on thread state, including resume tokens, permission modes, and model selection. It handles session opening, including fallback logic for stale tokens and authentication requirements.

```rust
let mut options = SessionOptions::in_dir(&thread.repo_dir);
if let Some(token) = &thread.resume_token {
    options = options.resume(token.clone());                    // continue an old conversation
}
if thread.unattended {
    options = options.permission_mode(PermissionMode::AutoApprove);
}
if let Some(model) = &thread.model {
    options = options.configure("model", model.as_str());
}

let (session, events) = match runtime.open(&agent, options).await {
    Ok(pair) => pair,
    Err(AgentError::ResumeFailed(_)) => {
        // the token went stale: start fresh, keep your transcript
        runtime.open(&agent, SessionOptions::in_dir(&thread.repo_dir)).await?
    }
    Err(AgentError::AuthRequired { login }) => return ui.show_login(login),
    Err(e) => return Err(e.into()),
};
thread.save_info(session.info());   // resume token, capabilities, options
```

--------------------------------

### Handle agent permissions and questions

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Uses open_request to match on Request types, rendering either a permission dialog or a question form based on the agent's request.

```rust
fn open_request(ui: &Ui, session: Session, request: Request) {
    match request {
        Request::Permission(r) => {
            // r.tool is the ToolUpdate awaiting approval (title, input, diffs)
            ui.permission_dialog(r.tool, r.detail, r.options, move |choice| {
                let session = session.clone();
                async move { session.answer(r.id.clone(), Answer::Permission(choice)).await }
            });
        }
        Request::Question(r) => {
            // one answer per question, in order; choices or free text per q.allows_free_text
            ui.question_form(r.questions, move |answers: Vec<QuestionAnswer>| {
                let session = session.clone();
                async move { session.answer(r.id.clone(), Answer::Question(answers)).await }
            });
        }
    }
}
```

--------------------------------

### session.compact

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Triggers the agent to summarize its own context to free up window space.

```APIDOC
## session.compact()

### Description
Asks the agent to summarize its own context. This operation confirms with `ContextCompacted` followed by a `ContextUsage` update.

### Usage
```rust
session.compact().await?;
```
```

--------------------------------

### Configure headless session options

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Sets up session options for unattended workers by enabling auto-approval and specific agent modes.

```rust
let options = SessionOptions::in_dir(&repo)
    .permission_mode(PermissionMode::AutoApprove)   // allow every tool request
    .configure("mode", "accept-edits");             // if the agent has such a mode
```

--------------------------------

### Run pi in RPC mode

Source: https://github.com/spotta85/anyagent-rs/blob/main/tests/fixtures/pi/README.md

Command used to generate the wire recordings with the specified provider and model.

```bash
pi --mode rpc --provider openrouter --model nvidia/nemotron-3-super-120b-a12b:free
```

--------------------------------

### Test with mock agents

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Initializes a runtime with a scripted agent using the mock feature to test engine logic without external dependencies.

```rust
let runtime = Runtime::with_mock(Script::default().turn(vec![
    Step::Emit(text("m1", "hi")),
    Step::Emit(permission("p1")),
    Step::AwaitAnswer,
    Step::End(completed()),
]));
let agent = runtime.discover().await.require("mock")?.clone();
// steps 3 to 7 run unchanged
```

--------------------------------

### Open a new agent session

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Spawns an agent process and returns a Session handle and an Events stream. Requires a directory path for session configuration.

```rust
let (session, events) = runtime
    .open(&agent, SessionOptions::in_dir("/path/to/repo"))
    .await?;
```

--------------------------------

### Send prompts and cancel sessions

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Demonstrates sending text and file attachments via session.prompt and handling session cancellation.

```rust
async fn send(session: &Session, text: String, files: Vec<PathBuf>) -> Result<(), AgentError> {
    let mut input = Input::text(text);
    for f in files { input = input.attach(f); }
    match session.prompt(input).await?.kind {
        DeliveryKind::Started { .. } | DeliveryKind::Steered { .. } => {}
        DeliveryKind::Queued { position } => ui.show_queued(position),
    }
    Ok(())
}

// stop button
session.cancel(false).await?;    // true also drops queued prompts
```

--------------------------------

### Runtime::generate(&agent, options, prompt)

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/core-api.mdx

Performs a one-shot text generation task by opening a session, prompting the agent, and closing the session.

```APIDOC
## Runtime::generate(&agent, options, prompt)

### Description
Performs a one-shot text generation task by opening a session, prompting the agent, and closing the session.

### Parameters
- **agent** (AgentInstallation) - The agent to use.
- **options** (SessionOptions) - Configuration options.
- **prompt** (String) - The text prompt to send.

### Returns
- **String** - The generated text response.
```

--------------------------------

### runtime.probe(&agent)

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Queries the agent for its capabilities, configuration, and authentication status by opening a temporary session.

```APIDOC
## runtime.probe(&agent)

### Description
Queries the agent to retrieve its version, real login state, capabilities, and configuration options. This operation opens a temporary session.

### Method
Async Method

### Parameters
- **agent** (Agent) - Required - The agent instance to probe.

### Response
- **details** (AgentDetails) - Contains auth status, capabilities, and config options.
```

--------------------------------

### Configure session options

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Configures agent settings like model and effort. Options can be set at creation or updated mid-session if marked as live.

```rust
// at open: creation-only and live options alike
let options = SessionOptions::in_dir(".").configure("model", "sonnet").configure("effort", "low");

// mid-session: options with `live: true`
session.configure("fast", true).await?;
```

--------------------------------

### Add anyagent dependency

Source: https://github.com/spotta85/anyagent-rs/blob/main/README.md

Add the anyagent crate to your Cargo.toml file.

```toml
[dependencies]
anyagent = "0.0.1"
```

--------------------------------

### Persist and resume session

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Loads session information and uses the resume token to reopen a session. The resume token must be stored as-is.

```rust
// tomorrow, after restart
let info = store.load_info(thread_id);
let token = info.resume_token.clone().ok_or("this agent cannot resume")?;
let (session, events) = runtime
    .open(&info.agent, SessionOptions::in_dir(&repo).resume(token))
    .await?;
```

--------------------------------

### Handling agent permissions and questions

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Responds to permission requests and questions forwarded by the agent. Use RequestClosed to clear UI elements.

```rust
EventKind::RequestOpened(Request::Permission(r)) => {
    // r.tool is the ToolUpdate awaiting approval; r.options is what the agent accepts
    session.answer(r.id, Answer::Permission(PermissionChoice::AllowOnce)).await?;
}
EventKind::RequestOpened(Request::Question(r)) => {
    // one QuestionAnswer per question, in order; Choices(ids) or Text(string)
    let answers = r.questions.iter().map(|q| QuestionAnswer::Choices(vec![q.choices[0].id.clone()])).collect();
    session.answer(r.id, Answer::Question(answers)).await?;
}
EventKind::RequestClosed { request_id } => ui.clear(request_id),
```

--------------------------------

### Session

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/core-api.mdx

Methods for interacting with a live agent session, including sending prompts, answering requests, and managing session state.

```APIDOC
## Session

### Description
Handle for a live conversation. Used to send prompts, answer requests, configure settings, and manage the session lifecycle.

### Methods
- **prompt(input)** - Sends text or an `Input` with attachments. Returns a `Delivery`.
- **dequeue(prompt_id)** - Drops a queued prompt before it starts.
- **answer(request_id, answer)** - Answers a permission or question request.
- **configure(id, value)** - Changes a live configuration option.
- **rollback(turns, scope)** - Rewinds completed turns.
- **compact()** - Requests the agent to summarize its context.
- **cancel(clear_queue)** - Stops the running turn.
- **close()** - Ends the agent session.
- **info()** - Returns a snapshot of agent details and configuration.
- **status()** - Returns current status (`Idle`, `Working`, or `NeedsInput`).
```

--------------------------------

### Configure Cargo.toml dependencies

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/quickstart.mdx

The resulting dependencies added to your Cargo.toml file.

```toml
[dependencies]
anyagent = "0.0.1"
futures = "0.3"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
```

--------------------------------

### Compact session context

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Summarizes the agent's context to free window space without losing the thread. Compaction runs as an agent-originated turn.

```rust
session.compact().await?;
```

--------------------------------

### Configure Agent Session Isolation

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/agents.mdx

Set a custom configuration directory for an agent session using config_home. AnyAgent will set the corresponding environment variable for the process; failure to support this results in an InvalidConfiguration error.

```rust
SessionOptions::in_dir(".").config_home("/path/to/work-account")
```

--------------------------------

### Resume session with resume_token

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Continues a conversation from a new process using a stored resume_token. The agent regains its context, but old events are not replayed.

```rust
let token = session.info().resume_token.clone().unwrap();   // grab it while alive
// later, any process
let (session, events) = runtime
    .open(&agent, SessionOptions::in_dir(".").resume(token))
    .await?;
```

--------------------------------

### One-shot generation with runtime.generate

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Performs a single prompt-to-string generation without managing a persistent session. It automatically disables tools and rejects permissions, returning a String.

```rust
let title = runtime
    .generate(&agent, SessionOptions::in_dir("."), "a five-word title for: fix the parser")
    .await?;
```

--------------------------------

### Runtime::probe(&agent)

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/core-api.mdx

Opens a throwaway session to retrieve detailed information about an agent, including version, authentication, capabilities, and configuration options.

```APIDOC
## Runtime::probe(&agent)

### Description
Opens a throwaway session to retrieve detailed information about an agent, including version, authentication, capabilities, and configuration options.

### Parameters
- **agent** (AgentInstallation) - The agent to probe.

### Returns
- **AgentDetails** - Detailed information about the agent.
```

--------------------------------

### App architecture diagram

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

A visual representation of the application layout and the flow between the UI components and the agent session.

```text
 ┌──────────────── your app ────────────────┐
 │ thread list │ chat view      │ settings  │
 │  badges     │ text, tools,   │ permissions    │ model,    │
 │             │                │ effort    │
 └──────┬──────┴───────▲────────┴─────┬─────┘
        │              │              │
   StatusChanged    Events        configure()
        │              │              │
        └──────► Session ◄────────────┘
                    │
                agent process
```

--------------------------------

### Generate titles with runtime.generate

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Uses a throwaway session with tools disabled to generate a short title for a prompt and store it.

```rust
let title = runtime
    .generate(&agent, SessionOptions::in_dir(&repo), format!("five-word title for: {first_prompt}"))
    .await?;
store.set_title(thread_id, title);
```

--------------------------------

### session.configure

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Updates session configuration options dynamically without requiring a restart.

```APIDOC
## session.configure(key: string, value: any)

### Description
Updates agent settings such as model, effort, mode, or sandbox. Options must be present in the agent's current config_options.

### Parameters
- **key** (string) - Required - The configuration ID (e.g., 'model', 'effort', 'fast', 'mode', 'sandbox').
- **value** (any) - Required - The value to set for the configuration.

### Returns
- **SessionUpdated** (Event) - Emitted upon successful configuration change, carrying the new configuration and rebuilt config_options.
```

--------------------------------

### Architecture Layer Diagram

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/architecture.mdx

A visual representation of the three-layer architecture, showing the flow from the Public API down to the agent process.

```text
 ┌───────────────────────────────────────────────────────────┐
 │  1. Public API        Runtime · Session · Events           │  what your app sees
 ├───────────────────────────────────────────────────────────┤
 │  2. Engine            one task per session                 │  the rules: turns, queue,
 │                       (src/session.rs)                     │  requests, status, cleanup
 ├───────────────────────────────────────────────────────────┤
 │  3. Adapters          claude · codex · opencode · pi ·     │  one protocol each,
 │                       antigravity · acp                    │  zero rules
 └───────────────────────────────────────────────────────────┘
                                │
                         agent process (stdio or HTTP)
```

--------------------------------

### Claude CLI configuration for wire recordings

Source: https://github.com/spotta85/anyagent-rs/blob/main/tests/fixtures/claude/README.md

The command-line arguments used to generate the wire recordings, ensuring stream-json formatting and verbose output.

```bash
claude -p --output-format stream-json --input-format stream-json --verbose
       --include-partial-messages --permission-prompt-tool stdio
       --replay-user-messages --model sonnet
```

--------------------------------

### Configure mock testing in Cargo.toml

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Adds the anyagent mock feature as a development dependency.

```toml
[dev-dependencies]
anyagent = { version = "0.0.1", features = ["mock"] }
```

--------------------------------

### Run agy with stream-json format

Source: https://github.com/spotta85/anyagent-rs/blob/main/tests/fixtures/antigravity/README.md

The base command used for all wire recordings to enable stream-json input and output formats.

```bash
agy --input-format=stream-json --output-format=stream-json [flags]
```

--------------------------------

### Rebuild settings menu

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Clears and rebuilds the settings menu based on session configuration options. It handles dropdowns and boolean toggles, triggering configuration updates asynchronously.

```rust
fn rebuild_settings(ui: &Ui, session: &Session, info: &SessionInfo) {
    ui.clear_settings();
    for option in &info.details.config_options {
        let session = session.clone();
        let id = option.id.clone();
        match &option.kind {
            ConfigKind::Select { choices } => ui.dropdown(&option.name, choices, &option.current, move |v| {
                let s = session.clone(); let id = id.clone();
                async move { s.configure(id, v).await }
            }),
            ConfigKind::Boolean => ui.toggle(&option.name, &option.current, move |b| {
                let s = session.clone(); let id = id.clone();
                async move { s.configure(id, b).await }
            }),
            _ => {}
        }
    }
}
```

--------------------------------

### Agent lifecycle event flow

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/quickstart.mdx

A text representation of the agent lifecycle events.

```text
discover()  →  report.agents (installed)  +  report.missing (with install hints)
open()      →  spawns the agent, handshakes, returns (Session, Events)
prompt()    →  starts a turn
Events      →  TurnStarted, TextDelta…, TurnEnded
close()     →  ends the process
```

--------------------------------

### Define a scripted agent for testing

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Creates a scripted agent using the mock module to simulate real engine events and turn rules.

```rust
use anyagent::mock::{Script, Step, completed, permission, text};

let script = Script::default().turn(vec![
    Step::Emit(text("m1", "hello")),     // TextDelta
    Step::Emit(permission("p1")),        // RequestOpened
    Step::AwaitAnswer,                   // pause until your app answers
    Step::End(completed()),              // TurnEnded
]);
let runtime = Runtime::with_mock(script);
let agent = runtime.discover().await.require("mock")?.clone();
```

--------------------------------

### Antigravity Discovery Logic

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/agents.mdx

Visual representation of the discovery process for the Antigravity agent, showing the branching logic between ACP server and headless agy wire.

```text
discover("antigravity")
  ├─ ACP server found  ──►  open over ACP: permissions, questions,
  │                         in-process cancel, live mode and model switch,
  │                         images, PDFs, diffs, slash commands
  │                         (Gemini models only)
  └─ only `agy` found  ──►  open over agy's headless stream-json wire:
                            text, tools, resume, context usage, cancel by
                            respawn; every model `agy models` lists
                            → installation.upgrade names the server
```

--------------------------------

### session.answer(request_id, answer)

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Provides a response to an agent's request for permission or clarification.

```APIDOC
## session.answer(request_id, answer)

### Description
Responds to a RequestOpened event (Permission or Question) from the agent.

### Parameters
- **request_id** (String) - Required - The ID of the request being answered.
- **answer** (Answer) - Required - The specific choice or text response provided by the user.
```

--------------------------------

### Override Agent Binary Path

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/agents.mdx

Use the ANYAGENT_<AGENT>_BIN environment variable to point to a specific binary path, bypassing standard discovery.

```bash
ANYAGENT_CLAUDE_BIN=/path/to/claude cargo run --example probe
```

--------------------------------

### Render agent events with match statement

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Uses a match statement to handle various event kinds, filtering out nested events to ensure they are rendered under their parent tool.

```rust
fn render(ui: &Ui, thread: ThreadId, event: Event) {
    let nested = event.turn_info.as_ref().is_some_and(|t| t.parent_tool_id.is_some());
    match event.kind {
        // content
        EventKind::TextDelta { message_id, text } if !nested => ui.append(thread, message_id, text),
        EventKind::ReasoningDelta { text, .. } if !nested => ui.append_thinking(thread, text),
        EventKind::MessageEnded { message_id } => ui.finish_message(thread, message_id),

        // tools: ToolUpdated is a full snapshot, replace by id
        EventKind::ToolUpdated(tool) => ui.upsert_tool(thread, event.turn_info, tool),
        EventKind::ToolOutputDelta { tool_id, text } => ui.append_tool_output(thread, tool_id, text),
        EventKind::PlanUpdated { entries } => ui.set_plan(thread, entries),   // replaces, not appends

        // requests: step 6
        EventKind::RequestOpened(request) => ui.open_request(thread, request),
        EventKind::RequestClosed { request_id } => ui.close_request(thread, request_id),

        // session state
        EventKind::StatusChanged(status) => ui.set_badge(thread, status),
        EventKind::SessionUpdated(info) => { store.save_info(thread, &info); ui.rebuild_settings(thread, &info) }
        EventKind::ContextUsage { used_tokens, window_tokens, .. } => ui.set_gauge(thread, used_tokens, window_tokens),

        // turn boundaries
        EventKind::TurnStarted { .. } => ui.start_turn(thread),
        EventKind::TurnEnded { stop, background } => ui.end_turn(thread, stop, background),

        EventKind::Diagnostic(d) => tracing::warn!(?d),
        _ => {}
    }
}
```

--------------------------------

### Process Events in a Background Task

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Spawns a tokio task to consume events from the session stream, store them, and trigger UI rendering. It ensures thread closure is signaled when the event stream ends.

```rust
let thread_id = thread.id;
let ui = ui.clone();
tokio::spawn(async move {
    while let Some(event) = events.next().await {
        let event = match event {
            Ok(e) => e,
            Err(err) => { ui.thread_failed(thread_id, err); break }
        };
        store.append(thread_id, &event);
        render(&ui, thread_id, event);
    }
    ui.thread_closed(thread_id);       // the stream ended: close() or the agent died
});
```

--------------------------------

### Record wire communication

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/contributing.mdx

Capture raw wire communication to a JSONL file for debugging agent behavior.

```rust
SessionOptions::in_dir(".").record_wire("/tmp/claude.jsonl")
```

--------------------------------

### Codebase Directory Structure

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/architecture.mdx

A map of the source code organization, highlighting the separation of concerns across the three layers.

```text
src/
├── lib.rs           public exports
├── runtime.rs       layer 1: Runtime (discover, probe, open, generate, plan_usage)
├── session.rs       layer 2: the engine, plus Session and Events handles
├── event.rs         the public event and request types
├── agent.rs         AgentInstallation, AgentDetails, Capability, SessionOptions
├── error.rs         AgentError
├── catalog.rs       per-agent facts as data: ids, launch flags, login markers
├── discovery.rs     finds executables and login markers; never launches
├── process.rs       spawns children, guarantees cleanup
└── adapter/         layer 3
    ├── mod.rs         the seam: Adapter trait, DriverCommand, DriverEvent
    ├── claude.rs      native stream-json
    ├── codex.rs       native app-server JSON-RPC
    ├── opencode.rs    native HTTP + SSE against `opencode serve`
    ├── pi.rs          native pi RPC
    ├── antigravity.rs native agy headless stream-json
    ├── acp.rs         one adapter for every ACP agent
    ├── wire.rs        line-delimited JSON over stdio, plus the recorder
    ├── attach.rs      attachment loading shared by adapters
    ├── mock.rs        scripted adapter (feature `mock`)
    └── conformance.rs engine contract tests, run over the mock
```

--------------------------------

### Probe agent capabilities and authentication status

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Uses runtime.probe to retrieve agent details, including authentication status and login methods. The AuthStatus enum handles authenticated, unauthenticated, and unknown states.

```rust
let details = runtime.probe(&agent).await?;
match &details.auth {
    AuthStatus::Authenticated { kind, account } => {}       // Subscription | ApiKey | CloudProvider
    AuthStatus::Unauthenticated { login } => {
        for method in login {
            match method {
                LoginMethod::Terminal { command, .. } => ui.show_command(command),  // e.g. ["claude", "auth", "login"]
                LoginMethod::EnvVar { name } => ui.show_env_var(name),
                _ => {}
            }
        }
    }
    AuthStatus::Unknown => {}
}
```

--------------------------------

### Handle subagent events

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Manages subagent spawning and event tracking. Subagents render as a tree structure, and anyagent handles child turn bookkeeping.

```rust
EventKind::ToolUpdated(tool) if tool.kind == ToolKind::Subagent => ui.open_child(tool.id),
// every event the child produces:
let parent = event.turn_info.as_ref().and_then(|t| t.parent_tool_id.clone());
```

--------------------------------

### Gate feature buttons

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Controls the visibility of feature buttons based on agent capabilities.

```rust
let caps = &info.details.capabilities;
ui.show_fork(caps.supports(Capability::Fork));
ui.show_rollback(caps.supports(Capability::Rollback), caps.supports(Capability::RollbackFiles));
ui.show_compact(caps.supports(Capability::Compact));
```

--------------------------------

### AgentDetails struct definition

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/core-api.mdx

The AgentDetails struct provides the agent's version, authentication status, capabilities, configuration options, and available slash commands.

```rust
pub struct AgentDetails {
    pub version: Option<String>,
    pub auth: AuthStatus,               // Authenticated { kind, account } | Unauthenticated { login } | Unknown
    pub capabilities: Capabilities,     // .supports(Capability::Fork)
    pub config_options: Vec<ConfigOption>,  // id, name, kind (Select | Boolean), current, live
    pub commands: Vec<SlashCommand>,
}
```

--------------------------------

### session.cancel

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Stops the currently running turn while maintaining the session context. Optionally clears the prompt queue.

```APIDOC
## session.cancel(drop_queue: bool)

### Description
Stops the running turn. The session and its context survive.

### Parameters
- **drop_queue** (bool) - Required - If true, drops the queued prompts; if false, keeps them.

### Returns
- **TurnEnded** (Event) - Confirms the turn has ended with status Cancelled.
- **RequestClosed** (Event) - Emitted for any request the turn had open.
```

--------------------------------

### session.status

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Retrieves the current status of the session.

```APIDOC
## session.status()

### Description
Returns the current status of the session, which can be 'Idle', 'Working', or 'NeedsInput'.

### Returns
- **status** (string) - The current session status.
```

--------------------------------

### Probe authentication status

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/building-an-app.mdx

Checks if the selected agent is authenticated. If unauthenticated, it retrieves and displays the necessary login commands or environment variable hints.

```rust
let details = runtime.probe(&agent).await?;
if let AuthStatus::Unauthenticated { login } = &details.auth {
    for method in login {
        match method {
            LoginMethod::Terminal { command, description, .. } => ui.login_button(command, description),
            LoginMethod::EnvVar { name } => ui.env_hint(name),
            _ => {}
        }
    }
    return Ok(());
}
```

--------------------------------

### session.dequeue(prompt_id)

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Removes a queued prompt from the session before it begins execution.

```APIDOC
## session.dequeue(prompt_id)

### Description
Drops a prompt that is currently in the queue.

### Parameters
- **prompt_id** (String) - Required - The identifier of the queued prompt to remove.
```

--------------------------------

### DriverCommand and DriverEvent Communication Contract

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/architecture.mdx

The communication flow between the engine and the adapter using DriverCommand and DriverEvent enums.

```text
              DriverCommand (engine → adapter)
              ────────────────────────────────►
   Engine     StartTurn · Steer · Answer · Configure       Adapter
              Rollback · Compact · Cancel · Close
              ◄────────────────────────────────
              DriverEvent (adapter → engine)
              Event { kind, parent_tool_id, extensions }
              TurnAck · TurnEnded · Steered · InfoChanged
              AuthLost · Exited
```

--------------------------------

### Rollback session turns

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Rewinds the session by a specified number of turns. ConversationAndFiles scope writes to the working tree, so check RollbackFiles gate before use.

```rust
session.rollback(NonZeroU32::new(2).unwrap(), RollbackScope::Conversation).await?;
session.rollback(NonZeroU32::new(1).unwrap(), RollbackScope::ConversationAndFiles).await?;
```

--------------------------------

### Monitor session status

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Tracks the agent status (Idle, Working, or NeedsInput). Status changes are emitted via events and can be queried on demand.

```rust
EventKind::StatusChanged(status) => ui.set_badge(thread, status),
let now = session.status();    // for a component that mounts late
```

--------------------------------

### ToolUpdate Structure Definition

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/core-api.mdx

The ToolUpdate struct provides a cumulative snapshot of a tool call, which should be replaced by ID rather than merged.

```rust
pub struct ToolUpdate {
    pub id: ToolId,
    pub kind: ToolKind,          // Read, Edit, Execute, Mcp { server, tool }, Subagent, …
    pub title: String,           // ready to display
    pub status: ToolStatus,
    pub input: ToolInput,
    pub output: Option<String>,
    pub diffs: Vec<FileDiff>,    // typed, for edits
    pub locations: Vec<PathBuf>, // files it touched
    pub raw: Option<RawTool>,    // the agent's own name and raw input
}
```

--------------------------------

### session.rollback

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Rewinds the current session by a specified number of turns within a defined scope.

```APIDOC
## session.rollback(turns, scope)

### Description
Rewinds the session in place by a specified number of turns. The operation confirms with a `SessionUpdated` event.

### Parameters
- **turns** (NonZeroU32) - Required - The number of turns to rewind.
- **scope** (RollbackScope) - Required - The scope of the rollback (`Conversation` or `ConversationAndFiles`).

### Usage
```rust
session.rollback(NonZeroU32::new(2).unwrap(), RollbackScope::Conversation).await?;
```
```

--------------------------------

### Cancel a running turn

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/features.mdx

Stops the current turn while keeping the session and context alive. Passing true to cancel drops the queued prompts.

```rust
session.cancel(false).await?;   // stop the turn, keep queued prompts
session.cancel(true).await?;    // stop the turn, drop the queue too
```

--------------------------------

### Event Structure Definition

Source: https://github.com/spotta85/anyagent-rs/blob/main/docs/core-api.mdx

The Event struct represents a single unit of agent activity, containing sequence information, timestamps, and the specific event kind.

```rust
pub struct Event {
    pub sequence: u64,                   // 1, 2, 3… per session; the true order
    pub occurred_at: SystemTime,         // wall clock, for stored transcripts
    pub session_id: SessionId,
    pub turn_info: Option<TurnContext>,  // { id, parent_tool_id } when inside a turn
    pub kind: EventKind,
    pub extensions: Extensions,          // provider data, keyed "provider/name"
}
```
Tokens:
Raw