構建和部署你的第一個自主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暴露、以及容器化部署。這些技能直接適用於更復雜的生產級代理項目。