Skip to content
This repository was archived by the owner on Jul 25, 2026. It is now read-only.

agent-teams.md

Latest commit

 

History

History
120 lines (88 loc) · 4.18 KB

agent-teams.md

File metadata and controls

120 lines (88 loc) · 4.18 KB
Raw

Agent Teams (Delegation)

Coordinate multiple Codex agents working in true parallel with separate context windows.

Enable

Sous Codex CLI 0.130+, les agent teams reposent sur multi_agent (Stable, default true) et tool_search (Stable). L'installer écrit explicitement :

# ~/.codex/config.toml
[features]
multi_agent = true       # Stable (anciennement collab — alias legacy préservé)
tool_search = true

Notes audit 0.130 :

  • steer : retiré en 0.129+ (Enter submit = comportement par défaut)
  • enable_fanout, child_agents_md : UnderDevelopment côté OpenAI — laissés aux défauts Codex (false) pour ne pas activer des features non finalisées. Les promotions futures vers Stable seront prises en compte automatiquement.

Activation manuelle si besoin :

codex features enable enable_fanout
codex features enable child_agents_md

Architecture

┌─────────────────────────────────────────────┐
│              LEAD (Coordinator)              │
│  TeamCreate → TaskCreate → SendMessage      │
│  mode: "delegate" (NEVER writes code)       │
├──────────┬──────────┬───────────────────────┤
│ Agent A  │ Agent B  │ Agent C               │
│ Own ctx  │ Own ctx  │ Own ctx               │
│ Own files│ Own files│ Own files             │
└──────────┴──────────┴───────────────────────┘

Each agent runs in its own context window with isolated memory.

Delegation Rules

1. Lead = Coordinator ONLY

The lead agent orchestrates but NEVER implements. Use mode: "delegate" to restrict the lead to coordination-only tools (TeamCreate, TaskCreate, SendMessage).

2. File Ownership

Each teammate owns distinct files. Two agents editing the same file leads to overwrites.

Agent A → src/components/Header.tsx, src/hooks/useHeader.ts
Agent B → src/components/Footer.tsx, src/hooks/useFooter.ts
Agent C → src/services/api.ts, src/utils/helpers.ts

3. Well-Scoped Tasks

Every TaskCreate must specify:

  • Target files - Which files to create/modify
  • Expected output - What the result should look like
  • Acceptance criteria - How to validate success
  • Dependencies - addBlockedBy for task ordering

4. Mandatory TaskUpdate

Teammates MUST call TaskUpdate with status: "completed" when done. Forgetting this blocks dependent tasks indefinitely.

5. Max 4 Teammates

Beyond 4 agents, coordination overhead exceeds parallelism gains.

APEX Integration

Agent Teams power the Analyze phase of APEX:

TeamCreate → spawn 3 teammates:
├── explore-codebase  (architecture mapping)
├── research-expert   (documentation lookup)
└── [domain-expert]   (framework-specific analysis)

Results are synthesized by the lead before the Plan phase.

Anti-Patterns

Pattern Problem Fix
Lead implements code Defeats delegation purpose Use mode: "delegate"
Shared file edits Overwrites between agents Assign exclusive file ownership
Vague tasks Agents waste tokens guessing Specify files + criteria
Missing TaskUpdate Dependent tasks blocked forever Always mark completed
5+ teammates Overhead > gains Cap at 4 agents max

Known Limitations

  • /resume does not restore in-process teammates
  • One team per session (no nested teams)
  • Teammates cannot spawn their own teams
  • High token usage (~4x single agent for 4 teammates)

Example Workflow

1. TeamCreate("feature-auth")
2. TaskCreate("Implement login form")
   → files: src/components/LoginForm.tsx
   → criteria: Zod validation, shadcn/ui
3. TaskCreate("Implement auth API")
   → files: src/services/auth.ts
   → criteria: Better Auth integration
4. TaskCreate("Add auth tests")
   → files: src/__tests__/auth.test.ts
   → blockedBy: [task-1, task-2]
5. Spawn teammates → assign tasks → TaskUpdate on completion
6. Lead runs sniper for final validation