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

# Desenvolva com o Rust Agent SDK

> Crie um agente síncrono em Rust que chama uma ferramenta local pela Phaseo Gateway.

Use este guia para criar um agente pequeno que utiliza ferramentas e inspecionar sua execução concluída.

## Defina uma ferramenta

```rust theme={null}
use phaseo_agent::{define_tool, Tool};
use serde_json::json;

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
        }))
    },
));
```

O closure é executado localmente. Seu `RuntimeContext` inclui o ID da execução, o ID do agente, o índice da etapa, o contexto do aplicativo e a chamada de ferramenta original.

## Crie o agente

```rust theme={null}
use phaseo_agent::{create_agent, AgentDefinition};

let agent = create_agent(
    AgentDefinition::new("docs-agent", "openai/gpt-6-astra")
        .instructions("Use lookup_docs when it helps. Finish with a concise answer.")
        .max_steps(6)
        .tool(lookup),
);
```

## Execute pela Phaseo Gateway

```rust theme={null}
use phaseo_agent::{create_gateway_agent_client, RunOptions};

let mut client = create_gateway_agent_client("openai/gpt-6-astra")?;
let mut options = RunOptions::new("Explain when to use routing presets.");
options.context = serde_json::json!({
    "workspace": "docs"
});

let result = agent.run(&mut client, options)?;
println!("{}", result.output);
```

## Exemplo completo

```rust theme={null}
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(())
}
```

## Estado da execução

`RunResult` contém:

* `run`: status, IDs, modelo efetivo, limite de etapas, contexto e estado da pausa
* `steps`: cada turno do modelo, ID da requisição, provedor, modelo, motivo de encerramento, chamadas de ferramenta e uso
* `messages`: o histórico completo de mensagens do modelo e das ferramentas
* `output`: o valor final de saída
* `usage`: valores agregados de tokens e qualquer custo fornecido pelo cliente do modelo

## Modelo de execução atual

As execuções do Rust Agent SDK são síncronas. As ferramentas locais são executadas uma por vez. Use uma thread de trabalho do aplicativo ou um limite de tarefa quando uma execução não deve bloquear um handler de requisição.

## Próximos passos

* [Ferramentas e aprovações](./agent-sdk-tools.mdx)
* [Salvar e retomar execuções](./agent-sdk-state-and-approval.mdx)
* [Eventos, novas tentativas e erros](./agent-sdk-events-and-errors.mdx)


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