Uso do Agent SDK

Defina uma ferramenta, crie um agente e execute-o com um cliente de gateway. O modelo chama sua ferramenta, o SDK a executa e envia o resultado de volta, e a execução retorna quando o modelo responde sem chamar uma ferramenta, pausa para uma pessoa ou atende a uma condição de parada. Se a execução atingir antes o limite de etapas, o SDK lança um erro; só o Rust retorna a execução com o status stopped. A Phaseo não hospeda o agente nem armazena suas execuções; seu aplicativo faz isso.

Crie um primeiro agente

import {
  createAgent,
  createGatewayAgentClient,
  defineTool,
} from "@phaseo/agent-sdk";

const lookupDocs = defineTool({
  id: "lookup-docs",
  description: "Look up an internal docs page by slug.",
  parameters: {
    type: "object",
    properties: {
      slug: { type: "string" },
    },
    required: ["slug"],
    additionalProperties: false,
  },
  async execute(input: { slug: string }) {
    return {
      slug: input.slug,
      url: `https://phaseo.app/docs/v1/${input.slug}`,
    };
  },
});

const agent = createAgent({
  id: "support-docs-agent",
  model: "openai/gpt-6-astra",
  instructions: "Use tools when helpful and finish with a concise answer.",
  tools: [lookupDocs],
});

const result = await agent.run({
  input: "Find the docs page for presets and explain when to use them.",
  client: createGatewayAgentClient({
    clientOptions: {
      apiKey: process.env.PHASEO_API_KEY!,
    },
  }),
});

console.log(result.output);

import os
from phaseo_agent import AgentTool, create_agent, create_gateway_agent_client, define_tool

lookup_docs = define_tool(AgentTool(
    id="lookup-docs",
    description="Look up an internal docs page by slug.",
    parameters={
        "type": "object",
        "properties": {"slug": {"type": "string"}},
        "required": ["slug"],
        "additionalProperties": False,
    },
    execute=lambda tool_input, runtime: {
        "slug": tool_input["slug"],
        "url": f"https://phaseo.app/docs/v1/{tool_input['slug']}",
    },
))

agent = create_agent({
    "id": "support-docs-agent",
    "model": "openai/gpt-6-astra",
    "instructions": "Use tools when helpful and finish with a concise answer.",
    "tools": [lookup_docs],
})

result = agent.run(
    input="Find the docs page for presets and explain when to use them.",
    client=create_gateway_agent_client(client_options={"api_key": os.environ["PHASEO_API_KEY"]}),
)

print(result.output)

package main

import (
  "context"
  "fmt"

  phaseoagent "github.com/phaseoteam/Phaseo/packages/sdk/agent-sdk-go"
)

func main() {
  client, err := phaseoagent.CreateGatewayAgentClient(phaseoagent.GatewayAgentClientOptions{})
  if err != nil {
    panic(err) // PHASEO_API_KEY é obrigatória
  }

  lookup := phaseoagent.DefineTool(phaseoagent.Tool{
    ID:          "lookup_docs",
    Description: "Look up a Phaseo documentation topic",
    Parameters: map[string]any{
      "type":       "object",
      "properties": map[string]any{"topic": map[string]any{"type": "string"}},
      "required":   []string{"topic"},
    },
    Execute: func(input any, runtime phaseoagent.RuntimeContext) (any, error) {
      args, _ := input.(map[string]any)
      return map[string]any{"topic": args["topic"], "found": true}, nil
    },
  })

  agent := phaseoagent.CreateAgent(phaseoagent.AgentDefinition{
    ID:           "docs-agent",
    Model:        "openai/gpt-6-astra",
    Instructions: "Use tools when helpful and finish with a concise answer.",
    Tools:        []phaseoagent.Tool{lookup},
    MaxSteps:     6,
  })

  result, err := agent.Run(context.Background(), phaseoagent.RunOptions{
    Input:  "Explain when to use routing presets.",
    Client: client,
  })
  if err != nil {
    panic(err)
  }

  fmt.Println(result.Output)
  fmt.Println(result.Run.Status, result.Usage.TotalTokens)
}

using System.Text.Json;
using PhaseoAgentSdk;

var lookup = AgentSdk.DefineTool(new Tool(
    "lookup_docs",
    async (input, runtime) =>
    {
        var topic = ((JsonElement)input!).GetProperty("topic").GetString();
        return new { topic, found = true };
    },
    "Look up a Phaseo documentation topic",
    new Dictionary<string, object?>
    {
        ["type"] = "object",
        ["properties"] = new Dictionary<string, object?> { ["topic"] = new { type = "string" } },
        ["required"] = new[] { "topic" },
    }));

var agent = AgentSdk.CreateAgent(new AgentDefinition
{
    Id = "docs-agent",
    Model = "openai/gpt-6-astra",
    Instructions = "Use tools when helpful and finish with a concise answer.",
    Tools = new[] { lookup },
    MaxSteps = 6,
});

var result = await agent.Run(new RunOptions
{
    Input = "Explain when to use routing presets.",
    Client = AgentSdk.CreateGatewayAgentClient(), // lança exceção se PHASEO_API_KEY estiver ausente
});

