LangChain Deep Agents 指南：功能、工具與設定

使用 LangChain Deep Agents 打造能力更強的 AI agent。了解規劃、工具呼叫、檔案系統管理和子 agent 工作流程如何實現自主任務執行，並將 Kimi API 連接至你的 agent，賦予其進階的語言理解與推理能力。

取得你的 Kimi API Key

閱讀時長：12分鐘2026-08-13

隨著 AI agent 不再只是回答問題，而是開始從頭到尾處理任務，它們也變得越來越實用。LangChain Deep Agents 透過協助 agent 拆解工作、使用不同工具、管理資訊，以及協調較小的任務，帶來了更多的控制力與靈活性。這讓打造能夠處理真實世界工作流程、且不需要持續人為引導的 agent 變得更加容易。接下來，讓我們一起了解 LangChain Deep Agents 的運作方式，以及你可以用它們打造出什麼。

什麼是 LangChain Deep Agents？

LangChain Deep Agents 是建立在 LangChain 核心構件與 LangGraph 執行環境之上的一套 agent 框架。它在標準 agent 工作流程之上，內建了檔案系統存取、子 agent 委派、規劃、記憶以及人工介入支援等功能。Deep Agents 採用結合推理、工具呼叫與迭代執行的 agent 循環，因此適合處理需要多個步驟、大量上下文以及協調式工作流程的複雜任務。

與主要以簡單循環方式呼叫工具的基本 agent 不同，Deep Agents 為處理長時間執行的任務提供了額外的基礎架構。它們可以管理檔案、將工作委派給專門的子 agent、在複雜工作流程中維持上下文，並在必要時允許人工介入。這些內建功能減少了打造進階 agent 系統時所需要自行開發的工作量。

LangChain Deep Agents 的運作方式

當 Deep Agent 接收到任務時，它會分析請求並規劃完成任務所需的步驟，接著使用可用的工具（例如搜尋、程式碼執行或檔案系統操作）來收集資訊並執行動作。

在執行過程中，Deep Agents 透過讀寫檔案來管理上下文。它們不會把所有的中間結果都保留在對話歷史中，而是可以將大量資訊存放在外部，並在需要時再取用。這種做法有助於 agent 處理較長的工作流程，同時減少上下文視窗大小所帶來的限制。

對於涉及多個工作領域的複雜任務，Deep Agents 可以將特定的子任務委派給專門的子 agent。每個子 agent 專注於一個明確的目標，並將相關結果回傳給主 agent。主 agent 接著會整合子 agent 的輸出、取得的資訊以及儲存的檔案，產生完整且連貫的回應。

憑藉規劃、工具使用、檔案系統管理、子 agent 協作以及人工監督等功能，LangChain Deep Agents 為打造能夠處理多步驟真實世界任務、能力更強的 AI 系統提供了基礎。

Deep Agents 的核心能力：規劃、工具與執行

Deep Agents 能夠處理需要多個步驟、決策與動作的任務。它們的核心功能協助其規劃工作、使用合適的工具，並以較少的人工輸入有效完成每個步驟。讓我們逐一深入了解這些能力：

任務規劃

任務規劃讓 agent 能在執行過程中建立並管理一份結構化的任務清單。agent 不需要把複雜的目標當作單一指令來處理，而是可以將其拆分成較小的步驟，並在整個工作流程中追蹤進度、更新任務狀態。

何時使用規劃

較長或較複雜的多步驟任務
能從明確的進度追蹤與結構化執行中獲益的任務
需要從 agent 狀態串流顯示進度的使用者介面

如何啟用

將 TodoListMiddleware 傳遞給 middleware 參數，即可為 agent 提供一個 write_todos 工具，用於維護具有狀態追蹤（pending、in_progress、completed）的結構化任務清單。

from deepagents import create_deep_agent
from deepagents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="your-model",
    middleware=[TodoListMiddleware()],
)

任務會被保存在 agent 狀態中，為 agent 提供一層輕量化的規劃機制，用來組織長時間執行的工作。

虛擬檔案系統工具

Deep Agents 提供了一套可設定的虛擬檔案系統，背後由可插拔的後端支援，包括記憶體內狀態、本機磁碟、LangGraph store、複合式路由，或具有權限規則的自訂後端。

