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

# API reference

> Reference the TypeScript Agent SDK entry points, methods, options, and result types.

Use this page when you already understand the Agent SDK workflow and need the exact public entry point or option to reach for.

## Entry points

| Export                              | Purpose                                                                      |
| ----------------------------------- | ---------------------------------------------------------------------------- |
| `createAgent(definition)`           | Define an agent and its default runtime behaviour                            |
| `defineTool(definition)`            | Define a validated local, manual, approval-gated, or progress-producing tool |
| `tool(definition)`                  | Concise alias for `defineTool()`                                             |
| `createGatewayAgentClient(options)` | Run model turns through Phaseo Gateway                                       |
| `createAgentDevtools(options)`      | Enable local run capture                                                     |

## Agent methods

| Method                       | Returns                   | Purpose                                                      |
| ---------------------------- | ------------------------- | ------------------------------------------------------------ |
| `agent.run(options)`         | `Promise<AgentRunResult>` | Run until completion, pause, stop, cancellation, or failure  |
| `agent.stream(options)`      | `AgentStreamResult`       | Start the same loop with replayable stream consumers         |
| `agent.continueRun(options)` | `Promise<AgentRunResult>` | Continue saved or paused state with decisions or human input |

## Stream consumers

| Method                 | Value                                       |
| ---------------------- | ------------------------------------------- |
| `getResult()`          | Completed `AgentRunResult`                  |
| `getText()`            | Complete final text                         |
| `getTextStream()`      | Text deltas                                 |
| `getReasoningStream()` | Reasoning deltas when supplied by the model |
| `getItemsStream()`     | Typed `AgentItem<TOutput>` values           |
| `getToolStream()`      | Tool lifecycle events                       |
| `getFullStream()`      | Complete Agent SDK event stream             |
| `cancel(reason?)`      | Cancels the active run                      |

## Definition options

`AgentDefinition` includes:

* `id`
* `model` or `models`
* `preset`
* `instructions`
* `tools`
* `maxSteps` and `stopWhen`
* `modelRetry` and `toolExecution`
* `temperature`, `maxOutputTokens`, and `topP`
* `parseOutput` and `outputSchema`
* `requireApproval` and `humanReview`

Model, instruction, and sampling fields can use fixed or dynamic values.

## Run and continuation options

`AgentRunOptions` supplies input, the model client, application context, optional overrides, cancellation, lifecycle hooks, DevTools, and an application-owned state accessor.

`AgentContinueOptions` additionally accepts:

* a prior `run` or `runId`
* `humanInput`
* approvals and rejections by exact tool-call ID
* externally produced `toolOutputs`

## Result records

`AgentRunResult` contains:

* `run`: durable run status, context, pause details, and stop reason
* `steps`: persisted model/tool step records
* `stepResults`: normalized step results when available
* `usage`: cumulative tokens and reported cost
* `output`: parsed final output
* `messages`: the complete conversation used by the loop
* `items`: ordered typed messages, reasoning, tool activity, errors, and final output

## Error types

* `AgentGatewayError` describes gateway or upstream request failures.
* `AgentSchemaValidationError` describes invalid tool, progress, or final-output data.

## Related guides

* [Build your first agent](./agent-sdk)
* [Streaming](./agent-sdk-streaming)
* [Working with items](./agent-sdk-items)
* [Errors and troubleshooting](./agent-sdk-events-and-errors)