---
title: "Agents de code, proxy LLM et services Kodema"
description: "Utiliser des agents avec Kodema : MCP PM/Orchestrateur, proxy LLM natif, budgets, kodema harness exec, service OpenCode worktree et sandboxes Brain/Hands."
canonical_url: https://optimi.com/fr/docs/kodema/agents
md_url: https://optimi.com/fr/docs/kodema/agents.md
language: fr
alternates:
  - lang: en
    url: https://optimi.com/en/docs/kodema/agents
    md_url: https://optimi.com/en/docs/kodema/agents.md
last_updated: 2026-11-22
---

# Agents de code et services agentiques

Kodema offre un parcours continu de l’orchestration interactive sur votre poste
jusqu’à la livraison autonome 24/7 — sans jamais exposer de clés API LLM brutes
aux conteneurs ou aux pods d’agents, et sans plugin spécifique par harnais.

## Point de départ : votre harnais en PM & Orchestrateur

Aucun cluster Kubernetes ni aucun build local n’est nécessaire pour livrer avec
Kodema. Connectez votre harnais IA quotidien (**Claude Code**, **Codex**,
**OpenCode** ou **Cursor**) à votre instance locale `kodema up` :

```sh
kodema up
source ~/.kodema/instances/default/env.sh
printf '%s' "$ANTHROPIC_API_KEY" | kodema secret set ANTHROPIC_API_KEY --stdin
# ou OPENAI_API_KEY / OPENCODE_API_KEY, ou --value-file <chemin>
kodema mcp install claude              # ou codex, opencode, cursor (--print pour prévisualiser)
kodema docs install --target agents    # ou claude, opencode, all
```

Lors de l’initialisation MCP, votre harnais reçoit automatiquement les
instructions PM/Orchestrateur ainsi que les ressources et prompts
`kodema://docs/*` alignés sur la version. Travaillez avec lui pour rédiger les
specs dans KV (`kv_put`), appliquer les pipelines (`pipeline_apply`), piloter
les tâches multi-étapes (`task_create_and_start`, `task_start`), consulter
journaux et consommation de jetons (`execution_inspect`, `execution_logs_read`),
trancher les revues en 3 décisions (`execution_request_resolve` avec
`pass | revise | fail`) et clôturer (`task_complete`) — tout le code, les tests
et les merges protégés s’exécutant dans Kodema.

## Proxy LLM natif et budgets actifs

Kodema intègre un proxy LLM en streaming avec injection d’identifiants
(`/llm/{provider}/*`). `kodema up` active trois fournisseurs par défaut, et vous
pouvez ajouter tout point d’entrée compatible OpenAI (OpenRouter, LiteLLM,
vLLM, Ollama) avec `--llm-provider` ou `--models-file` :

| Fournisseur | Variable injectée | Chemin proxy | Upstream par défaut | Secret projet |
| --- | --- | --- | --- | --- |
| `openai` | `KODEMA_LLM_OPENAI_BASE_URL` | `${KODEMA_URL}/llm/openai/v1` | `https://api.openai.com` | `OPENAI_API_KEY` |
| `anthropic` | `KODEMA_LLM_ANTHROPIC_BASE_URL` | `${KODEMA_URL}/llm/anthropic` | `https://api.anthropic.com` | `ANTHROPIC_API_KEY` |
| `opencode` | `KODEMA_LLM_OPENCODE_BASE_URL` | `${KODEMA_URL}/llm/opencode/v1` | `https://opencode.ai/zen/v1` | `OPENCODE_API_KEY` |
| Personnalisé `<slug>` | `KODEMA_LLM_<SLUG>_BASE_URL` | `${KODEMA_URL}/llm/<slug>/v1` | `base_url` configurée | Secret configuré |

```sh
kodema up \
  --llm-provider openrouter=https://openrouter.ai/api/v1 \
  --llm-provider local-vllm=http://host.containers.internal:8000/v1,secret=VLLM_API_KEY
```

Les clés fournisseur restent strictement dans le plan de contrôle : Kodema
refuse de monter dans un conteneur (`secrets: [...]`) tout secret détenu par un
fournisseur du proxy LLM.

### Budgets actifs en jetons et USD

Les budgets sont appliqués en direct avant chaque appel sortant sur trois
niveaux :

1. **Par action :** `budget: {max_tokens, max_cost_usd}` sur une action conteneur.
2. **Par exécution :** `budget` en tête de pipeline (la borne la plus stricte
   entre le pipeline et les valeurs par défaut de l’installation prévaut).
3. **Par tâche :** budget par défaut cumulé sur toutes les exécutions d’une même
   tâche.

Dès qu’un seuil est atteint, le proxy répond HTTP `429` (`budget_exceeded`) et
enregistre un événement `model.budget_exceeded`. Un budget en USD échoue de
manière sécurisée si le modèle n’a pas de tarif défini dans `models.json`.
Consultez la consommation détaillée avec `kodema inspect <execution-id>`.

## Modèle A : harnais en conteneur (`kodema harness exec`)

