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

# 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](https://phaseo.app/docs/v1/sdk-reference/typescript/agent-sdk.md)
* [Streaming](https://phaseo.app/docs/v1/sdk-reference/typescript/agent-sdk-streaming.md)
* [Working with items](https://phaseo.app/docs/v1/sdk-reference/typescript/agent-sdk-items.md)
* [Errors and troubleshooting](https://phaseo.app/docs/v1/sdk-reference/typescript/agent-sdk-events-and-errors.md)


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