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

# Ferramentas

> Defina ferramentas locais validadas, ferramentas manuais e ferramentas que informam o progresso.

Use ferramentas quando um agente precisar ler dados da aplicação, chamar um serviço interno ou executar uma ação. O Agent SDK valida os limites das ferramentas e executa o código delas dentro da sua aplicação.

## Defina uma ferramenta local

`defineTool()` aceita uma descrição, parâmetros JSON opcionais, validadores de execução, um tempo limite e uma função `execute()`.

```typescript theme={null}
import { defineTool } from "@phaseo/agent-sdk";

const fetchTicket = defineTool({
  id: "fetch-ticket",
  description: "Load one internal support ticket.",
  parameters: {
    type: "object",
    properties: {
      ticketId: { type: "string" },
    },
    required: ["ticketId"],
    additionalProperties: false,
  },
  timeoutMs: 3_000,
  async execute(input: { ticketId: string }, context) {
    const response = await fetch(
      `https://internal.example/tickets/${input.ticketId}`,
      { signal: context.signal },
    );

    return response.json();
  },
});
```

Se o tempo limite expirar, o runtime cancela `context.signal`, marca a execução como malsucedida e relança o erro de tempo limite.

Os esquemas podem ser funções ou objetos que expõem `parse()` ou `safeParse()`. Argumentos inválidos do modelo e resultados inválidos da ferramenta falham antes de cruzar os limites da ferramenta.

## Execute o trabalho na sua aplicação

Defina `execute: false` quando o trabalho for feito pela sua aplicação, e não pelo processo do SDK. Continue a execução pausada com o resultado em `toolOutputs`.

Para uma ferramenta interativa, retorne `null` em `onToolCalled`. Após a continuação, `onResponseReceived` pode validar ou transformar a resposta fornecida.

## Publique o progresso

Um gerador assíncrono pode fornecer resultados preliminares antes de retornar um resultado final:

```typescript theme={null}
const indexRepository = defineTool({
  id: "index-repository",
  async *execute(input: { path: string }) {
    yield { phase: "scan" };
    yield { phase: "embed" };
    return { indexed: 248 };
  },
});
```

O progresso fica disponível por meio dos eventos `tool.preliminary_result` e de `preliminaryResults` da etapa.

## Execute ferramentas independentes em paralelo

Se um turno do modelo puder chamar várias ferramentas independentes com segurança, configure um limite de concorrência:

```typescript theme={null}
const agent = createAgent({
  id: "research-agent",
  toolExecution: {
    toolConcurrency: 3,
  },
  tools: [fetchDocs, fetchStatus, fetchIncidents],
});
```

O runtime preserva a ordem das mensagens de resultado das ferramentas mesmo quando as execuções locais se sobrepõem.

## Guias relacionados

* [Pause, aprove e retome execuções](./agent-sdk-state-and-approval.mdx)
* [Transmita resultados do agente](./agent-sdk-streaming.mdx)
* [Execute ferramentas locais em paralelo](../../cookbook/agent-sdk-parallel-tools.mdx)


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