內建檔案系統工具

工具	說明
`ls`	列出目錄中的檔案及其元資料（大小、修改時間）
`read_file`	讀取檔案內容並附上行號；支援使用 offset/limit 處理大型檔案；同時會針對圖片、影片、音訊和文件回傳多模態內容區塊
`write_file`	建立新檔案或覆寫現有檔案
`edit_file`	在檔案中執行精確的字串替換(可搭配全域替換模式)
`delete`	遞迴刪除檔案或目錄
`glob`	尋找符合特定模式的檔案(例如 `*/.py`)
`grep`	以多種輸出模式搜尋檔案內容
`execute`	在環境中執行 shell 指令(僅限沙盒後端)

支援的多模態副檔名

圖片: .png、.jpg、.jpeg、.gif、.webp、.heic、.heif
影片: .mp4、.mpeg、.mov、.avi、.flv、.mpg、.webm、.wmv、.3gpp
音訊: .wav、.mp3、.aiff、.aac、.ogg、.flac
文件: .pdf、.ppt、.pptx

檔案系統權限

此執行框架支援宣告式權限規則,可控制 agent 能讀取或寫入哪些檔案與目錄。規則會依從上到下的順序評估,採第一個符合即生效的原則。

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:your-model",
    permissions=[
        {"operations": ["read", "write"], "paths": ["/workspace/**"], "mode": "allow"},
        {"operations": ["read"], "paths": [".env", "**/secrets/**"], "mode": "deny"},
    ],
)

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:your-model",
    permissions=[
        {"operations": ["read", "write"], "paths": ["/workspace/**"], "mode": "allow"},
        {"operations": ["read"], "paths": [".env", "**/secrets/**"], "mode": "deny"},
    ],
)

這讓你可以將 agent 限制在特定目錄中,保護敏感檔案,並讓子 agent 的存取權限比主 agent 更狹窄。

限制工具存取範圍

你可以透過向 FilesystemMiddleware 傳入 tools 白名單,只公開部分檔案系統工具。read_file 必須永遠包含在內。

from deepagents import create_deep_agent
from deepagents.middleware import FilesystemMiddleware

# Read-only agent
agent = create_deep_agent(
    model="your-model",
    middleware=[
        FilesystemMiddleware(backend=backend, tools=["read_file", "ls", "glob", "grep"]),
    ],
)

from deepagents import create_deep_agent
from deepagents.middleware import FilesystemMiddleware

# Read-only agent
agent = create_deep_agent(
    model="your-model",
    middleware=[
        FilesystemMiddleware(backend=backend, tools=["read_file", "ls", "glob", "grep"]),
    ],
)

子 Agent(委派)

此執行框架內建 task 工具,可讓主 agent 建立臨時性的子 agent,用於處理獨立、長時間執行、多步驟或並行的任務。

主要特性

全新情境: 每次呼叫都會建立一個擁有自身情境的新 agent 實例
自主執行: 子 agent 會獨立執行直到任務完成
單次交付: 子 agent 只向主 agent 回報一份最終結果
可設定策略: 可使用預設的 general-purpose 子 agent,也可自訂子 agent
情境效率: 繁重的子任務工作會被隔離處理,並壓縮成精簡的結果

停用子 Agent

若要在沒有 task 工具的情況下執行 agent,請透過執行框架設定檔停用自動加入的子 agent,並在 subagents= 中不傳入任何同步子 agent。請勿嘗試透過 excluded_middleware 移除 SubAgentMiddleware——這是刻意被拒絕的操作。

工具呼叫能力

Deep Agents 支援三類工具:

自訂函式與 LangChain 工具

