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

# Outils

> Définissez des outils locaux validés, des outils manuels et des outils qui indiquent leur progression.

Utilisez des outils lorsqu’un agent doit lire les données de l’application, appeler un service interne ou effectuer une action. L’Agent SDK valide les limites des outils et exécute leur code dans votre application.

## Définir un outil local

`defineTool()` accepte une description, des paramètres JSON facultatifs, des validateurs d’exécution, un délai d’attente et une fonction `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();
  },
});
```

À l’expiration du délai, le runtime annule `context.signal`, marque l’exécution comme échouée et renvoie l’erreur de délai.

Les schémas peuvent être des fonctions ou des objets exposant `parse()` ou `safeParse()`. Les arguments de modèle et les résultats d’outil non valides échouent avant de franchir la limite de l’outil.

## Exécuter le travail dans votre application

Définissez `execute: false` lorsque le travail est réalisé par votre application plutôt que par le processus du SDK. Reprenez l’exécution en pause en fournissant le résultat dans `toolOutputs`.

Pour un outil interactif, renvoyez `null` depuis `onToolCalled`. Après la reprise, `onResponseReceived` peut valider ou transformer la réponse fournie.

## Publier la progression

Un générateur asynchrone peut produire des résultats préliminaires avant de renvoyer un résultat final :

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

La progression est accessible via les événements `tool.preliminary_result` et le champ `preliminaryResults` de l’étape.

## Exécuter des outils indépendants en parallèle

Si un tour de modèle peut appeler plusieurs outils indépendants sans risque, configurez une limite de concurrence :

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

Le runtime conserve l’ordre des messages de résultat, même lorsque les exécutions locales se chevauchent.

## Guides associés

* [Mettre en pause, approuver et reprendre des exécutions](./agent-sdk-state-and-approval.mdx)
* [Diffuser les résultats de l’agent](./agent-sdk-streaming.mdx)
* [Exécuter des outils locaux en parallèle](../../cookbook/agent-sdk-parallel-tools.mdx)


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