Idéal quand chaque étape de code ou de vérification doit tourner dans un Job
conteneur sans état, sans pod d’agent persistant.

Encapsulez la commande de votre harnais avec **`kodema harness exec -- <cmd>`**
(intégré dans `/kodema/bin/kodema`, présent dans le `PATH` de chaque action) :

```sh
kodema harness exec -- opencode run "Implement /kodema/task/spec.json and verify tests pass"
kodema harness exec -- claude -p "Implement /kodema/task/spec.json and verify tests pass" --dangerously-skip-permissions
kodema harness exec -- codex exec "Implement /kodema/task/spec.json and verify tests pass"
kodema harness exec -- pi -p "Implement /kodema/task/spec.json and verify tests pass"
```

`kodema harness exec` démarre un proxy HTTP éphémère en boucle locale
(`127.0.0.1:0`) qui :

- Fait confiance à `$KODEMA_CA_FILE` vers `$KODEMA_URL` (sans boilerplate
  `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE` ou `CURL_CA_BUNDLE` pour le trafic LLM).
- Relit `/kodema/secrets/KODEMA_TOKEN` à chaque requête sortante, de sorte
  qu’une rotation de jeton pendant une longue session ne provoque jamais de `401`.
- Exporte `OPENAI_*`, `ANTHROPIC_*`, `OPENCODE_*`, `KODEMA_HARNESS_PROXY_URL`
  et les `KODEMA_LLM_*_BASE_URL` réécrites avec une clé locale aléatoire.
- Renseigne automatiquement `OPENCODE_CONFIG_CONTENT` (s’il est vide) pour
  router `opencode` (Zen), `openai` et `anthropic` sur le proxy local.

### SDLC multi-étapes avec revue en 3 décisions et Decision IDs

Enchaînez trois pipelines courts sur une même tâche (`completes_task: false`)
avec le store KV et `service/merge-coordinator` :

1. **Implémentation :** lit `spec_key` depuis KV, lance `kodema harness exec`,
   pousse `refs/heads/work/$KODEMA_TASK`, stocke `summary_key` dans KV et
   produit `branch`, `base`, `candidate` et `summary_key`.
2. **Vérification et revue :** exécute des tests déterministes dans une image
   outillage dédiée avec `caches: [go-mod, go-build]`, dépose le rapport dans KV
   et attend sur `request: role/reviewer` :
   - `kodema approve` (`pass`) émet un `decision_id` immuable.
   - `kodema revise --reason "…"` ajoute le retour à la tâche et la garde `open`
     sans alerter les opérateurs.
   - `kodema reject --reason "…"` met l’exécution en échec et alerte les
     opérateurs.
3. **Fusion sérialisée :** transmet `decision_id` à
   `request: service/merge-coordinator` (`kodema services --kind merge_coordinator`),
   qui sérialise les pushs vers `target_ref` avec `-o kodema.decision_id=<id>`.
   Clôturez explicitement la tâche avec `kodema task complete <task-id>`.

