Features

Everything anyagent does. Each section says what it is for, how to use it, what confirms it, and which capability gates it.

Every section has the same four parts: what it does, how to call it, what confirms it happened, and what gates it. Types and signatures are on the Core API page. Which agents support what is on the Agents page.

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

Discovery

What: find every supported agent on the machine, instantly, without launching anything. Checks env overrides, PATH, the login-shell PATH (GUI apps often miss it), and known install directories. Agents that are supported but missing come back with an install hint.

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

Confirms: the report itself. Discovery never guesses login state; probe or probe_auth asks the agent. Gates: none. Call runtime.prewarm() at startup to scan early.

Not found? MissingAgent.searched lists every directory that was checked, so an app can show it and offer a file picker. A user with an unusual install sets ANYAGENT_<AGENT>_BIN (see Agents). An installer that edits the user’s PATH is invisible to an app that is already running: say “installed? restart the app”, not “not found”.

Some agents have a richer, separately installed runtime (Antigravity’s ACP server). When only the base CLI is found, agent.upgrade names what to install for more capabilities.

Probe and auth

What: ask the agent itself what it can do. Opens a throwaway session (about 1 s) and returns version, real login state, capabilities, config options, and slash commands. probe_auth is the cheaper call when you only need the login state.

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 => {}
}

Confirms: AgentDetails. The same struct is available later as session.info().details. Gates: none.

anyagent never reads or holds credentials and never drives a login flow. It tells you the exact command or env var to show the user. Keep several logins of one agent apart with SessionOptions::config_home(dir).

Sessions

What: one live conversation with one agent process. open spawns the agent, handshakes, and returns two halves: Session (commands, cheap to clone) and Events (the stream, one consumer).

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

Confirms: open returns. session.info() has the resume token, capabilities, and config options. Gates: none. Fails typed: AuthRequired { login } when logged out, HandshakeTimeout after 30 s, ResumeFailed for a bad token.

Drain Events continuously. It buffers 1024 events; a consumer that falls a full buffer behind is treated as gone and the session closes. close() ends the process; dropping Events does the same.

Prompting

What: send text, slash commands, and file attachments. What happens depends on session state, and the returned Delivery tells you which.

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 state	Agent has Steer	Result
Idle	any	Started
Turn running	yes	Steered: the agent changes course mid-turn
Turn running	no	Queued: starts its own turn when the current one ends

Confirms: TurnStarted { origin: Prompt(id) } for started and queued prompts. Gates: Steer decides steer vs queue. Images decides whether an attachment goes inline or degrades to a path in the prompt text.

Drop a queued prompt before it starts with session.dequeue(prompt_id). Slash commands from details.commands are sent as plain text: session.prompt("/review"). An unknown slash prompt is just text.

Permissions and questions

What: the agent’s “may I run this?” and “which one?” moments, forwarded as typed requests with the choices the agent actually offers. Answer exactly once.

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),

Confirms: RequestClosed. It also arrives when a cancelled turn withdraws the request, so clear your UI on that event, not on your own answer. While a request is open, session.status() is NeedsInput. Gates: Permissions and Questions. An agent without Permissions runs tools without asking.

For unattended runs, open with SessionOptions::permission_mode(PermissionMode::AutoApprove): anyagent allows each request once without forwarding it.

Cancel

What: stop the running turn. The session and its context survive.

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

Confirms: TurnEnded { stop: Cancelled }, then RequestClosed for any request the turn had open. Gates: none.

Configuration

What: models, effort, mode, sandbox, switched without a restart. Agents advertise their settings as ConfigOptions with typed choices, so a picker renders what the agent offers instead of a hardcoded list.

// 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?;

id	Kind	Notes
model	select	Switching it rebuilds the other options’ choices
effort	select	Choices follow the model; a model without levels drops the option
fast	boolean	Only when the selected model supports it. Lower latency, higher usage
mode	select	Agent-specific: plan, accept-edits, ask, …
sandbox	select	Codex

