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

# Turnos dinâmicos do Agent SDK

> Troque o modelo, as instruções, a amostragem ou as ferramentas de um agente entre turnos sem recriá-lo.

Passe uma função em vez de um valor fixo quando um turno posterior do modelo deve depender do contexto do aplicativo ou de resultados anteriores. O runtime a chama antes de cada requisição ao modelo com o número do turno, o índice da etapa, as mensagens e o contexto. O Rust não tem callbacks por turno; ele [define o modelo por execução](#set-the-model-per-run-in-rust).

## Altere as configurações a cada turno

```typescript TypeScript theme={null}
type ResearchContext = {
  fast: boolean;
};

const agent = createAgent<string, string, ResearchContext>({
  id: "research-agent",
  model: ({ context }) =>
    context?.fast ? "openai/gpt-6-astra" : "openai/gpt-6-astra-pro",
  instructions: ({ numberOfTurns }) =>
    `Research turn ${numberOfTurns}. Cite the evidence you use.`,
});
```

```python Python theme={null}
agent = create_agent({
    "id": "research-agent",
    "model": lambda turn: "openai/gpt-6-astra" if (turn["context"] or {}).get("fast") else "openai/gpt-6-astra-pro",
    "instructions": lambda turn: f"Research turn {turn['number_of_turns']}. Cite the evidence you use.",
})
```

```go Go theme={null}
agent := phaseoagent.CreateAgent(phaseoagent.AgentDefinition{
  ID:    "support-agent",
  Model: "openai/gpt-6-astra",
  DynamicModel: func(turn phaseoagent.TurnContext) string {
    if turn.StepIndex >= 3 {
      return "openai/gpt-6-astra-pro"
    }
    return "openai/gpt-6-astra"
  },
  DynamicInstructions: func(turn phaseoagent.TurnContext) string {
    return fmt.Sprintf("Resolve the request. Current context: %v", turn.Context)
  },
})
```

```csharp C# theme={null}
var agent = AgentSdk.CreateAgent(new AgentDefinition
{
    Id = "support-agent",
    Model = "openai/gpt-6-astra",
    DynamicModel = turn => turn.StepIndex >= 3 ? "openai/gpt-6-astra-pro" : "openai/gpt-6-astra",
    DynamicInstructions = turn => $"Resolve the request. Current context: {turn.Context}",
});
```

```php PHP theme={null}
$agent = AgentSdk::createAgent(new AgentDefinition(
    id: "support-agent",
    model: fn (array $turn) => $turn["step_index"] >= 3
        ? "openai/gpt-6-astra-pro"
        : "openai/gpt-6-astra",
    instructions: fn (array $turn) => "Resolve the request. Current context: " . json_encode($turn["context"]),
));
```

```ruby Ruby theme={null}
agent = PhaseoAgentSdk.create_agent(
  id: "support-agent",
  model: ->(turn) {
    turn[:step_index] >= 3 ? "openai/gpt-6-astra-pro" : "openai/gpt-6-astra"
  },
  instructions: ->(turn) {
    "Resolve the request. Current context: #{turn[:context].inspect}"
  }
)
```

```java Java theme={null}
// Os callbacks são os seis últimos argumentos do construtor de 19 argumentos.
var agent = AgentSdk.createAgent(new AgentSdk.AgentDefinition(
    "support-agent", "openai/gpt-6-astra", null, "Resolve the request.",
    List.of(), 12, null, null, null, null,
    List.of(), null, null,                         // stopWhen, outputSchema, requireApproval
    turn -> turn.stepIndex() >= 3 ? "openai/gpt-6-astra-pro" : "openai/gpt-6-astra", // dynamicModel
    turn -> "Resolve the request. Current context: " + turn.context(),         // dynamicInstructions
    null, null, null,                              // temperature, maxOutputTokens, topP
    null                                           // dynamicTools
));
```

### O que você pode alterar por turno

| Configuração | TypeScript | Python | Go | C# | PHP | Ruby | Java |
| - | - | - | - | - | - | - | - |
| Modelo | `model` | `model` | `DynamicModel` | `DynamicModel` | `model` | `model:` | `dynamicModel` |
| Instruções | `instructions` | `instructions` | `DynamicInstructions` | `DynamicInstructions` | `instructions` | `instructions:` | `dynamicInstructions` |
| Temperatura | `temperature` | `temperature` | `Temperature` (`*float64`) | `Temperature` (`double?`) | `temperature` | `temperature:` | `temperature` (`Double`) |
| Top-p | `topP` | `top_p` | `TopP` (`*float64`) | `TopP` (`double?`) | `topP` | `top_p:` | `topP` (`Double`) |
| Máximo de tokens de saída | `maxOutputTokens` | `max_output_tokens` | `MaxOutputTokens` (`*int`) | `MaxOutputTokens` (`int?`) | `maxOutputTokens` | `max_output_tokens:` | `maxOutputTokens` (`Integer`) |
| Ferramentas oferecidas | `activeTools` (IDs de ferramenta) | Não por turno; use `next_turn_params` | `DynamicTools` (`[]Tool`) | `DynamicTools` (`IReadOnlyList<Tool>`) | `dynamicTools` | `dynamic_tools:` | `dynamicTools` (`List<Tool>`) |
| Lista de modelos | `models` | Não | Não | Não | Não | Não | Não |

TypeScript, Python, PHP e Ruby aceitam uma função no lugar do campo fixo. Go, C# e Java usam campos de callback separados, ao lado dos campos fixos `Model` e `Instructions`. No TypeScript, as ferramentas deixadas de fora de `activeTools` continuam chamáveis, então as chamadas anteriores ainda são resolvidas.

O argumento do turno tem os mesmos quatro valores em todas as linguagens:

| Linguagem | Argumento do turno |
| - | - |
| TypeScript | Objeto com `numberOfTurns`, `stepIndex`, `messages`, `context` |
| Python | Dict com `number_of_turns`, `step_index`, `messages`, `context` |
| Go, C# | `TurnContext` com `NumberOfTurns`, `StepIndex`, `Messages`, `Context` |
| PHP | Array com `number_of_turns`, `step_index`, `messages`, `context` |
| Ruby | Hash com `:number_of_turns`, `:step_index`, `:messages`, `:context` |
| Java | `TurnContext` com `numberOfTurns()`, `stepIndex()`, `messages()`, `context()` |

No Python, um `model` ou `preset` passado a `run()` substitui o modelo da definição em todos os turnos.

## Atualize o contexto do aplicativo a partir de uma ferramenta

Uma ferramenta pode substituir o contexto do aplicativo que os turnos seguintes leem: `context.setContext()` no TypeScript, `runtime.set_context()` no Python e os equivalentes em [Ferramentas](https://phaseo.app/docs/pt-BR/v1/sdk-reference/agent/tools.md#report-progress-and-update-context). Mantenha o contexto pequeno e serializável quando você salva execuções e as continua depois.

```typescript theme={null}
const chooseMode = defineTool({
  id: "choose-mode",
  async execute(input: { fast: boolean }, context) {
    context.setContext({ fast: input.fast });
    return { selected: input.fast ? "fast" : "thorough" };
  },
});
```

## Substitua só o próximo turno

Defina parâmetros do próximo turno em uma ferramenta para alterar a requisição que vem logo depois dela, sem mudar a definição do agente. Eles têm prioridade sobre as funções por turno naquele turno.

```typescript TypeScript theme={null}
const broadenSearch = defineTool({
  id: "broaden-search",
  nextTurnParams: {
    model: "openai/gpt-6-astra-pro",
    maxOutputTokens: 2_000,
  },
  async execute() {
    return { broadened: true };
  },
});
```

```python Python theme={null}
broaden_search = define_tool(AgentTool(
    id="broaden-search",
    next_turn_params={"model": "openai/gpt-6-astra-pro", "max_output_tokens": 2_000},
    execute=lambda tool_input, runtime: {"broadened": True},
))
```

```go Go theme={null}
inspect := phaseoagent.Tool{
  ID:       "inspect_repository",
  Execute:  inspectRepository,
  NextTurn: &phaseoagent.NextTurnParams{Model: "openai/gpt-6-astra-pro"},
}
```

```csharp C# theme={null}
var inspect = new Tool("inspect_repository", InspectRepository)
{
    NextTurnParams = new NextTurnParams(Model: "openai/gpt-6-astra-pro"),
};
```

```php PHP theme={null}
$inspect = new Tool(
    id: "inspect_repository",
    execute: fn (array $input, $runtime) => inspectRepository($input),
    nextTurnParams: ["model" => "openai/gpt-6-astra-pro"],
);
```

```ruby Ruby theme={null}
inspect_repo = PhaseoAgentSdk::Tool.new(
  id: "inspect_repository",
  execute: ->(input, runtime) { inspect_repository(input) },
  next_turn_params: { model: "openai/gpt-6-astra-pro" }
)
```

```java Java theme={null}
// Passe como o último argumento do construtor da ferramenta.
new AgentSdk.NextTurnParams("openai/gpt-6-astra-pro", null, null, null, null, null)
```

Os parâmetros do próximo turno aceitam o modelo, as instruções, a temperatura, o top-p, o máximo de tokens de saída e as ferramentas, com os nomes na convenção de cada linguagem. No Python, eles são a única forma de alterar a lista de ferramentas entre turnos.

Se a ferramenta aguarda aprovação, as substituições dela são salvas com a execução pausada e aplicadas ao turno depois que você continua:

| Linguagem | Salvo em |
| - | - |
| TypeScript | Aplicado quando a chamada aprovada roda na continuação |
| Python | `run.next_turn_params` |
| Go | `Run.NextTurn` |
| C# | `Run.NextTurn` |
| PHP | `$result->run->nextTurnParams` |
| Ruby | `result.run.next_turn_params` |
| Java | `run().nextTurn()` |

Use funções por turno para regras que você quer recalcular a cada turno, e parâmetros do próximo turno para uma passagem pontual vinda de uma ferramenta específica.

## Defina o modelo por execução no Rust

O `phaseo-agent` 0.2 do Rust não tem callbacks por turno, atualizações de contexto a partir de ferramentas nem parâmetros do próximo turno. Defina o modelo, o limite de etapas e o contexto do aplicativo por execução com `RunOptions`:

```rust theme={null}
let mut options = RunOptions::new("Explain when to use routing presets.");
options.model = Some("openai/gpt-6-astra-pro".to_string());
options.max_steps = Some(4);
options.context = serde_json::json!({ "workspace": "docs" });

let result = agent.run(&mut client, options)?;
```


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