可透過 tools= 參數直接傳入自訂函式或 LangChain 工具:

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_deep_agent(
    model="your-model",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_deep_agent(
    model="your-model",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

MCP(Model Context Protocol)

Deep Agents 完整支援 MCP,讓你能透過標準介面連接資料庫、API、檔案系統等。

程式碼執行

沙盒後端： 提供一個 execute 工具，用於在隔離環境中執行 shell 指令
解譯器： 新增一個 eval 工具，在有範圍限制的 QuickJS 執行環境中執行 JavaScript，構建輕量級的可程式化層

隨著這些能力整合在一起，驅動 Agent 的語言模型就成為整套架構中重要的一環。一個能力出色的模型可以幫助 Deep Agents 理解指令、對任務進行推理，並更好地運用可用的工具。Kimi API 可以提供這一層模型能力,使其成為構建更強大 Deep Agent 工作流程的自然選擇。

6 步將 Kimi API 連接到 LangChain Deep Agents

一個能力出色的模型能為你的 Deep Agent 提供有效處理任務所需的語言理解與推理能力。Kimi API 可以提供這些能力,同時讓 Agent 能運用工具、管理任務並處理複雜指令。有了模型層之後,接下來自然就是將 Kimi API 與 LangChain Agents 連接起來。以下是連接 Kimi API 與 LangChain Deep Agents 的方法：

步驟 1：取得你的 Kimi API 金鑰

登入 Kimi API 平台,建立一個新的 API 金鑰。複製並妥善保存該金鑰,因為你需要將它加入 Deep Agents 的設定中。此 API 金鑰用於驗證你的請求,讓 LangChain 的 Deep Agents 能透過 API 存取 Kimi 模型。

取得你的 Kimi API Key

步驟 2：設定環境變數

將你的 Kimi API 金鑰設定為環境變數。Kimi API 使用 Moonshot API 端點,因此請設定以下變數：

export MOONSHOT_API_KEY="your-api-key-here"

export MOONSHOT_API_KEY="your-api-key-here"

API 基礎網址為：

https://api.moonshot.ai/v1
``````text
https://api.moonshot.ai/v1

步驟 3：安裝相依套件

安裝 Deep Agents 及所需的 LangChain 相依套件：

pip install deepagents langchain-openai

pip install deepagents langchain-openai

由於 Kimi API 與 OpenAI 相容,langchain-openai 可讓 LangChain 透過 OpenAI 相容介面連接到 Kimi 模型。

如果你想為 Deep Agent 加入網頁搜尋能力,可以選擇安裝 Tavily：

pip install tavily-python

pip install tavily-python

從 Tavily 平台建立 Tavily API 金鑰後,將其設定為環境變數：

export TAVILY_API_KEY="your-tavily-api-key"

export TAVILY_API_KEY="your-tavily-api-key"

只有在你打算為 Agent 加入網頁搜尋工具時,才需要用到 Tavily。

步驟 4：使用 Kimi API 設定 Deep Agent

由於 Kimi API 與 OpenAI API 格式相容,你可以透過 init_chat_model 將其連接到 LangChain Deep Agents。

以下範例建立了一個以 Kimi 為驅動的基本 Deep Agent。你可以選擇為其擴充網頁搜尋等工具。

以 Kimi 驅動的基本 Deep Agent

from os import environ
from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model

kimi_model = init_chat_model(
    "kimi-k3",
    api_key=environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
    temperature=0.7,
)

agent = create_deep_agent(
    model=kimi_model,
    system_prompt="""You are an expert assistant.
Your job is to solve tasks with structured reasoning and provide clear outputs.
""",
)

from os import environ
from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model

kimi_model = init_chat_model(
    "kimi-k3",
    api_key=environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
    temperature=0.7,
)

agent = create_deep_agent(
    model=kimi_model,
    system_prompt="""You are an expert assistant.
Your job is to solve tasks with structured reasoning and provide clear outputs.
""",
)

加入網頁搜尋能力（選用）

若要啟用網頁搜尋,可連接一個搜尋工具,例如 Tavily：

from tavily import TavilyClient

tavily_client = TavilyClient(
    api_key=os.environ["TAVILY_API_KEY"]
)

def internet_search(query: str, max_results: int = 5):
    """Run a web search"""
    return tavily_client.search(
        query=query,
        max_results=max_results
    )

agent = create_deep_agent(
    model=kimi_model,
    tools=[internet_search],
    system_prompt="""You are an expert researcher.
Use the internet search tool when additional information is required.
""",
)

from tavily import TavilyClient

tavily_client = TavilyClient(
    api_key=os.environ["TAVILY_API_KEY"]
)

def internet_search(query: str, max_results: int = 5):
    """Run a web search"""
    return tavily_client.search(
        query=query,
        max_results=max_results
    )

agent = create_deep_agent(
    model=kimi_model,
    tools=[internet_search],
    system_prompt="""You are an expert researcher.
Use the internet search tool when additional information is required.
""",
)

透過此設定,Deep Agents 可以將 Kimi 作為推理模型,同時透過 Tavily 存取外部搜尋能力。

步驟 5：執行你的 Kimi 驅動 Deep Agent

配置好以 Kimi 驅動的 Deep Agent 後,執行該 Agent 以測試其處理任務與工具呼叫的方式。

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What is LangGraph?"}]}
)

print(result["messages"][-1].content)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What is LangGraph?"}]}
)

