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

# Herramientas

> Define herramientas locales validadas, herramientas manuales y herramientas que notifican su progreso.

Usa herramientas cuando un agente necesite leer datos de la aplicación, llamar a un servicio interno o realizar una acción. Agent SDK valida los límites de cada herramienta y ejecuta su código dentro de tu aplicación.

## Define una herramienta local

`defineTool()` acepta una descripción, parámetros JSON opcionales, validadores de ejecución, un tiempo de espera y una función `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();
  },
});
```

Si se agota el tiempo de espera, el entorno de ejecución aborta `context.signal`, marca la ejecución como fallida y vuelve a lanzar el error de tiempo de espera.

Los esquemas pueden ser funciones u objetos que expongan `parse()` o `safeParse()`. Los argumentos no válidos del modelo y los resultados no válidos de las herramientas generan un error antes de cruzar el límite de la herramienta.

## Ejecuta el trabajo en tu aplicación

Establece `execute: false` cuando el trabajo lo realice tu aplicación en lugar del proceso del SDK. Reanuda la ejecución en pausa con el resultado en `toolOutputs`.

Para una herramienta interactiva, devuelve `null` desde `onToolCalled`. Después de continuar, `onResponseReceived` puede validar o transformar la respuesta proporcionada.

## Publica el progreso

Un generador asíncrono puede devolver resultados preliminares antes de devolver el 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 };
  },
});
```

El progreso está disponible mediante los eventos `tool.preliminary_result` y `preliminaryResults` del paso.

## Ejecuta herramientas independientes en paralelo

Si un turno del modelo puede llamar de forma segura a varias herramientas independientes, configura un límite de concurrencia:

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

El entorno de ejecución conserva el orden de los mensajes de resultados de herramientas aunque las ejecuciones locales se solapen.

## Guías relacionadas

* [Pausar, aprobar y reanudar ejecuciones](./agent-sdk-state-and-approval.mdx)
* [Transmitir resultados del agente](./agent-sdk-streaming.mdx)
* [Ejecutar herramientas locales en paralelo](../../cookbook/agent-sdk-parallel-tools.mdx)


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