Crate agent_abstraction

Expand description

Drive Claude Code, Codex and GitHub Copilot headlessly from Rust.

One request type, one event vocabulary and one session model across three agent CLIs that agree on none of those things. This is a library: your program links it and spawns the agent itself, with no intermediate CLI marshalling a request through stdout and back.

§Running a prompt

use agent_abstraction::{Agent, Permission, Request, run};

let outcome = run(
    &Request::new(Agent::Claude, "Reply with the single word: pong")
        .model("haiku")
        .permission(Permission::ReadOnly),
)
.await?;

println!("{}", outcome.text);

§Watching one as it works

use agent_abstraction::{Agent, Event, Request, stream};

let mut running = stream(&Request::new(Agent::Claude, "audit this repo"))?;
while let Some(event) = running.recv().await {
    match event {
        Event::Text(text) => print!("{text}"),
        Event::ToolCall { name, .. } => println!("[{name}]"),
        _ => {}
    }
}
let outcome = running.finish().await?;

§Multi-turn conversations

Thread one stable name across turns and let SessionStore map it to whatever handle the agent understands:

use agent_abstraction::{Agent, Request, SessionStore, run};

let store = SessionStore::open("/var/lib/myapp/sessions");

// First turn creates the session; later turns continue it.
let first = Request::new(Agent::Claude, "remember the number 7")
    .session(&store, ".", "thread-42", false)?;
run(&first).await?;

let second = Request::new(Agent::Claude, "what number did I say?")
    .session(&store, ".", "thread-42", false)?;
println!("{}", run(&second).await?.text);

§What each agent can do

	session id	fork	events	system prompt
Claude Code	caller-minted (`--session-id`)	yes	yes	native flag
Codex	agent-printed (`thread_id`)	no	yes	prepended
Copilot	caller-minted (`--session-id`)	no	yes	prepended

Asking for something an agent cannot do is always an Error::Unsupported, never a silent downgrade. A caller that asked to fork and got a linear resume would corrupt the conversation it meant to branch.

§Operating within the agents’ terms

This crate drives each vendor’s own supported headless interface with the credentials that CLI already uses. It does not reimplement a provider API, multiplex accounts, or retry around a quota: a refusal surfaces as Error::RateLimited, carrying the provider’s own wording, and backing off is the caller’s decision. See docs/operating-limits.md.

Structs§

AccountUsage: What an account has spent and what it has left.
Approval: A tool call the agent is waiting for permission to make.
AuthStatus: What an agent reported about its credentials.
Caps: What an agent supports. Used to reject an impossible request before spawning rather than silently doing something weaker than asked.
Commands: What the running agent reports it can do, from its own catalogue.
Credits: A pay-as-you-go balance.
DailyUsage: One day’s total.
Lifetime: All-time counters.
Model: One model a caller can choose.
Outcome: The result of one completed run.
Probe: What an installed agent CLI reported about itself.
RateLimit: A quota signal the agent emitted mid-run.
Request: A run, described but not yet started.
Run: A run in progress.
RunControl: A cloneable route for sending input to a live Run.
SessionRecord: One named conversation.
SessionStore: The store of named sessions.
Usage: Token and cost accounting for a run.
UsageWindow: One quota window and how much of it is gone.
Verified: How a catalogue was established, so a stale one can be recognised as stale.
Version: A three-part version, compared numerically.

Enums§

Agent: A coding agent this crate can drive headlessly.
AuthState: Whether an agent has usable credentials.
Command: A slash command a run can carry instead of a prompt.
Compaction: How far a /compact got.
Decision: What to do about an Approval.
EnvPolicy: Which of the host’s environment variables reach the agent.
Error: Everything that can go wrong driving an agent CLI.
Event: One normalized thing an agent did, agent-agnostic so a single renderer works across all three.
Format: Output shape requested from the agent.
Kind: Whether an id names a specific model or points at whichever is current.
Permission: Permission posture for a run, mapped onto each agent’s own vocabulary.
Phase: Whether the next turn starts a conversation or continues one.
SessionSupport: How an agent’s native session id is obtained. This is the axis deciding whether a caller-owned session name can be bound to it at all.
Source: The kind of evidence behind a catalogue.
Stop: Why the agent stopped.
VersionStatus: How an installed CLI relates to the release this crate was verified against.

Constants§

MAX_CAPTURE: The ceiling on any single captured buffer.
MAX_EVENT_BYTES: The ceiling on any single event’s payload.
MAX_LINE: The ceiling on a single output line before it is truncated.
NETWORK_ENV: Environment variables that route an agent’s traffic through a corporate proxy or a custom certificate authority.
TRUNCATION_MARK: Marks a payload this crate shortened, so a truncated value is never mistaken for what the agent actually produced.

Functions§

run: Run request to completion, discarding the intermediate events.
stream: Start request, returning a handle that streams its events.

Type Aliases§

Result: Result alias for this crate.