Quickstart：5 分鐘建立你的第一個 Deep Agent

理解了設計邏輯，下一步就是讓它跑起來。

這篇少廢話，直接帶你從安裝到第一個能動的代理人。整個過程不超過五分鐘——前提是你已經有 Python 環境，而且至少有一個可用的 LLM API key。

安裝

pip install -qU deepagents

需要用 OpenAI 當 LLM 後端的話，把 API key 設定好：

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

其他後端（Anthropic、Ollama、其他 LangChain 支援的 LLM）也都可以接，設定方式一樣，換成對應的環境變數就好。

最基本的代理人

直接來一個最簡版本，先讓它跑起來：

from deepagents import create_deep_agent
 
def get_weather(city: str) -> str:
    """取得指定城市的天氣資訊。"""
    return f"{city} 今天天氣晴朗，氣溫 25°C。"
 
agent = create_deep_agent(
    tools=[get_weather],
    system_prompt="你是一個實用的助理。",
)
 
result = agent.invoke({
    "messages": [{"role": "user", "content": "台北今天天氣怎麼樣？"}]
})
 
print(result["messages"][-1].content)

create_deep_agent 是入口點，最少只需要兩個參數：你的工具清單（tools），還有系統提示（system_prompt）。代理人會自動決定什麼時候呼叫哪個工具，你不需要自己設計呼叫邏輯。

加入多個工具

真實的代理人通常需要多個工具協作——

from deepagents import create_deep_agent
 
def search_web(query: str) -> str:
    """搜尋網路上的資訊。"""
    return f"關於 '{query}' 的搜尋結果：找到 3 筆相關資料。"
 
def read_document(filename: str) -> str:
    """讀取指定的文件內容。"""
    return f"文件 {filename} 的內容：這是一份重要的技術文件..."
 
def save_summary(content: str, output_file: str) -> str:
    """把摘要儲存到檔案。"""
    return f"已將摘要儲存至 {output_file}"
 
agent = create_deep_agent(
    tools=[search_web, read_document, save_summary],
    system_prompt="你是一個研究助理，擅長搜集資訊、閱讀文件、整理摘要。",
)
 
result = agent.invoke({
    "messages": [
        {"role": "user", "content": "幫我研究 Deep Learning 的最新發展，整理成摘要存到 summary.txt"}
    ]
})

注意這裡的任務有三個步驟——搜尋、整理、存檔。Deep Agents 的規劃能力就在這種多步驟場景裡才真正有感，代理人會自己決定執行順序，不需要你指定。

觀察代理人的思考過程

如果你想看到代理人呼叫工具的完整過程而不只是最終結果，開啟 streaming：

for chunk in agent.stream({
    "messages": [{"role": "user", "content": "台北今天天氣怎麼樣？"}]
}):
    print(chunk)

每一個 chunk 是一個步驟的輸出——你可以看到代理人決定呼叫哪個工具、工具回傳了什麼、然後代理人怎麼決定下一步。

接 LangSmith 做追蹤（選用）

如果你想要可視化的追蹤介面——哪個步驟花了多少時間、工具呼叫的詳細輸入輸出——設定兩個環境變數就好：

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

之後每次 invoke 或 stream，都會自動把 trace 送到 LangSmith dashboard。特別推薦在除錯階段開著，代理人做了什麼一目瞭然。

常見的第一次踩坑

工具的 docstring 不能省：代理人靠工具的文件字串（docstring）決定什麼時候呼叫它。寫得越清楚，代理人的判斷越準確。空的 docstring 或描述不清楚，代理人很容易選錯工具或根本不呼叫。

system_prompt 要給到位：不是越短越好，也不是越長越好。重點是把代理人的角色和主要任務說清楚——「你是一個研究助理，擅長 X、Y、Z」這類描述，比「你是一個 AI 助理」有用得多。

invoke 的 input 格式：用 messages 這個 key，value 是 list，每條 message 有 role 和 content。這個格式是固定的，打錯格式會直接報錯而不是給你奇怪的輸出。

你現在有什麼

一個可以：

呼叫自訂工具的代理人
串流輸出中間步驟的代理人
用 LangSmith 追蹤執行過程的代理人

但現在的代理人還缺一個能力——規劃。複雜任務丟給它，它會開始做，但不會先把任務拆開、排好順序再執行。這是下一篇要解決的事。

上一篇：什麼是 Deep Agents SDK？代理人框架背後的設計邏輯 下一篇：任務規劃與 write_todos：讓代理人先想清楚再做事