deep-agents-core

<overview> Les Deep Agents sont un framework d'agent opiniâtre construit sur LangChain/LangGraph avec des middleware intégrés :

• Task Planning : TodoListMiddleware pour décomposer les tâches complexes
• Context Management : outils filesystem avec backends enfichables
• Task Delegation : middleware SubAgent pour spawner des agents spécialisés
• Long-term Memory : stockage persistant entre les threads via Store
• Human-in-the-loop : workflows d'approbation pour les opérations sensibles
• Skills : chargement à la demande de capacités spécialisées

Le harness d'agent fournit ces capacités automatiquement - tu configures, tu n'implémente pas. </overview>

<when-to-use>

</when-to-use>

<middleware-selection>

</middleware-selection>

<ex-basic-agent> <python> Crée un deep agent basique avec un outil personnalisé et invoque-le avec un message utilisateur.

from deepagents import create_deep_agent
from langchain.tools import tool

@tool
def get_weather(city: str) -> str:
    """Get the weather for a given city."""
    return f"It is always sunny in {city}"

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[get_weather],
    system_prompt="You are a helpful assistant"
)

config = {"configurable": {"thread_id": "user-123"}}
result = agent.invoke({
    "messages": [{"role": "user", "content": "What's the weather in Tokyo?"}]
}, config=config)

</python> <typescript> Crée un deep agent basique avec un outil personnalisé et invoque-le avec un message utilisateur.

import { createDeepAgent } from "deepagents";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(
  async ({ city }) => `It is always sunny in ${city}`,
  { name: "get_weather", description: "Get weather for a city", schema: z.object({ city: z.string() }) }
);

const agent = await createDeepAgent({
  model: "claude-sonnet-4-5-20250929",
  tools: [getWeather],
  systemPrompt: "You are a helpful assistant"
});

const config = { configurable: { thread_id: "user-123" } };
const result = await agent.invoke({
  messages: [{ role: "user", content: "What's the weather in Tokyo?" }]
}, config);

</typescript> </ex-basic-agent>

<ex-full-configuration> <python> Configure un deep agent avec toutes les options disponibles incluant les subagents, skills et persistance.

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langgraph.checkpoint.memory import MemorySaver
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    name="my-assistant",
    model="claude-sonnet-4-5-20250929",
    tools=[custom_tool1, custom_tool2],
    system_prompt="Custom instructions",
    subagents=[research_agent, code_agent],
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
    interrupt_on={"write_file": True},
    skills=["./skills/"],
    checkpointer=MemorySaver(),
    store=InMemoryStore()
)

</python> <typescript> Configure un deep agent avec toutes les options disponibles incluant les subagents, skills et persistance.

import { createDeepAgent, FilesystemBackend } from "deepagents";
import { MemorySaver, InMemoryStore } from "@langchain/langgraph";

const agent = await createDeepAgent({
  name: "my-assistant",
  model: "claude-sonnet-4-5-20250929",
  tools: [customTool1, customTool2],
  systemPrompt: "Custom instructions",
  subagents: [researchAgent, codeAgent],
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  interruptOn: { write_file: true },
  skills: ["./skills/"],
  checkpointer: new MemorySaver(),
  store: new InMemoryStore()
});

</typescript> </ex-full-configuration>

<built-in-tools> Chaque deep agent a accès à :

1. Planning : write_todos - Suivre les tâches multi-étapes
2. Filesystem : ls, read_file, write_file, edit_file, glob, grep
3. Delegation : task - Spawner des agents spécialisés </built-in-tools>

Format SKILL.md

<skill-md-format> Les skills utilisent la progressive disclosure - les agents ne chargent le contenu que s'il est pertinent.

Structure de Répertoire

skills/
└── my-skill/
    ├── SKILL.md        # Requis : fichier principal du skill
    ├── examples.py     # Optionnel : fichiers de support
    └── templates/      # Optionnel : templates

Format SKILL.md

---
name: my-skill
description: Description claire et spécifique de ce que ce skill fait
---

# Skill Name

## Overview
Explication brève de l'objectif du skill.

## When to Use
Conditions où ce skill s'applique.

## Instructions
Guidance étape par étape pour l'agent.

</skill-md-format>

<skills-vs-memory>

</skills-vs-memory>

<ex-skills-with-filesystem-backend> <python> Configure un agent avec répertoire de skills et filesystem backend pour le chargement à la demande.

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
    skills=["./skills/"],
    checkpointer=MemorySaver()
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Use the python-testing skill"}]
}, config={"configurable": {"thread_id": "session-1"}})

</python> <typescript> Configure un agent avec répertoire de skills et filesystem backend pour le chargement à la demande.

import { createDeepAgent, FilesystemBackend } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const agent = await createDeepAgent({
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  skills: ["./skills/"],
  checkpointer: new MemorySaver()
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "Use the python-testing skill" }]
}, { configurable: { thread_id: "session-1" } });

</typescript> </ex-skills-with-filesystem-backend>

