Rust Agent SDK API Reference

This page describes the public API in phaseo-agent 0.1.

Agent definition

API	Purpose
`AgentDefinition::new(id, model)`	Create an agent definition with an eight-step default limit.
`.instructions(text)`	Set the model instructions.
`.tool(tool)`	Add one tool.
`.max_steps(limit)`	Set the model-turn limit. Values are clamped to at least one.
`.model_retries(count, backoff)`	Retry failed model requests with a fixed `Duration`.
`.human_review(callback)`	Pause after a model response when the callback returns `Some(HumanReviewRequest)`.
`create_agent(definition)`	Create an `Agent`.

Running and continuing

Method	Purpose
`Agent::run(client, options)`	Run synchronously without an event callback.
`Agent::run_with_events(client, options, callback)`	Run synchronously and emit `AgentEvent` values.
`Agent::continue_run(client, options)`	Continue a paused run.
`Agent::continue_with_events(client, options, callback)`	Continue and emit events.

RunOptions fields:

input: Value
context: Value
model: Option<String>
max_steps: Option<usize>

Create defaults with RunOptions::new(input). ContinueOptions fields:

result: RunResult
human_input: Option<String>
approvals: Vec<ToolDecision>
tool_outputs: Vec<ToolOutput>

Create defaults with ContinueOptions::new(result).

Tools

API	Purpose
`Tool::new(id, description, parameters, executor)`	Define a local synchronous tool.
`Tool::external(id, description, parameters)`	Define a tool fulfilled by the application after a pause.
`Tool::require_approval()`	Require an exact-ID approval before local execution.
`define_tool(tool)`	Return the supplied `Tool` for a consistent definition style.

The executor signature is:

Fn(
    serde_json::Value,
    &RuntimeContext,
) -> Result<serde_json::Value, AgentError>
    + Send
    + Sync
    + 'static

Tool exposes id, description, parameters, execute, and require_approval. Prefer its constructors and builder method so executor types and defaults remain consistent. RuntimeContext passed to an executor contains:

run_id
agent_id
step_index
context
tool_call

Messages and tool calls

Message contains role, content, tool_calls, optional tool_call_id, optional name, and is_error. Create ordinary messages with:

Message::user(content)
Message::assistant(content)

ToolCall contains the call id, tool name, and JSON input. ToolSpec contains the tool id, description, and JSON Schema parameters sent to a model client.

Model clients

Implement ModelClient to use another model transport:

pub trait ModelClient {
    fn generate(
        &mut self,
        request: &ModelRequest,
    ) -> Result<ModelResponse, AgentError>;
}

The built-in Gateway adapter is available through:

GatewayAgentClient::new(phaseo_client, model)
GatewayAgentClient::from_env(model)
create_gateway_agent_client(model)

It sends ModelRequest values to POST /responses and normalizes output text, function calls, request metadata, and usage. ModelRequest contains the agent ID, effective model, instructions, current messages, tool specifications, and application context. ModelResponse contains:

message: Message
usage: UsageSummary
request_id: Option<String>
provider: Option<String>
model: Option<String>
finish_reason: Option<String>

Review and pause types

HumanReviewContext contains the run and agent IDs, step index, current messages, normalized model response, and application context. Return HumanReviewRequest { reason, payload } from the review callback to pause a run. HumanPause contains:

reason
JSON payload
kind
pending_tool_calls

Each PendingToolCall contains the original ToolCall, its required input kind, and a human-readable reason. ToolDecision supplies an approved tool_call_id and optional reason. ToolOutput supplies a tool_call_id and JSON output.

Run records

RunResult contains:

run: RunRecord
steps: Vec<RunStep>
output: Value
messages: Vec<Message>
usage: UsageSummary

RunRecord contains the run and agent IDs, effective model and step limit, status, original input, application context, step count, optional pause, optional stop reason, and timestamps. RunStep contains its index, status, model-attempt count, tool calls, request ID, provider, model, finish reason, optional error, and usage. UsageSummary contains input_tokens, output_tokens, cached_tokens, total_tokens, and cost. cost is model-client supplied. The built-in 0.1 Gateway adapter does not currently map Gateway cost_nanos or cost_cents into this field. RunResult, RunRecord, RunStep, Message, ToolCall, HumanPause, PendingToolCall, ToolDecision, ToolOutput, and UsageSummary support Serde serialization where their definitions derive Serialize and Deserialize.

Events and errors

AgentEvent fields:

event_type
run_id
agent_id
timestamp_ms
details

AgentError implements std::error::Error and Display. Use AgentError::new(...) to create one and message() to read its message.

Start Here

Build

Observe

Reference

Rust Agent SDK API Reference

Agent definition

Running and continuing

Tools

Messages and tool calls

Model clients

Review and pause types

Run records

Events and errors

External reference

​Agent definition

​Running and continuing

​Tools

​Messages and tool calls

​Model clients

​Review and pause types

​Run records

​Events and errors

​External reference

Agent definition

Running and continuing

Tools

Messages and tool calls

Model clients

Review and pause types

Run records

Events and errors

External reference