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

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.