La suite complète et testée se trouve dans
[`examples/agentic-sdlc/`](https://github.com/optimiware/kodema/tree/master/examples/agentic-sdlc).

## Modèle B (Option 1) : service OpenCode par projet (`--mode worktree`)

Passez à un service OpenCode v2 permanent par projet qui conserve une correspondance
durable `task_id -> opencode_session_id` au fil des tours (`plan`, `implement`,
`fix`, `revise`, `ai_review`) tout en isolant chaque tâche dans son propre
worktree Git local (`refs/heads/work/<task-id>`) :

```sh
OPENCODE_PASSWORD="$(cat /path/to/opencode.password)" \
  opencode serve --hostname 127.0.0.1 --port 4096

kodema services --kind opencode \
  --mode worktree \
  --service opencode-shop \
  --tenant tenant-local \
  --project project-local \
  --base-url "$KODEMA_URL" \
  --ca-file "$KODEMA_CA_FILE" \
  --credential-file /path/to/opencode-shop.token \
  --state-dir /var/lib/kodema/opencode-shop \
  --git-url "${KODEMA_GIT_URL:-${KODEMA_URL}/git}" \
  --opencode-url http://127.0.0.1:4096 \
  --opencode-password-file /path/to/opencode.password \
  --llm-proxy-listen 127.0.0.1:18080 \
  --per-turn-proxy-routing \
  --max-concurrency 4
```

Propriétés clés :

- **Proxy LLM attribué (`kodsvc.`) :** appelle `/llm/{provider}/*` avec son
  jeton `kodsvc.` et les en-têtes `X-Kodema-Execution` et `X-Kodema-Action` liés
  à la demande active `request: service/<id>`. Kodema applique les budgets,
  impute l’usage dans `model_usage` et coupe le flux en cas d’annulation ou
  d’expiration.
- **Privilèges minimaux (`roles: []`) :** l’Option 1 en mode worktree ne requiert
  **aucun rôle `engineer`** — un compte de service actif dans le projet plus
  `RW+ refs/heads/work/` dans `admin/conf/git.conf` suffisent.
- **Annulation en direct par SSE :** surveille le flux d’événements du projet et
  appelle `AbortSession` sur OpenCode dès qu’une exécution est annulée.
- **Concurrence :** activez `--per-turn-proxy-routing` pour exécuter
  `--max-concurrency > 1` derrière `--llm-proxy-listen`.

Dans un pipeline, envoyez les tours à `request: service/<service-id>` avec
`subject.mode` (`plan`, `implement`, `fix`, `revise`, `ai_review`), `repository`,
`base_ref` et les clés KV optionnelles (`plan_key`, `feedback_key`), en déclarant
les sorties souhaitées (`branch`, `candidate`, `summary_key`, `plan_key`,
`review_key`, `session_id`).

## Modèle C (Option 2) : séparation Brain/Hands (`--mode brain` + `kodema sandbox serve`)

Séparez le raisonnement LLM et les sessions persistantes (**Brain**) de
l’exécution des builds et tests (**Hands**) afin que le pod Brain n’exécute
jamais de commande shell locale et que chaque étape utilise une image outillage
standard (`golang:1.24`, `node:22`, `python:3.12`) :

1. **`kodema sandbox serve` (Hands) :** compilé dans `/kodema/bin/kodema` en Go
   stdlib pur — aucune image d’agent personnalisée requise. Expose un serveur
   MCP Streamable HTTP (`POST /mcp`, `GET /healthz`) confiné strictement à
   `/workspace` par `os.Root`, offrant 6 outils (`read_file`, `write_file`,
   `edit_file`, `glob`, `grep`, `bash`) derrière une authentification Bearer en
   temps constant, suppression des variables de jeton dans les sous-processus
   `bash` et arrêt par groupe de processus sur timeout.
2. **OpenCode Brain (`--mode brain`) :** désactive tous les outils locaux shell
   et fichiers dans OpenCode et lance dynamiquement des sandboxes éphémères par
   tâche via l’API publique de Kodema (`KodemaExecutionSandboxManager`) :

```sh
kodema services --kind opencode \
  --mode brain \
  --service opencode-shop \
  --tenant tenant-local \
  --project project-local \
  --base-url "$KODEMA_URL" \
  --ca-file "$KODEMA_CA_FILE" \
  --credential-file /path/to/opencode-shop.token \
  --state-dir /var/lib/kodema/opencode-shop \
  --opencode-url http://127.0.0.1:4096 \
  --opencode-password-file /path/to/opencode.password \
  --llm-proxy-listen 127.0.0.1:18080 \
  --max-concurrency 1 \
  --sandbox-default-image docker.io/library/golang:1.24 \
  --sandbox-caches go-mod,go-build \
  --sandbox-port 8090 \
  --sandbox-memory 2Gi \
  --sandbox-cpu 2
```

Différences importantes avec l’Option 1 :

- **Requiert le rôle `engineer` :** le compte de service Brain a besoin de
  `engineer` pour lancer les exécutions sandbox (`pipeline.start`), les arrêter
  (`execution.cancel`) et livrer des jetons Bearer éphémères `KODEMA_SBOX_TOK_*`
  hors bande (`secret.write` / `secret.delete`).
- **Tours sans sandbox :** les tours de raisonnement (`plan`, `ai_review`) sans
  `sandbox_image` s’exécutent directement dans le Brain sans lancer de conteneur.
- **Chaînes polyglottes :** surchargez `sandbox_image`, `sandbox_caches`,
  `sandbox_memory` et `sandbox_cpu` par action (ex. Go pour le backend et Node
  pour le frontend dans un même pipeline).
- **Concurrence et isolation :** l’attachement MCP d’OpenCode v2 étant lié au
  répertoire, le mode Brain impose `--max-concurrency 1` par instance serveur
  OpenCode v2 (déployez plusieurs instances pour paralléliser). Sur Kubernetes,
  activez `opencodeBrain` dans le chart Helm `kodema` pour générer les
  NetworkPolicies strictes entre pods Brain et pods `kodema.dev/role: sandbox`.

## Contexte partagé et compétences d’entreprise

Stockez vos conventions d’équipe, blueprints et compétences Markdown dans des
dépôts Git dédiés (`<tenant>/context`, `<tenant>/<project>/context`), puis
récupérez-les et validez-les dans vos conteneurs ou sur vos postes :

```sh
kodema context pull --repo context --repo myproject/context \
  --target agents --agents-md AGENTS.md --include-kodema-docs
kodema context list --dir ./context
kodema context show build-and-test --dir ./context
```

`kodema context pull` contrôle chaque fichier contre les liens symboliques
sortants, les limites de taille et les fuites de secrets avant de matérialiser
les compétences dans `.agents/skills/`, `.claude/skills/` ou `.opencode/skills/`.

Suite : **[Référence CLI](/fr/docs/kodema/cli)** et
**[API et MCP](/fr/docs/kodema/api)**.