Console.WriteLine(result.Output);
Console.WriteLine($"{result.Run.Status} {result.Usage.TotalTokens}");

<?php
require "vendor/autoload.php";

use Phaseo\AgentSdk\AgentDefinition;
use Phaseo\AgentSdk\AgentSdk;
use Phaseo\AgentSdk\Tool;

$lookup = AgentSdk::defineTool(new Tool(
    id: "lookup_docs",
    execute: fn (array $input, $runtime) => ["topic" => $input["topic"], "found" => true],
    description: "Look up a Phaseo documentation topic",
    parameters: [
        "type" => "object",
        "properties" => ["topic" => ["type" => "string"]],
        "required" => ["topic"],
    ],
));

$agent = AgentSdk::createAgent(new AgentDefinition(
    id: "docs-agent",
    model: "openai/gpt-6-astra",
    instructions: "Use tools when helpful and finish with a concise answer.",
    tools: [$lookup],
    maxSteps: 6,
));

$result = $agent->run(
    input: "Explain when to use routing presets.",
    client: AgentSdk::createGatewayAgentClient() // lança exceção se PHASEO_API_KEY estiver ausente
);

echo $result->output . PHP_EOL;
echo $result->run->status . " " . $result->usage["total_tokens"] . PHP_EOL;

require "phaseo_agent_sdk"

lookup = PhaseoAgentSdk.define_tool(
  PhaseoAgentSdk::Tool.new(
    id: "lookup_docs",
    description: "Look up a Phaseo documentation topic",
    parameters: {
      type: "object",
      properties: { topic: { type: "string" } },
      required: ["topic"]
    },
    execute: ->(input, runtime) { { topic: input["topic"], found: true } }
  )
)

agent = PhaseoAgentSdk.create_agent(
  id: "docs-agent",
  model: "openai/gpt-6-astra",
  instructions: "Use tools when helpful and finish with a concise answer.",
  tools: [lookup],
  max_steps: 6
)

result = agent.run(
  input: "Explain when to use routing presets.",
  client: PhaseoAgentSdk.create_gateway_agent_client # lança exceção se PHASEO_API_KEY estiver ausente
)

puts result.output
puts "#{result.run.status} #{result.usage[:total_tokens]}"

import app.phaseo.agent.AgentSdk;
import java.time.Duration;
import java.util.List;
import java.util.Map;

var lookup = AgentSdk.defineTool(new AgentSdk.Tool(
    "lookup_docs",
    (input, context) -> Map.of("topic", ((Map<?, ?>) input).get("topic"), "found", true),
    "Look up a Phaseo documentation topic",
    Map.of(
        "type", "object",
        "properties", Map.of("topic", Map.of("type", "string")),
        "required", List.of("topic")),
    Duration.ofSeconds(10)
));

var agent = AgentSdk.createAgent(new AgentSdk.AgentDefinition(
    "docs-agent",                       // id
    "openai/gpt-6-astra",               // model
    null,                               // preset
    "Use tools when helpful and finish with a concise answer.", // instructions
    List.of(lookup),                    // tools
    6,                                  // maxSteps
    null, null, null, null              // parseOutput, humanReview, modelRetry, toolExecution
));

var result = agent.run(new AgentSdk.RunOptions(
    "Explain when to use routing presets.",  // input
    AgentSdk.createGatewayAgentClient(),     // lança exceção se PHASEO_API_KEY estiver ausente
    null, null, null, null, null, null, null, null
));

System.out.println(result.output());
System.out.println(result.run().status() + " " + result.usage().totalTokens());

use phaseo_agent::{
    create_agent, create_gateway_agent_client, define_tool, AgentDefinition,
    RunOptions, Tool,
};
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let lookup = define_tool(Tool::new(
        "lookup_docs",
        "Look up a Phaseo documentation topic",
        json!({
            "type": "object",
            "properties": {
                "topic": { "type": "string" }
            },
            "required": ["topic"]
        }),
        |input, context| {
            Ok(json!({
                "topic": input["topic"],
                "run_id": context.run_id,
                "found": true
            }))
        },
    ));

    let agent = create_agent(
        AgentDefinition::new("docs-agent", "openai/gpt-6-astra")
            .instructions("Use lookup_docs when helpful. Answer concisely.")
            .max_steps(6)
            .tool(lookup),
    );

    let mut client = create_gateway_agent_client("openai/gpt-6-astra")?;
    let result = agent.run(
        &mut client,
        RunOptions::new("Explain when to use routing presets."),
    )?;

    println!("{}", result.output);
    println!("steps: {}", result.run.step_count);
    println!("tokens: {}", result.usage.total_tokens);
    Ok(())
}

O ID da ferramenta é o nome de função que o modelo vê, e os parâmetros dela são o JSON Schema que o modelo preenche. Os argumentos chegam ao seu código no formato nativo de cada linguagem:

