03 — Créer des ingénieurs IA (agents)

Objectif : comprendre ce qu’est un agent dans Opencode et créer vos propres « ingénieurs » spécialisés (frontend, backend, IA, revue de code, sécurité).

1. Qu’est-ce qu’un agent ?

Un agent est une configuration qui donne à Opencode un rôle, un modèle et des permissions précis. C’est comme embaucher un spécialiste : même moteur, mais une spécialité, des habitudes et des droits différents.

Deux types d’agents

Type	Rôle	Exemple
Primary	L’assistant principal avec qui vous parlez (bascule avec `Tab`)	`build`, `plan`
Subagent	Un spécialiste invoqué à la demande (via `@agent`) ou délégué automatiquement	`explore`, `general`, `scout`

Les subagents sont la pièce maîtresse pour créer votre équipe d’ingénieurs : vous les invoquez manuellement, ou l’agent principal les sollicite automatiquement quand la tâche correspond à leur description.

2. Les agents intégrés

Agent	Mode	Spécialité
`build`	primary	Agent par défaut, tous les outils activés
`plan`	primary	Analyse et planification, ne modifie rien
`general`	subagent	Recherche et tâches multi-étapes, peut modifier
`explore`	subagent	Exploration rapide du code, lecture seule
`scout`	subagent	Recherche dans la doc et les dépendances externes

3. Créer son premier agent

Deux façons : l’assistant interactif ou le fichier manuel.

Méthode rapide — l’assistant interactif

opencode agent create

Il pose quelques questions (emplacement, description, permissions) et génère le fichier pour vous.

Méthode manuelle — un fichier Markdown

Créez un fichier dans .opencode/agents/ (projet) ou ~/.config/opencode/agents/ (global). Le nom du fichier devient le nom de l’agent.

.opencode/agents/code-reviewer.md :

---
description: Reviews code for quality, security and performance without editing.
mode: subagent
model: anthropic/claude-sonnet-4-6
temperature: 0.1
permission:
  edit: deny
---

You are a senior code reviewer. Review the requested code or diff and report:
- bugs and edge cases
- security issues
- performance concerns
- readability and maintainability
Suggest concrete fixes, but never edit files yourself.

C’est tout ! Après un redémarrage d’Opencode, vous pouvez l’invoquer :

@code-reviewer Passe en revue le dernier commit

Redémarrage : Opencode charge la configuration au démarrage. Après avoir créé ou modifié un agent, quittez et relancez opencode.

4. Les champs du frontmatter

Champ	Rôle
`description`	Obligatoire. Ce que fait l’agent et quand l’utiliser. C’est ce qui permet l’invocation automatique.
`mode`	`primary`, `subagent` ou `all` (défaut `all`)
`model`	Sur-mesure par rôle (ex. un modèle rapide pour planifier, un puissant pour implémenter). Format `provider/model-id`.
`permission`	Ce que l’agent a le droit de faire (`allow` / `ask` / `deny`)
`temperature`	Créativité : `0.1` pour de l’analyse rigoureuse, `0.7` pour du brainstorming
`steps`	Nombre max d’itérations agentiques (limite de coût)
`hidden`	`true` pour cacher de l’autocomplétion `@`
`color`	Couleur d’affichage dans l’interface

Tout champ inconnu du frontmatter est transmis au modèle comme option provider (ex. reasoningEffort).

5. Les permissions par agent

C’est ce qui fait de vos agents des collaborateurs sûrs plutôt que des exécutants dangereux.

---
permission:
  edit: deny              # ne peut jamais écrire
  bash:
    "*": ask              # par défaut, demande validation
    "git status*": allow  # mais certaines commandes sont libres
    "git push*": ask
    "rm *": deny          # jamais de suppression sauvage
---

⚠️ Dans les règles, la dernière règle correspondante gagne. Placez le "*" d’abord, les règles spécifiques ensuite.

6. Notre équipe d’ingénieurs (fichiers fournis)

Le dossier exemples/.opencode/agents/ contient 5 agents prêts à l’emploi, prompts en anglais :

Fichier	Rôle	Particularité
`frontend-engineer.md`	Ingénieur frontend (React/TS)	Écrit de l’UI soignée, accessibilité, responsive
`backend-engineer.md`	Ingénieur backend	API, bases de données, performances
`ai-engineer.md`	Ingénieur IA	Intégration LLM, prompts, données, évaluation
`code-reviewer.md`	Revues de code	Lecture seule (`edit: deny`)
`security-auditor.md`	Audits de sécurité	Lecture seule, focus vulnérabilités

À copier dans votre projet pour disposer immédiatement d’une équipe :

cp -r exemples/.opencode/agents/ .opencode/agents/

7. Déléguer : le pattern chef de projet

flowchart TD
    U[Vous — chef de projet] -->|Tab / plan & validation| P[build — agent primaire]
    P -->|tâche frontend| FE[frontend-engineer]
    P -->|tâche backend| BE[backend-engineer]
    P -->|tâche IA| AI[ai-engineer]
    P -->|revue du diff| CR[code-reviewer]
    P -->|audit sécurité| SA[security-auditor]
    FE -->|résultat + tests| U
    BE -->|résultat + tests| U
    AI -->|résultat + évaluation| U
    CR -->|rapport de revue| U
    SA -->|rapport d'audit| U
    style U fill:#fef9c3,stroke:#ca8a04,color:#713f12
    style P fill:#eef2ff,stroke:#4f46e5,color:#312e81
    style FE fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95
    style BE fill:#ecfeff,stroke:#0891b2,color:#164e63
    style AI fill:#fff7ed,stroke:#ea580c,color:#7c2d12
    style CR fill:#f0fdf4,stroke:#16a34a,color:#14532d
    style SA fill:#fef2f2,stroke:#dc2626,color:#7f1d1d

@backend-engineer Ajoute le champ deleted_at au modèle Note avec une migration,
                  en suivant le pattern de @src/models/note.py

Vous restez le chef de projet : vous définissez le quoi et le pourquoi, l’agent s’occupe du comment dans son domaine. Multipliez la productivité sans perdre le contrôle.

8. Définir des agents via opencode.json (alternatif)

Certains préfèrent tout centraliser dans opencode.json :

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for quality and best practices.",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-6",
      "permission": { "edit": "deny" },
      "prompt": "You are a strict code reviewer..."
    }
  }
}

Pour les agents non triviaux, préférez les fichiers Markdown : plus lisibles, plus faciles à versionner.

Récapitulatif

Un agent = rôle + modèle + permissions.
Un fichier .opencode/agents/<nom>.md = un agent.
description bien écrite = invocation automatique fiable.
Permissions restrictives par défaut, étendues ensuite.
@nom pour invoquer manuellement un subagent.

Passez au chapitre 04 — Commandes pour automatiser vos prompts récurrents.