> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust Agent SDK API Reference

> Public structs, traits, and methods in phaseo-agent 0.1.

This page describes the public API in [`phaseo-agent 0.1`](https://docs.rs/phaseo-agent/0.1.0/phaseo_agent/).

## 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:

```rust theme={null}
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:

```rust theme={null}
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.

## External reference

* [`phaseo-agent` on crates.io](https://crates.io/crates/phaseo-agent)
* [`phaseo-agent` on docs.rs](https://docs.rs/phaseo-agent)