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 インスタンスが必要

カスタムツールを備えた基本的なディープエージェントを作成し、ユーザーメッセージで呼び出します。 ```python 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>
カスタムツールを備えた基本的なディープエージェントを作成し、ユーザーメッセージで呼び出します。
```typescript
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);

サブエージェント、スキル、永続化など、利用可能なすべてのオプションを使ってディープエージェントを設定します。 ```python 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>
サブエージェント、スキル、永続化など、利用可能なすべてのオプションを使ってディープエージェントを設定します。
```typescript
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()
});

すべてのディープエージェントは、次の機能を利用できます。

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 ファイル

スキルディレクトリとファイルシステムバックエンドを備えたエージェントを設定し、スキルを必要に応じて読み込めるようにします。 ```python 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>
スキルディレクトリとファイルシステムバックエンドを備えたエージェントを設定し、スキルを必要に応じて読み込めるようにします。
```typescript
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 バックエンドに読み込みます。 ```python 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>
### エージェントが設定できる項目

- モデルの選択とパラメーター
- 追加のカスタムツール
- システムプロンプトのカスタマイズ
- バックエンドのストレージ戦略
- 承認が必要なツール
- 専門ツールを備えたカスタムサブエージェント
### エージェントが設定できないこと

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

<fix-checkpointer-for-interrupts>
<python>
割り込みにはチェックポインターが必要です。
```python
# WRONG
agent = create_deep_agent(interrupt_on={"write_file": True})

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

割り込みにはチェックポインターが必要です。 ```typescript // 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 でスレッド間の永続的なメモリを使用するには、Store インスタンスが必要です。
```python
# WRONG
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt))

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

StoreBackend でスレッド間の永続的なメモリを使用するには、Store インスタンスが必要です。 ```typescript // 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>
呼び出し間で会話のコンテキストを維持するには、一貫した thread_id を使用してください。
```python
# 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 を使用してください。 ```typescript // 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);

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

<fix-frontmatter-required>
```markdown
# 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...

ファイルシステムからスキルを読み込むには、適切なバックエンドが必要です。 ```python # 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/"] )

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

<fix-specific-skill-descriptions>
エージェントがスキルをいつ使用するか判断しやすいよう、具体的な説明を記述してください。
```markdown
# 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
---

スキルはサブエージェントに継承されないため、明示的に指定してください。 ```python # 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/"], ...}] )

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