deep-agents-core

Deep Agents は、LangChain/LangGraph 上に構築された、組み込みミドルウェアを備えた意見を持ったエージェントフレームワークです：

• タスク計画: 複雑なタスクを分解するための TodoListMiddleware
• コンテキスト管理: プラグイン可能なバックエンドを備えたファイルシステムツール
• タスク委任: 特化したエージェントを生成するための SubAgent ミドルウェア
• 長期メモリ: Store を介したスレッド間での永続ストレージ
• Human-in-the-loop: 機密性の高い操作に対する承認ワークフロー
• スキル: 特化した機能のオンデマンド読み込み

エージェントハーネスはこれらの機能を自動的に提供します - 実装するのではなく、設定するだけです。

Deep Agents を使う場合	LangChain の create_agent を使う場合
計画を必要とするマルチステップのタスク	単純な単一目的のタスク
ファイル管理を必要とする大きなコンテキスト	コンテキストが単一のプロンプトに収まる
特化したサブエージェントが必要	単一のエージェントで十分
セッションをまたぐ永続メモリ	一時的な単一セッションの作業

必要なこと...	ミドルウェア	備考
複雑なタスクを追跡する	TodoListMiddleware	デフォルトで有効
ファイルコンテキストを管理する	FilesystemMiddleware	バックエンドを設定
作業を委任する	SubAgentMiddleware	カスタムサブエージェントを追加
人間の承認を追加する	HumanInTheLoopMiddleware	チェックポインターが必要
スキルを読み込む	SkillsMiddleware	スキルディレクトリを指定
メモリにアクセスする	MemoryMiddleware	Store インスタンスが必要

カスタムツールを備えた基本的な deep agent を作成し、ユーザーメッセージで呼び出します。

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)

カスタムツールを備えた基本的な deep agent を作成し、ユーザーメッセージで呼び出します。

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);

サブエージェント、スキル、永続化を含む、利用可能なすべてのオプションを備えた deep agent を設定します。

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()
)

サブエージェント、スキル、永続化を含む、利用可能なすべてのオプションを備えた deep agent を設定します。

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()
});

すべての deep agent は以下にアクセスできます：

1. 計画: write_todos - マルチステップのタスクを追跡
2. ファイルシステム: ls、read_file、write_file、edit_file、glob、grep
3. 委任: task - 特化したサブエージェントを生成

---

SKILL.md の形式

スキルは**段階的開示**を使用します - エージェントは関連する場合にのみコンテンツを読み込みます。

ディレクトリ構造

skills/
└── my-skill/
    ├── SKILL.md        # Required: main skill file
    ├── examples.py     # Optional: supporting files
    └── templates/      # Optional: templates

SKILL.md の形式

---
name: my-skill
description: Clear, specific description of what this skill does
---

# Skill Name

## Overview
Brief explanation of the skill's purpose.

## When to Use
Conditions when this skill applies.

## Instructions
Step-by-step guidance for the agent.

スキル	メモリ（AGENTS.md）
オンデマンド読み込み	起動時に常に読み込まれる
タスク固有の指示	一般的な設定
大きなドキュメント	コンパクトなコンテキスト
ディレクトリ内の SKILL.md	単一の AGENTS.md ファイル

オンデマンドのスキル読み込みのために、スキルディレクトリとファイルシステムバックエンドを備えたエージェントをセットアップします。

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"}})

オンデマンドのスキル読み込みのために、スキルディレクトリとファイルシステムバックエンドを備えたエージェントをセットアップします。

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" } });

ファイルシステムにアクセスできない環境向けに、スキルコンテンツを Store バックエンドに読み込みます。

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/"]
)

エージェントが設定できること

• モデルの選択とパラメータ
• 追加のカスタムツール
• システムプロンプトのカスタマイズ
• バックエンドのストレージ戦略
• 承認が必要なツール
• 特化したツールを備えたカスタムサブエージェント

エージェントが設定できないもの

• コアミドルウェアの削除（TodoList、Filesystem、SubAgent は常に存在）
• write_todos、task、filesystem ツールの名前
• SKILL.md のフロントマター形式

割り込みにはチェックポインターが必要です。

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

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

割り込みにはチェックポインターが必要です。

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

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

StoreBackend はスレッド間で永続的なメモリを維持するために Store インスタンスを必要とします。

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

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

StoreBackend はスレッド間で永続的なメモリを維持するために Store インスタンスを必要とします。

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

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

呼び出し間で会話コンテキストを維持するには、一貫した thread_id を使用してください。

# WRONG: Each invocation is isolated
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)

呼び出し間で会話コンテキストを維持するには、一貫した thread_id を使用してください。

// WRONG: Each invocation is isolated
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);

# WRONG: Missing frontmatter in SKILL.md
# My Skill
This is my skill...

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

スキルはファイルシステムから読み込むために適切なバックエンドを必要とします。

# WRONG: Skills won't load without proper backend
agent = create_deep_agent(skills=["./skills/"])

# CORRECT: Use FilesystemBackend for local skills
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
    skills=["./skills/"]
)

エージェントがいつスキルを使用すべきかを判断できるよう、具体的な説明を使用してください。

# WRONG: Vague description
---
name: helper
description: Helpful skill
---

# CORRECT: Specific description
---
name: python-testing
description: Python testing best practices with pytest fixtures, mocking, and async patterns
---

スキルはサブエージェントに継承されません - 明示的に提供してください。

# WRONG: Custom subagents don't inherit skills
agent = create_deep_agent(
    skills=["/main-skills/"],
    subagents=[{"name": "helper", ...}]  # No skills
)

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