構建和部署你的第一個自主AI代理的7個步驟

本文提供了一個完整的、逐步的指南，幫助你構建和部署你的第一個自主研究代理。該指南基於LangGraph框架和Claude模型，涵蓋從概念到生產的全過程。

引言

大多數人的第一個AI代理從未離開過他們的筆記型電腦。它在終端中執行一次，輸出一個合理的答案，然後就閒置在那裡，因為沒有人編寫必要的膠水程式碼來使指令碼成為其他人或其他系統可以實際呼叫的服務。這種“它在執行時有效”與“它已上線，並且有人在使用它”之間的差距，正是大多數代理專案悄然消亡的地方。

資料支援這一點。根據一份涵蓋Gartner、McKinsey和IDC資料的2026年統計資料綜述，近79%的公司表示他們以某種形式採用了AI代理，但只有大約11%的公司有在生產中執行的專案。這個差距不是一個小問題。它是演示與產品之間的區別，而且幾乎從來不是因為模型不夠強大，而是因為沒有人正確地界定工作範圍、沒有人處理故障、或者沒有人費心將程式容器化並放在一個有URL的地方。

本文針對一個特定專案彌合了這一差距。到本文結束時，你將構建並部署一個研究代理：你給它一個主題，它搜尋網路，提取來源，然後返回一份帶有連結的簡短書面簡報。它足夠複雜，需要實際的工具使用、記憶和防護措施，但又足夠小，你可以在一次坐下來構建整個專案。下面的每個程式碼塊都是完整並帶有註釋的，並且每個程式碼塊之後都有對其作用和原因的解釋。

步驟一：決定你的代理實際需要做什麼（以及不該做什麼）

在開啟編輯器之前，寫下三件事：代理唯一的任務是什麼、成功的輸出是什麼樣的、以及在沒有人工檢查之前它永遠不允許做什麼。

對於我們的研究代理，這看起來像這樣：

• 任務：接受一個主題作為輸入，進行網路搜尋，閱讀結果，並生成一份包含摘要和來源列表的書面簡報。
• 成功的輸出：一份連貫、事實有依據、不超過500字的簡報，每個聲稱都可透過來源URL追溯。
• 硬性邊界：它可以自由搜尋和閱讀，但未經人員批准，它永遠不會發布任何內容、傳送任何內容或寫入其工作區以外的檔案。

第三步比聽起來更重要。跳過這一步是Gartner預計到2027年底將有超過40%的自主AI專案被取消的重要原因之一，通常是因為沒有人及早定義邊界，導致專案要麼做得太少而無法實用，要麼做得太多而無法信任。

步驟二：選擇你的模型和框架

你需要做兩個決定：哪個模型負責推理，哪個框架管理思考、行動和檢查結果的迴圈。

對於模型，任何具有良好工具使用能力的當前前沿模型都符合要求：Claude、GPT和Gemini都可以。我們在下面的程式碼中使用Claude，因為它的工具呼叫在多步驟任務中一直可靠，但更換為其他提供商只需更改一行程式碼。

對於框架，這是2026年下半年的情況：

• LangGraph：將代理建模為圖中的節點和邊，內建檢查點，使得崩潰的執行可以恢復而無需重新開始。每月PyPI下載量超過3800萬次，Klarna、Uber和LinkedIn等公司在生產中使用它。代價是學習曲線較陡，通常需要一兩週才能掌握。
• CrewAI：將代理建模為具有角色和目標的“團隊”，你可以在20行程式碼內讓某物工作。這是驗證想法的最快方法，在GitHub上獲得了超過44,000顆星，但一旦工作流變得複雜，它提供的控制就較少，團隊通常會遷移到LangGraph。
• AutoGen：曾經是多代理對話模式的預設選擇，但現在微軟已將其置於維護模式，並轉向統一的Microsoft Agent Framework，因此不建議在2026年用於新專案。
• 供應商SDK：如OpenAI Agents SDK或Anthropic的Claude Agent SDK，如果你完全致力於一個供應商並希望最小的框架開銷，值得考慮，但它們會將你鎖定在該供應商的模型上。

我們在此構建中使用LangGraph，因為研究代理受益於檢查點（超時的搜尋不應意味著重新開始），並且因為這是最直接轉移到實際生產工作的技能版本。

步驟三：設定專案

建立一個資料夾、一個虛擬環境，並安裝所需的依賴。

mkdir research-agent && cd research-agent
python3 -m venv venv
source venv/bin/activate
pip install langgraph langchain-anthropic langchain-community python-dotenv tavily-python beautifulsoup4

虛擬環境使此專案的包與機器上的其他專案隔離，避免了專案間依賴更新的問題。安裝的包涵蓋了編排（langgraph）、模型連線（langchain-anthropic）、即用型網路搜尋工具和頁面載入器（langchain-community加上tavily-python和beautifulsoup4）以及安全金鑰管理（python-dotenv）。

接下來，在專案根目錄建立一個.env檔案來存放你的金鑰。你需要一個來自Anthropic Console的Anthropic API金鑰和一個來自Tavily的搜尋API金鑰，Tavily提供足夠本教程使用的免費層級。

# .env檔案，切勿將其提交到版本控制
ANTHROPIC_API_KEY=your-anthropic-key-here
TAVILY_API_KEY=your-tavily-key-here