print(result["messages"][-1].content)

步驟 6：啟用 LangSmith 追蹤（選用）

LangSmith 追蹤能幫助你監控 Agent 的執行情況,包括工具呼叫、中間步驟以及模型回應。

透過以下環境變數啟用追蹤：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-api-key"

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-api-key"

當你需要更深入了解 Agent 工作流程、進行除錯或性能分析時,可以使用 LangSmith。

使用 Kimi API 連接 agent

使用 Kimi API 的優勢

將 Kimi API 與 Deep Agents 連接起來,可以讓複雜的工作流程更強大、更易於管理。這種組合能讓 Agent 具備更強的推理能力,同時能夠使用工具、處理檔案並完成多項任務。以下是這套設定可以帶來的幾項主要優勢：

提升 Agent 的推理與任務執行能力

Kimi 模型具備出色的語言理解與推理能力,能幫助 Deep Agents 分析複雜指令、拆解任務並生成更準確的回應。這使得 Agent 能以更少的人工干預,更有效地處理多步驟的工作流程。

打造更強大的 AI 工作流程

透過將 Kimi API 與 Deep Agents 連接,開發者可以將 Kimi 的模型能力與 LangChain 支援的工具、檔案系統及外部整合結合在一起。這讓 Agent 能在統一的工作流程中執行研究、文件處理、程式碼分析與資料處理等任務。

以自主 Agent 應對複雜任務的規模化擴展

以 Kimi 驅動的 Deep Agents 可以透過制定計畫、使用工具以及在需要時委派子任務,來管理長時間執行的任務。這讓開發者更容易建構能完成複雜工作流程的 AI 應用,同時減少重複的手動操作。

結語

打造可靠的 AI Agent，首要之務是為複雜工作流選對基礎架構。LangChain Deep Agents 提供了建構 Agent 所需的工具與架構，讓 Agent 能夠規劃、使用工具、管理上下文，並以更少的人工介入處理多步驟任務。搭配合適的模型與設定，開發者便能把進階的 Agent 構想落實為實際應用。透過整合 Kimi API，你還能為 Deep Agent 工作流注入強大的推理能力與長上下文處理能力。立即開始探索 Kimi API，發掘 AI Agent 能為你帶來的可能。

取得你的 Kimi API Key

常見問題

LangChain agent 與 Deep Agents 有什麼區別？

LangChain agent 為構建使用工具的 AI agent 提供了基礎架構。Deep Agents 在此基礎上加入了規劃、檔案管理、子 agent 委派、上下文處理等額外功能，讓 Deep Agents 更適合處理較長且更複雜的任務，同時也減少了另外開發這些功能的需求。

LangChain Deep Agents 可以用來做什麼？

LangChain Deep Agents 能夠處理需要多個步驟、工具使用以及持續決策的任務，可支援研究自動化、文件分析、程式碼理解、資料處理以及複雜工作流程執行等使用情境。對於涉及多個專業領域的任務，Deep Agents 可以將特定的子任務委派給專門的子 agent，再整合其結果。透過將 Deep Agents 與 Kimi API 連接，開發者可以打造出能運用 Kimi 推理能力與大型上下文視窗的 AI 應用程式，用於分析大量文件、處理複雜資訊，以及自動化知識密集型工作流程等任務。

我可以為 LangChain Deep Agent 加入記憶功能嗎？

可以，LangChain Deep Agents 可以透過現有的持久化與記憶整合來支援記憶功能。這有助於 agent 在多次互動與任務之間保留相關資訊，而不需要每次都從頭開始。記憶功能對於個人化工作流程、長時間執行的任務以及需要持續保存的資訊都很有用。