<ex-skills-with-store-backend> <python> Charge le contenu des skills dans un backend Store pour les environnements sans accès filesystem.

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from deepagents.backends.utils import create_file_data
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

# Load skill content into store
skill_content = """---
name: python-testing
description: Best practices for Python testing with pytest
---
# Python Testing Skill
..."""

store.put(
    namespace=("filesystem",),
    key="/skills/python-testing/SKILL.md",
    value=create_file_data(skill_content)
)

agent = create_deep_agent(
    backend=lambda rt: StoreBackend(rt),
    store=store,
    skills=["/skills/"]
)

</python> </ex-skills-with-store-backend>

<boundaries>

Ce que les Agents PEUVENT Configurer

• Sélection et paramètres du modèle
• Outils personnalisés supplémentaires
• Personnalisation du system prompt
• Stratégie de stockage backend
• Quels outils nécessitent une approbation
• Agents spécialisés personnalisés avec outils spécialisés

Ce que les Agents NE PEUVENT PAS Configurer

• Suppression de middleware core (TodoList, Filesystem, SubAgent sont toujours présents)
• Les noms des outils write_todos, task, ou filesystem
• Le format frontmatter SKILL.md </boundaries>

<fix-checkpointer-for-interrupts> <python> Les interrupts nécessitent un checkpointer.

# WRONG
agent = create_deep_agent(interrupt_on={"write_file": True})

# CORRECT
agent = create_deep_agent(interrupt_on={"write_file": True}, checkpointer=MemorySaver())

</python> <typescript> Les interrupts nécessitent un checkpointer.

// WRONG
const agent = await createDeepAgent({ interruptOn: { write_file: true } });

// CORRECT
const agent = await createDeepAgent({ interruptOn: { write_file: true }, checkpointer: new MemorySaver() });

</typescript> </fix-checkpointer-for-interrupts>

<fix-store-for-memory> <python> StoreBackend nécessite une instance Store pour la mémoire persistante entre les threads.

# WRONG
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt))

# CORRECT
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt), store=InMemoryStore())

</python> <typescript> StoreBackend nécessite une instance Store pour la mémoire persistante entre les threads.

// WRONG
const agent = await createDeepAgent({ backend: (config) => new StoreBackend(config) });

// CORRECT
const agent = await createDeepAgent({ backend: (config) => new StoreBackend(config), store: new InMemoryStore() });

</typescript> </fix-store-for-memory>

<fix-thread-id-for-conversations> <python> Utilise un thread_id cohérent pour maintenir le contexte de conversation entre les invocations.

# WRONG: Chaque invocation est isolée
agent.invoke({"messages": [{"role": "user", "content": "Hi"}]})
agent.invoke({"messages": [{"role": "user", "content": "What did I say?"}]})

# CORRECT
config = {"configurable": {"thread_id": "user-123"}}
agent.invoke({"messages": [...]}, config=config)
agent.invoke({"messages": [...]}, config=config)

</python> <typescript> Utilise un thread_id cohérent pour maintenir le contexte de conversation entre les invocations.

// WRONG: Chaque invocation est isolée
await agent.invoke({ messages: [{ role: "user", content: "Hi" }] });
await agent.invoke({ messages: [{ role: "user", content: "What did I say?" }] });

// CORRECT
const config = { configurable: { thread_id: "user-123" } };
await agent.invoke({ messages: [...] }, config);
await agent.invoke({ messages: [...] }, config);

</typescript> </fix-thread-id-for-conversations>

<fix-frontmatter-required>

# WRONG: Frontmatter manquant dans SKILL.md
# My Skill
This is my skill...

# CORRECT: Inclure le frontmatter YAML
---
name: my-skill
description: Python testing best practices with pytest fixtures and mocking
---
# My Skill
This is my skill...

</fix-frontmatter-required>

<fix-backend-for-skills> <python> Les skills nécessitent un proper backend pour charger depuis le filesystem.

# WRONG: Les skills ne chargeront pas sans proper backend
agent = create_deep_agent(skills=["./skills/"])

# CORRECT: Utilise FilesystemBackend pour les skills locaux
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
    skills=["./skills/"]
)

</python> </fix-backend-for-skills>

<fix-specific-skill-descriptions> Utilise des descriptions spécifiques pour aider les agents à décider quand utiliser un skill.

# WRONG: Description vague
---
name: helper
description: Helpful skill
---

# CORRECT: Description spécifique
---
name: python-testing
description: Python testing best practices with pytest fixtures, mocking, and async patterns
---

</fix-specific-skill-descriptions>

<fix-subagent-skills> <python> Les skills ne sont pas hérités par les subagents - fournis-les explicitement.

# WRONG: Les subagents personnalisés n'héritent pas des skills
agent = create_deep_agent(
    skills=["/main-skills/"],
    subagents=[{"name": "helper", ...}]  # No skills
)

# CORRECT: Fournir les skills explicitement
agent = create_deep_agent(
    skills=["/main-skills/"],
    subagents=[{"name": "helper", "skills": ["/helper-skills/"], ...}]
)

</python> </fix-subagent-skills>