最後，設定資料夾結構：

research-agent/
├── venv/
├── .env
├── .gitignore
├── agent.py
├── app.py
├── requirements.txt
└── Dockerfile

將agent.py（代理邏輯）與app.py（公開代理的網路伺服器）分離，使程式碼可讀，並允許在包裝成API之前直接測試代理。將.env和venv/新增到.gitignore中，防止金鑰洩露。

步驟四：構建核心代理迴圈

這是專案的核心：代理讀取任務、決定是否需要工具、呼叫工具、讀取結果、並決定下一步做什麼的迴圈。開啟agent.py並逐步構建。

# agent.py
from dotenv import load_dotenv
from langchain_anthropic import ChatAnthropic
from langchain_community.tools.tavily_search import TavilySearchResults
from langgraph.prebuilt import create_react_agent

load_dotenv()

model = ChatAnthropic(model="claude-sonnet-4-6", temperature=0.2, max_tokens=1500)
search_tool = TavilySearchResults(max_results=5)
agent = create_react_agent(model, tools=[search_tool])

def run_research(topic: str) -> str:
    result = agent.invoke({
        "messages": [
            ("system", "You are a research assistant. When given a topic, search for current, credible information and write a brief under 500 words. Every factual claim must be followed by the source URL in parentheses. If sources disagree, say so."),
            ("user", topic),
        ]
    })
    return result["messages"][-1].content

if __name__ == "__main__":
    topic = input("What should I research? ")
    print(run_research(topic))

逐行說明：load_dotenv()從.env檔案讀取金鑰；ChatAnthropic建立與模型的連線；低溫度設定使得答案更注重準確性而非創造性；TavilySearchResults為代理提供訪問即時網際網路的能力；create_react_agent是LangGraph構建經典推理迴圈（ReAct，推理和行動）的快捷方式；system訊息強制代理引用來源並指出分歧。

從終端中執行python agent.py，輸入一個主題，你應該會收到一份帶有連結的簡短簡報。如果掛起或出錯，檢查.env檔案中的金鑰是否正確以及是否處於啟用的虛擬環境中。

步驟五：賦予記憶和第二個工具

目前，代理完成後會忘記一切。這對於單個問題沒問題，但當使用者詢問後續問題（如“現在比較一下X”）時就不行了。我們將透過新增對話記憶來解決這個問題，並且新增第二個工具，以便當搜尋摘要不夠詳細時，代理可以提取整個頁面的內容。

# agent.py (updated)
from dotenv import load_dotenv
from langchain_anthropic import ChatAnthropic
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain_community.document_loaders import WebBaseLoader
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver

load_dotenv()

model = ChatAnthropic(model="claude-sonnet-4-6", temperature=0.2, max_tokens=1500)
search_tool = TavilySearchResults(max_results=5)

@tool
def read_page(url: str) -> str:
    """Fetches the readable text of a single web page."""
    try:
        loader = WebBaseLoader(url)
        docs = loader.load()
        return docs[0].page_content[:3000]
    except Exception as e:
        return f"Could not load that page: {e}"

SYSTEM_PROMPT = (
    "You are a research assistant with memory. Use the search and read_page tools "
    "to gather information. Keep track of the conversation history. Always cite sources."
)

memory = MemorySaver()
agent = create_react_agent(model, tools=[search_tool, read_page], checkpointer=memory)

config = {"configurable": {"thread_id": "research thread"}}

def run_research(topic: str) -> str:
    result = agent.invoke({"messages": [("user", topic)]}, config=config)
    return result["messages"][-1].content

if __name__ == "__main__":
    topic = input("What should I research? ")
    print(run_research(topic))

這裡的關鍵變化：使用@tool裝飾器定義了read_page函式；MemorySaver新增了檢查點功能，使得對話歷史得以儲存；系統提示現在作為常量定義，檢查點機制會自動處理訊息歷史；config中的thread_id標識會話，使得後續呼叫可以關聯到同一個對話。

步驟六：使用FastAPI將代理暴露為API

現在，代理在終端中工作得很好，但我們需要透過Web API使其可呼叫。我們將使用FastAPI來建立端點，並非同步處理請求以避免長時間執行任務阻塞伺服器。

# app.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from agent import run_research

app = FastAPI()

class ResearchRequest(BaseModel):
    topic: str

@app.post("/research")
async def research(request: ResearchRequest):
    if not request.topic:
        raise HTTPException(status_code=400, detail="Topic cannot be empty")
    result = run_research(request.topic)
    return {"result": result}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

步驟七：透過Docker容器化部署

最後，我們將代理容器化，以便在任何支援Docker的環境（如雲伺服器或Kubernetes）中一致地執行。

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

構建映象並執行：

docker build -t research-agent .
docker run -d -p 8000:8000 --env-file .env research-agent

現在，你的代理可以透過http://localhost:8000/research呼叫，並帶有對話記憶、工具使用和持久化狀態。將容器部署到任何雲服務（如AWS ECS、Google Cloud Run或Azure Container Instances）只需一次推送。

結論

本文帶你從零到生產構建了一個自主研究代理。關鍵要點包括：精確定義任務邊界、選擇適合的工具框架、構建具有記憶和工具的核心迴圈、透過API暴露、以及容器化部署。這些技能直接適用於更復雜的生產級代理專案。