🤖 Qu'est-ce qu'un agent ?

Un agent est une unité d'exécution IA définie par un prompt. Contrairement aux workflows (étapes prédéfinies), un agent reçoit un prompt, des credentials et un contexte, puis l'IA décide comment accomplir la tâche.

Chaque agent peut avoir :

Un prompt (texte libre, le cœur de l'agent)
Un schéma de configuration (JSON Schema, validation AJV) pour des paramètres ajustables
Un schéma d'input pour les données d'entrée structurées
Un schéma d'output pour valider les résultats
Des skills et tools qui étendent ses capacités

✨ Créer un agent

Via l'interface

Cliquez sur Nouvel agent dans la barre latérale
Donnez un nom et écrivez votre prompt
(Optionnel) Connectez des providers pour donner accès à des services externes
Cliquez sur Exécuter

Via l'API

curl -X POST http://localhost:3000/api/packages/agents \
  -H "Authorization: Bearer ask_your_key" \
  -H "X-App-Id: app_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "email-summarizer",
    "description": "Résumé les emails récents"
  }'

✍️ Écrire un prompt efficace

Le prompt est injecté dans le conteneur agent via la variable AGENT_PROMPT. Il est enrichi automatiquement avec des sections contextuelles :

User Input — les données d'entrée fournies au lancement du run
Configuration — les valeurs de configuration de l'agent
Previous State — l'état persisté du run précédent
Run History API — l'URL pour consulter l'historique des runs

Conseils :

Soyez précis sur la tâche à accomplir
Décrivez le format de sortie attendu
Mentionnez les providers disponibles et comment les utiliser
Utilisez la section "Previous State" pour des agents qui maintiennent un suivi

⚙️ Configuration

Le schéma de configuration est un JSON Schema qui définit les paramètres ajustables de l'agent. Les utilisateurs remplissent ces champs via un formulaire auto-généré dans l'interface.

{
  "schema": {
    "type": "object",
    "properties": {
      "maxEmails": {
        "type": "number",
        "description": "Nombre maximum d'emails à traiter"
      },
      "language": {
        "type": "string",
        "enum": ["fr", "en", "es"]
      }
    },
    "required": ["maxEmails"]
  }
}

La validation utilise AJV avec coerceTypes: true (ex: "50" accepté comme nombre). Les propriétés additionnelles sont toujours autorisées.

📥 Input et Output

Le schéma d'input définit les données attendues à chaque run. Le schéma d'output active la validation du résultat.

Si un schéma d'output est défini :

Il est injecté dans le conteneur via OUTPUT_SCHEMA pour le constrained decoding du LLM
Après le run, AJV valide le résultat
En cas de mismatch, un warning est enregistré mais le run n'échoue pas

🧩 Skills

Les skills sont des documents Markdown (SKILL.md) avec un frontmatter YAML (name, description) qui étendent les connaissances de l'agent. Ils sont rendus disponibles dans le conteneur à .pi/skills/{id}/SKILL.md.

Pour attacher des skills à un agent :

curl -X PUT http://localhost:3000/api/agents/@scope/agent-name/skills \
  -H "Authorization: Bearer ask_your_key" \
  -H "X-App-Id: app_xxx" \
  -H "Content-Type: application/json" \
  -d '{"skills": ["sk_xxx", "sk_yyy"]}'

🔧 Tools

Les tools sont des extensions MCP-style qui ajoutent des fonctions appelables par l'agent au runtime. Signature : execute(_toolCallId, params, signal) — params est le deuxième argument. Le retour doit être { content: [{ type: "text", text: "..." }] }.

💾 État persistant

Chaque run peut produire un result.state (JSON). Cet état est stocké et injecté automatiquement dans la section ## Previous State du prompt au run suivant. Cela permet de créer des agents qui maintiennent un suivi entre les exécutions (ex: "derniers emails traités").

🧠 Mémoires

Les mémoires sont un stockage clé-valeur par application, attaché à un agent. Elles sont accessibles via l'API :

# Lister les mémoires
curl http://localhost:3000/api/agents/@scope/agent-name/memories \
  -H "Authorization: Bearer ask_your_key" \
  -H "X-App-Id: app_xxx"

# Supprimer une mémoire
curl -X DELETE http://localhost:3000/api/agents/@scope/agent-name/memories/mem_xxx \
  -H "Authorization: Bearer ask_your_key" \
  -H "X-App-Id: app_xxx"

🔀 Override de modèle et proxy

Chaque agent peut avoir un modèle LLM spécifique (différent du modèle par défaut de l'organisation) et un proxy dédié pour les requêtes sortantes.

# Configurer le modèle d'un agent
curl -X PUT http://localhost:3000/api/agents/@scope/agent-name/model \
  -H "Authorization: Bearer ask_your_key" \
  -H "X-App-Id: app_xxx" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "mod_xxx"}'

La cascade de proxy suit l'ordre : override agent → proxy par défaut org → PROXY_URL env var.

Agents