Linguagem	A ferramenta recebe	Observações
TypeScript	Objeto tipado	`execute(input, context)`
Python	`dict`	`execute(tool_input, runtime)`
Go	`any` (JSON decodificado, normalmente `map[string]any`)	`Execute(input, runtime) (any, error)`
C#	`JsonElement`	`Execute(input, runtime)`, aguardado com await
PHP	Array associativo	`execute(array $input, $runtime)`
Ruby	Hash com chaves string	Crie ferramentas com `PhaseoAgentSdk::Tool.new`; `define_tool` retorna o que você passa, então um Hash simples não funciona
Java	`Map`	Records são posicionais; passe `null` para tudo o que você não definir
Rust	`serde_json::Value`	A closure roda localmente; `RuntimeContext` tem o ID da execução, o ID do agente, o índice da etapa, o contexto do aplicativo e a chamada de ferramenta

Se o agente, a execução e o cliente não definirem modelo nem predefinição, o cliente de gateway envia phaseo/free. O create_gateway_agent_client do Rust recebe o modelo como argumento.

Como uma execução funciona

Cada etapa recebe um checkpoint no resultado da execução retornado. Para retomar entre requisições ou reinicializações, salve esse resultado no seu próprio armazenamento e passe-o ao método de continuação, ou dê ao agente um acessor de estado; veja Estado e aprovação. O limite de etapas e o que acontece quando ele se esgota variam por linguagem:

Cada chamada a run() ou continueRun() usa até 12 etapas, a menos que você defina maxSteps; além disso, ela lança Max steps exceeded. Use condições de parada para encerrar uma execução de forma limpa.

Uma execução usa até 12 etapas, a menos que você defina max_steps; além disso, ela lança RuntimeError. As condições de parada só são verificadas em uma etapa em que o modelo não faz chamadas de ferramenta, então a ordem difere do diagrama: um loop de ferramentas roda até pausar, responder ou esgotar max_steps.

Uma execução que precisa de mais de MaxSteps turnos do modelo (padrão 8) falha com Max steps exceeded (N).

Uma execução que precisa de mais de MaxSteps turnos do modelo (padrão 12) lança InvalidOperationException("Max steps exceeded (N)").

Uma execução que precisa de mais de maxSteps turnos do modelo (padrão 12) lança Max steps exceeded (N).

Uma execução que precisa de mais de max_steps turnos do modelo (padrão 12) lança Max steps exceeded (N).

Uma execução que precisa de mais de maxSteps turnos do modelo (padrão 12) lança Max steps exceeded (N).

Uma execução usa até 8 turnos do modelo, a menos que você chame .max_steps(n) ou defina RunOptions.max_steps. Atingir o limite não causa falha: a execução retorna com run.status stopped e run.stop_reason max_steps:<limit>. As execuções são síncronas e as ferramentas locais rodam uma de cada vez, então use uma thread de trabalho ou um limite de tarefa quando uma execução não deve bloquear um handler de requisição.

Leia o resultado da execução

Toda execução retorna as mesmas partes. Os nomes dos campos seguem a convenção de maiúsculas e minúsculas de cada linguagem (output, Output, output()):

Parte	Conteúdo
`run`	Status, IDs, modelo efetivo, limite de etapas, contexto, estado de pausa e motivo da parada
`steps`	Um registro por turno do modelo: ID da requisição, provedor, modelo, motivo de término, avisos, chamadas de ferramenta e uso
`messages`	A conversa inteira, incluindo os resultados das ferramentas
`output`	A saída final
`usage`	Tokens de entrada, de saída, em cache e totais, e o custo

O usage.cost do Rust vem só de um meta.cost ou cost numérico na resposta; ele não mapeia cost_nanos nem cost_cents. Use a resposta do Gateway ou o registro de geração para relatar gastos no Rust.

Encontre o recurso certo

Para…	Página
Dar ao modelo ferramentas locais, manuais ou que relatam progresso	Ferramentas
Pausar para aprovação ou para uma pessoa e depois retomar	Estado e aprovação
Mostrar texto e atividade de ferramentas enquanto acontecem	Streaming
Renderizar uma linha do tempo de mensagens, raciocínio e chamadas de ferramenta	Itens
Limitar etapas, tokens, custo ou tempo	Condições de parada
Trocar o modelo ou as ferramentas entre turnos	Turnos dinâmicos
Obter saída tipada, repetir chamadas ao modelo, usar uma predefinição	Saídas e novas tentativas
Registrar ou auditar cada etapa	Hooks do ciclo de vida
Registrar uso, custo e IDs de requisição de uma execução	Observabilidade
Tratar erros de gateway, de schema e de limite de etapas	Eventos e erros
Inspecionar execuções localmente	DevTools

Todas as exportações estão listadas na referência da API, e agentes completos estão em Exemplos.

Comece aqui

Criar

Observabilidade

Referência

Crie um primeiro agente

Como uma execução funciona

Leia o resultado da execução

Encontre o recurso certo

​Crie um primeiro agente

​Como uma execução funciona

​Leia o resultado da execução

​Encontre o recurso certo

Crie um primeiro agente

Como uma execução funciona

Leia o resultado da execução

Encontre o recurso certo