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

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Vue d’ensemble du SDK Agent

> Exécutez des boucles d’outils bornées et reprenables sur Phaseo Gateway avec le SDK Agent.

Utilisez un SDK Agent Phaseo quand une seule requête ne suffit pas : le SDK exécute dans votre processus une boucle bornée qui envoie chaque tour à l’API Responses, exécute les outils appelés par le modèle et se met en pause pour une personne quand un outil exige une approbation. Vous conservez l’état de l’exécution ; Phaseo n’héberge rien pour l’agent.

```mermaid theme={null}
flowchart LR
  input["Entrée"] --> turn["Tour du modèle via l’API Responses de Phaseo"]
  turn --> calls{{"Appels d’outils ?"}}
  calls -- "non" --> answer["Sortie finale"]
  calls -- "oui" --> gate{{"Approbation ou sortie manuelle requise ?"}}
  gate -- "non" --> tools["Exécuter les outils locaux"]
  tools --> limit{{"Condition d’arrêt atteinte ?"}}
  limit -- "non" --> turn
  limit -- "oui" --> stopped["Exécution arrêtée"]
  gate -- "oui" --> paused["Exécution en pause : enregistrez-la, puis reprenez"]
```

## Choisir votre package

| Langage | Package | Version | Client principal installé |
| - | - | - | - |
| TypeScript | [`@phaseo/agent-sdk`](https://www.npmjs.com/package/@phaseo/agent-sdk) | 0.3.0 | `@phaseo/sdk` |
| Python | [`phaseo-agent-sdk`](https://pypi.org/project/phaseo-agent-sdk/) (module `phaseo_agent`) | 0.3.0 | `phaseo` 3.x |
| Go | [`github.com/phaseoteam/Phaseo/packages/sdk/agent-sdk-go`](https://pkg.go.dev/github.com/phaseoteam/Phaseo/packages/sdk/agent-sdk-go) | v0.3.0 | `sdk-go/v3` |
| C# | [`Phaseo.AgentSdk`](https://www.nuget.org/packages/Phaseo.AgentSdk) | 0.3.0 | `Phaseo.Sdk` |
| PHP | [`phaseo/agent-sdk`](https://packagist.org/packages/phaseo/agent-sdk) | v0.3.0 | `phaseo/sdk` `^3.0.0` |
| Ruby | [`phaseo_agent_sdk`](https://rubygems.org/gems/phaseo_agent_sdk) | 0.3.0 | `phaseo_sdk` `>= 3.0.0, < 4.0.0` |
| Java | `app.phaseo:phaseo-agent-sdk` (Maven Central) | 0.3.0 | `app.phaseo:phaseo-sdk` 3.0.0 |
| Rust | [`phaseo-agent`](https://crates.io/crates/phaseo-agent) | 0.2.0 | `phaseo` 0.2 |

TypeScript sert de conception de référence. C++ n’a pas de SDK Agent. [Installation](https://phaseo.app/docs/fr/v1/sdk-reference/agent/installation.md) donne les commandes d’installation et les prérequis d’exécution, et [Utilisation](https://phaseo.app/docs/fr/v1/sdk-reference/agent/usage.md) construit un premier agent.

Demandez à un agent de code de construire un premier agent avec le SDK Agent Phaseo dans votre langage.

Build a small agent in this project with the Phaseo Agent SDK.

&#x20; 1\. Install the Phaseo skills: npx skills add [https://phaseo.app/docs](https://phaseo.app/docs)
&#x20;  For TypeScript, follow the phaseo-agent-sdk-typescript skill.
&#x20; 2\. Read the Agent SDK pages at [https://phaseo.app/docs/v1/sdk-reference/agent/overview](https://phaseo.app/docs/v1/sdk-reference/agent/overview.md), pick this project's language tab, and use only the APIs it documents.
&#x20; 3\. Define one agent with at most two local tools that fit \[AGENT TASK]. Keep the loop bounded with a step limit, and require approval for any tool that changes data.
&#x20; 4\. Use a server-side PHASEO\_API\_KEY and check the model ID with GET /v1/models before using it.
&#x20; 5\. Stream the agent's steps to the console so a run can be inspected.
&#x20; 6\. Run the agent once, then report what you verified and what you could not verify.

## Comparer ce que chaque runtime prend en charge

Chaque SDK exécute des outils locaux, se met en pause sur des ID d’appel d’outil exacts pour une approbation ou une sortie manuelle, et renvoie un état d’exécution sérialisable que votre application stocke. Le reste diffère selon le langage :

| Fonctionnalité | TypeScript | Python | Go | C# | PHP | Ruby | Java | Rust |
| - | - | - | - | - | - | - | - | - |
| Limite d’étapes par défaut | 12 | 12 | 8 | 12 | 12 | 12 | 12 | 8 |
| Limite d’étapes atteinte | Lève `Max steps exceeded` | Lève `RuntimeError` | Renvoie une erreur | Lève `InvalidOperationException` | Lève une exception | Lève une exception | Lève une exception | Renvoie une exécution `stopped` (`max_steps:N`) |
| Streaming du modèle | Itérable asynchrone | Itérateur (thread en arrière-plan) | Channel | Énumérable asynchrone | Itérable ; ne s’exécute que pendant que vous itérez (Fiber) | Énumérateur (thread de travail) | Listes après l’exécution ; en direct via `onEvent` | Pas encore |
| Événements de progression des outils | Générateur asynchrone | `emit_progress` ou générateur | `EmitProgress` | `EmitProgress` | `emitProgress` | `emit_progress` | `emitProgress` | Pas encore |
| Outils concurrents | Oui | Oui (threads) | Oui | Oui | Non | Oui (threads) | Oui (pool de threads) | Non |
| Délai d’expiration des outils | Interrompt `context.signal` | Fait échouer l’exécution ; le thread continue | Fait échouer l’appel ; la goroutine continue | Annule le `CancellationToken` | Vérifié après le retour de l’outil | Interrompt l’appel | Interrompt le thread | Aucun |
| Validation du schéma à l’exécution | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Non ; le JSON Schema est seulement envoyé au modèle |
| Erreur d’outil par défaut | Fait échouer l’exécution | Fait échouer l’exécution | Fait échouer l’exécution | Fait échouer l’exécution | Fait échouer l’exécution | Fait échouer l’exécution | Fait échouer l’exécution | Renvoyée au modèle |
| Approuver et rejeter par ID d’appel | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Approbation seulement |
| Outils interactifs (humain dans la boucle) | Oui | Oui | Oui | Oui | Oui | Oui | Oui | `human_review` au niveau de l’agent seulement |
| Conditions d’arrêt | Composables | Composables ; vérifiées seulement sur les étapes sans appel d’outil | Composables | Composables | Composables | Composables | Composables | Limite d’étapes |
| Tours dynamiques | Oui | Modèle, instructions et échantillonnage ; outils via `next_turn_params` | Oui | Oui | Oui | Oui | Oui | Modèle, limite d’étapes et contexte par exécution |
| Éléments de chronologie typés | Union `AgentItem` | Dicts | Map `Details` | Dictionnaire `Details` | Tableaux | Hashes | Map `details()` | Non ; lisez `messages` et `steps` |
| Utilisation et coût | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Tokens, plus le coût quand la réponse contient `meta.cost` ou `cost` |
| Annulation | `cancel()` | `cancel()` | Context | `CancellationToken` | `cancel()` | `cancel` | `cancel()` | Pas encore |
| Capture Devtools | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Pas encore |

Rust (`phaseo-agent` 0.2) est synchrone : pas de streaming, d’exécution asynchrone, d’outils concurrents, de validation du schéma à l’exécution ni de capture Devtools. Exécutez-le sur un thread de travail quand une exécution ne doit pas bloquer un gestionnaire de requêtes. PHP exécute les outils un par un, et son flux n’avance que pendant que votre code itère.

## Choisir le SDK Agent, le client ou l’API brute

| Pour | Choisissez | Ce qu’il prend en charge |
| - | - | - |
| Une requête API ou la couverture complète des endpoints | [SDK client](https://phaseo.app/docs/fr/v1/sdk-reference/client/overview.md) | Types d’API générés et transport |
| Une logique applicative multi-étapes qui utilise des outils | SDK Agent | Boucle locale, outils, points de reprise, revue, événements et Devtools |
| Un transport personnalisé ou un langage non pris en charge | API brute | Gestion des requêtes et réponses HTTP |

Le client gateway de chaque SDK Agent envoie les tours du modèle via le SDK client de ce langage. La plupart acceptent une map `requestOptions` (ou l’équivalent du langage) pour des champs supplémentaires de l’API Responses ; l’agent définit toujours `model`, `input`, `instructions` et ses outils de fonction. L’adaptateur Rust 0.2 n’envoie que les champs normalisés de l’agent et n’a pas de point d’extension pour des options supplémentaires.

## Partir d’une recette

| Recette | Langage |
| - | - |
| [Construire une boucle d’agent durable](https://phaseo.app/docs/fr/v1/cookbook/agent-sdk-durable-loop.md) | TypeScript |
| [Faire des recherches avec sortie structurée et recherche web](https://phaseo.app/docs/fr/v1/cookbook/agent-sdk-research-brief.md) | TypeScript |
| [Trier le support avec des préréglages et des échecs tenant compte des guardrails](https://phaseo.app/docs/fr/v1/cookbook/agent-sdk-support-triage.md) | TypeScript |
| [Exécuter un agent de revue de code avec des outils à l’exécution](https://phaseo.app/docs/fr/v1/cookbook/agent-sdk-coding-review.md) | TypeScript |
| [Répartir les outils d’agent locaux en parallèle](https://phaseo.app/docs/fr/v1/cookbook/agent-sdk-parallel-tools.md) | TypeScript |
| [Extraire du JSON structuré](https://phaseo.app/docs/fr/v1/cookbook/agent-sdk-python-structured-extraction.md) | Python |
| [Construire un agent de runbook d’exploitation](https://phaseo.app/docs/fr/v1/cookbook/agent-sdk-go-ops-runbook.md) | Go |
| [Trier des tickets](https://phaseo.app/docs/fr/v1/cookbook/agent-sdk-csharp-ticket-triage.md) | C# |
| [Relire du contenu CMS](https://phaseo.app/docs/fr/v1/cookbook/agent-sdk-php-content-review.md) | PHP |
| [Résumer des notes internes](https://phaseo.app/docs/fr/v1/cookbook/agent-sdk-ruby-rag-notes.md) | Ruby |

Les recettes TypeScript se transposent à n’importe quel langage avec les API décrites sur ces pages.


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