Crate nanocodex_agent

Expand description

§Nanocodex Agent

The owned lifecycle for one headless OpenAI coding agent.

nanocodex-agent composes the Tower-native Responses state machine from nanocodex-oai-api with the runtime from nanocodex-tools. A normal consumer builds one agent, receives a cheap cloneable Nanocodex handle and an independent AgentEvents stream, then submits ordered prompts.

§Quick start

use nanocodex_agent::{Nanocodex, OpenAi};

let openai = OpenAi::new(std::env::var("OPENAI_API_KEY")?)?;
let (agent, _events) = Nanocodex::builder(openai)
    .instructions(
        "You are a Rust coding agent. Preserve unrelated work and run relevant tests.",
    )
    .workspace(std::env::current_dir()?)
    .build()?;

let result = agent
    .prompt("Explain the cause of the failing parser test.")
    .await?
    .await?;
println!("{}", result.final_message());
agent.shutdown().await?;

The first await means the private driver accepted and ordered the prompt. Turn is both a per-turn event stream and a future for TurnResult. Awaiting the turn waits only for its result; event consumption is independent.

The private driver is the sole owner of mutable conversation, transport, tool, and process state. Cloning Nanocodex only clones its command capability; Nanocodex::spawn creates a clean sibling and Nanocodex::fork creates an independent branch from committed history.

§Remote tool environments

When tools execute in a VM or remote workspace, provide one coherent snapshot of the facts described to the model. This prevents host time and AGENTS.md discovery from being mixed with a different tool filesystem:

use nanocodex_agent::{ExecutionEnvironment, Nanocodex, OpenAi};

let environment = ExecutionEnvironment::new("2026-07-29", "Etc/UTC")
    .project_instructions("Preserve generated files under build/.");
let (_agent, _events) = Nanocodex::builder(openai)
    .execution_environment(environment)
    .build()?;

Omit ExecutionEnvironment::project_instructions when the remote workspace has no project instructions. Without an execution environment, native agents continue discovering date, timezone, and project instructions from the local embedding host.

§Typed events

AgentEvents is optional and independent from turn results. Its raw JSONL-compatible envelope remains lossless, while AgentEvent::data provides a normalized domain view:

use futures_util::StreamExt;
use nanocodex_agent::{
    Nanocodex, OpenAi,
    events::{AgentEventData, AssistantEvent},
};

let openai = OpenAi::new(std::env::var("OPENAI_API_KEY")?)?;
let (agent, mut events) = Nanocodex::builder(openai)
    .instructions("Answer concisely and preserve exact identifiers.")
    .build()?;
let turn = agent.prompt("Explain the identifier req_7f3.").await?;

while let Some(event) = events.next().await {
    if let AgentEventData::Assistant(AssistantEvent::Delta(delta)) = event.data()? {
        print!("{}", delta.text);
    }
    if event.kind.is_terminal() {
        break;
    }
}
let _result = turn.await?;
agent.shutdown().await?;

§Components

events contains the complete typed lifecycle event taxonomy.
input contains prompts and multimodal user input.
session contains durable session identities and snapshots.
usage contains token accounting and USD estimates.
rollout records and restores Codex-compatible sessions.
transport exposes advanced Responses and Tower configuration.
tools exposes the complete tool implementation surface.

OpenAI API-key and managed ChatGPT credentials belong to nanocodex_oai_api::auth, independently of this lifecycle crate.

Re-exports§

pub use usage::TurnUsage;

Modules§

events: Complete typed lifecycle events emitted by an agent.
input: Prompts and multimodal user input accepted by the agent.
rolloutNon-target_family=wasm: Codex-compatible durable rollout recording and restoration.
session: Durable agent session identities and snapshots.
tools: Complete tool contracts, registry, built-ins, Code Mode, and MCP.
transportNon-target_family=wasm: Advanced Responses transport and Tower service configuration.
usage: Per-turn token accounting and USD estimates.

Structs§

AgentEvents: The receiving half of an agent’s typed event stream.
AgentHandle: Weak child-agent capability for the driver that owns one tool runtime.
AgentSessionContext: Read-only model context exposed to session adapters.
EstimatedUsdCost: Exact estimated USD cost for provider-reported token usage.
ExecutionEnvironment: Model-visible facts owned by a remote tool-execution environment.
Nanocodex: Cheap, cloneable command handle for an owned agent driver.
NanocodexBuilder: Builder for one owned agent lifecycle.
OpenAi: Configured, cloneable OpenAI client recipe.
ResponseError: Cloneable typed failure returned by a response stream and its completed future.
Tools: Declarative selection of the built-in tools installed for an agent.
Turn: Completion handle for an accepted turn.
TurnControl: Cheap cloneable control capability for one accepted turn.
TurnResult: Final result of a completed turn.
UsdAmount: An exact non-negative amount of United States dollars.

Enums§

CostStatus: Availability of the automatic local USD estimate.
Model: Supported models in the GPT-5.6 coding-model family.
NanocodexError: Error returned by the Nanocodex library boundary.
PromptRoute: Outcome of routing live user input into an agent session.
ReasoningMode: Responses reasoning execution mode for the supported GPT-5.6 model family.
ResponseErrorKind: Stable classification for one failed Responses operation.
ServiceTier: OpenAI service tiers supported by Nanocodex.
Thinking: Requested model reasoning effort.

Traits§

Tool: A caller-defined model-visible tool.

Type Aliases§

Result: Result type returned by the owned agent lifecycle.

Attribute Macros§

toolNon-target_family=wasm: Defines a typed JSON function tool from an async Rust function.