Confirms: SessionUpdated, carrying the new configuration and the rebuilt config_options. Wait for it rather than for configure to return. Gates: the option must be in details.config_options, else InvalidConfiguration.

Status

What: the one value a thread list needs. Idle, Working, or NeedsInput, pushed on every change and readable on demand.

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

Confirms: StatusChanged is emitted only on change. A turn ending with another prompt queued stays Working, never flashing Idle. Gates: none.

One-shot generation

What: prompt in, string out, no session to manage. For thread titles, commit messages, branch names, PR bodies.

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

It opens a throwaway session, disables tools where the wire allows (claude, pi) and declines every permission elsewhere, collects the text until the turn ends, and closes.

Confirms: the returned String. Gates: Permissions, or a wire that can launch without tools. Requires a new session: resume and fork_from options are rejected. A tool event or a question needing a choice cancels generation. Put context inline; attachments cannot be opened without tools.

Resume

What: continue a conversation from a new process. Every session mints an opaque resume_token; store it with your transcript.

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?;

Confirms: open returns; the agent has its context back. No old events are replayed, so keep your own transcript. Gates: Resume, else ResumeFailed. The token is agent-owned: store it as-is, never parse it. The session id is not a resume token.

Fork

What: a new session starting from an old one’s history. The original is untouched, which is what “try this a different way” needs.

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

Confirms: open returns a new session with its own resume token. Gates: Fork.

Rollback

What: rewind this session in place by whole turns.

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

Scope	Rewinds	Gate
Conversation	The agent’s context only	Rollback
ConversationAndFiles	Context and the files those turns changed	RollbackFiles

Confirms: SessionUpdated. A refusal comes back as a Diagnostic, not an error from the call. Gates: above, plus an idle session (SessionBusy otherwise).

ConversationAndFiles writes to the working tree. Check RollbackFiles before offering the button and tell the user what it does.

Compact

What: ask the agent to summarize its own context, freeing room in the window without losing the thread.

session.compact().await?;

Confirms: ContextCompacted, then a lower ContextUsage. Compaction runs as an agent-originated turn: prompts sent meanwhile queue behind it. An agent that finds nothing to summarize says so as a Diagnostic. Gates: Compact (claude, codex, opencode, pi) and an idle session.

Subagents

What: agents that spawn agents render as a tree, not interleaved noise.

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());

Confirms: parent_tool_id on the child’s events. A child can never end the parent’s turn; anyagent consumes the child’s turn bookkeeping. Gates: Subagents.

Context and plan usage

What: the two gauges apps show. They measure different things.

Gauge	Source	Measures
Context usage	EventKind::ContextUsage { used_tokens, window_tokens, cost_usd }	How full this session’s window is
Plan usage	runtime.plan_usage(&agent), EventKind::PlanUsageUpdated	How much of the account’s subscription is used, per window

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);
}

Confirms: the events and return values above. Numbers come from the agent itself: no HTTP endpoints, no token handling. Gates: ContextUsage and PlanUsage. Plan usage also needs a subscription login (AuthKind::Subscription).

MCP servers

What: hand the agent your app’s MCP servers for this session.

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"));

Confirms: calls into your servers arrive as ToolUpdated with ToolKind::Mcp { server, tool }. Gates: the agent’s supported transports. An unsupported transport fails open typed rather than dropping the server.

Wire recording

What: a bug report that contains the actual bug. Tees every raw protocol frame, both directions, to a JSONL file.

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

Confirms: the file. A recording failure never fails a turn. Gates: none.

The recording is unredacted: prompts, file contents, command output, paths. Treat it as sensitive and delete it after debugging.

Testing without a subprocess

What: run your app over a scripted agent. The engine, turn rules, and event shapes are real; only the agent is fake.

Cargo.toml

[dev-dependencies]
anyagent = { version = "0.0.2", features = ["mock"] }

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();

Confirms: the same events your real code handles. Gates: feature mock. Script flags (steer, deterministic, buffer, …) model the wire shapes the engine has to cope with.