入門必懂的 10 個 Agent 核心概念：用 TaoToken 統(tǒng)一 Key 跑通第一個 Agent 示例)
1. 從“會聊天”到“會干活”Agent 開發(fā)入門到底在學什么很多人第一次接觸 Agent 開發(fā)腦子里其實只有一個模糊印象不就是讓大模型自己調(diào)工具、自己干活嗎但真動手寫的時候問題立刻冒出來——它為什么知道該調(diào)哪個工具它怎么記住上一輪說過的話任務拆到一半卡住了怎么辦這些疑問背后其實對應的是 Agent 的十個核心概念。把這十個概念串起來你才算真正跨過了 Agent 開發(fā)入門的門檻。這篇內(nèi)容聚焦一件事把抽象概念落到可運行的最小 Agent 示例上。我會用統(tǒng)一的 Key 和 API 通道在本地跑通一個能規(guī)劃、能調(diào)工具、能記住上下文的 Agent然后逐項檢查每個概念是否真的生效。你不需要先啃完論文跟著配置和代碼走一遍概念自然就對應上了。適合誰看如果你已經(jīng)會調(diào)用大模型 API但沒寫過 Agent 循環(huán)或者用過 Claude Code 這類工具卻說不清它內(nèi)部怎么“思考”再或者想自己搭一個能查天氣、能讀寫文件的小助手這篇就是為你準備的。核心檢索詞就三個Agent、開發(fā)、核心概念——我們邊跑邊理解。先明確一個前提Agent 不是某個具體框架而是一種運行模式。它的最小骨架就是“感知 → 思考 → 行動 → 觀察”的循環(huán)。你后面看到的所有高級能力規(guī)劃、記憶、多 Agent 協(xié)作都是在這個循環(huán)上疊加出來的。所以第一步我們先把循環(huán)跑起來再談其他。2. 用 TaoToken 統(tǒng)一 Key 打通 Agent 的模型調(diào)用通道寫 Agent 最煩的一件事是模型調(diào)用通道不統(tǒng)一。今天試這個模型明天換那個接口Key 散落在各個環(huán)境變量里調(diào)試的時候光找配置就耗掉一半精力。我的做法是用一個統(tǒng)一的 API 通道把模型調(diào)用固定下來Agent 代碼里只認一個 Base URL 和一個 Key換模型只改一個 Model ID。這里我用 TaoToken 來做這件事。它的 API 地址是 https://taotoken.net/api兼容常見的 OpenAI 風格調(diào)用方式所以你在 Agent 代碼里用 openai 這個 SDK 就能直接連。對 Agent 開發(fā)入門來說這一點很關(guān)鍵——你不需要為每個模型寫一套適配層統(tǒng)一通道能讓你的循環(huán)邏輯保持干凈。先拿 Key。打開 https://taotoken.net/api-keys 登錄后創(chuàng)建一個 API Key復制出來。注意這個 Key 只顯示一次先存到安全的地方。然后我們把它寫進環(huán)境變量不要硬編碼在代碼里。在項目根目錄建一個.env文件TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用 Python裝兩個包pip install openai python-dotenv然后在代碼里這樣初始化客戶端import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) MODEL_ID claude-sonnet-4-5-20250929 # 按需替換這里有個細節(jié)Base URL 結(jié)尾不要帶/v1SDK 會自己拼路徑。如果你寫成https://taotoken.net/api/v1請求會變成/api/v1/v1/chat/completions直接 404。這個坑我踩過排查了半天。統(tǒng)一通道的好處在你寫 Agent 循環(huán)時會特別明顯。因為 Agent 一次任務可能要調(diào)用模型十幾次每次的請求格式都一樣只是消息歷史在變。如果通道不統(tǒng)一你會在不同模型的參數(shù)差異上浪費大量時間?，F(xiàn)在你只需要關(guān)心消息怎么組織、工具怎么描述、循環(huán)怎么退出。另外提醒一句Key 不要提交到 Git。把.env加進.gitignore團隊協(xié)作時用環(huán)境變量注入。Agent 項目里經(jīng)常會有多個工具和子進程Key 泄露的風險比普通腳本高這點要養(yǎng)成習慣。3. 可復制的 Agent 最小配置Base URL、Key 與 Model ID 三件套概念要落地得先有一個能跑的最小 Agent。我們不追求功能多只追求把核心循環(huán)、工具調(diào)用、記憶這三件事跑通。下面這份配置你可以直接復制改掉 Key 就能用。先看目錄結(jié)構(gòu)mini-agent/ ├── .env ├── agent.py └── tools.py.env就是上一步那兩行。tools.py里定義兩個最簡單的工具一個查時間一個算加法。工具描述要寫清楚因為模型靠描述決定調(diào)哪個。# tools.py import datetime def get_current_time(city: str) - str: 獲取指定城市的當前時間。當用戶詢問時間相關(guān)問題時使用。 now datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) return f{city} 當前時間{now} def add_numbers(a: float, b: float) - str: 計算兩個數(shù)字的和。當用戶需要做加法運算時使用。 return f{a} {a b} TOOL_MAP { get_current_time: get_current_time, add_numbers: add_numbers, } TOOLS_SCHEMA [ { type: function, function: { name: get_current_time, description: 獲取指定城市的當前時間。當用戶詢問時間相關(guān)問題時使用。, parameters: { type: object, properties: { city: {type: string, description: 城市名稱} }, required: [city], }, }, }, { type: function, function: { name: add_numbers, description: 計算兩個數(shù)字的和。當用戶需要做加法運算時使用。, parameters: { type: object, properties: { a: {type: number, description: 第一個數(shù)字}, b: {type: number, description: 第二個數(shù)字}, }, required: [a, b], }, }, }, ]注意工具描述里的“當用戶……時使用”。這不是寫給人看的注釋是寫給模型看的觸發(fā)條件。描述越具體模型選錯工具的概率越低。我試過把描述寫成“處理數(shù)據(jù)”結(jié)果模型在需要算加法時去調(diào)了時間工具因為它覺得“處理”也能涵蓋。然后是主循環(huán)agent.py# agent.py import json import os from dotenv import load_dotenv from openai import OpenAI from tools import TOOL_MAP, TOOLS_SCHEMA load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) MODEL_ID claude-sonnet-4-5-20250929 def run_agent(user_input: str, max_turns: int 5): messages [ {role: system, content: 你是一個會使用工具的助手。需要時調(diào)用工具不要憑空猜測。}, {role: user, content: user_input}, ] for turn in range(max_turns): response client.chat.completions.create( modelMODEL_ID, messagesmessages, toolsTOOLS_SCHEMA, tool_choiceauto, ) msg response.choices[0].message messages.append(msg) if not msg.tool_calls: print(f[最終回答] {msg.content}) return msg.content for tool_call in msg.tool_calls: name tool_call.function.name args json.loads(tool_call.function.arguments) print(f[調(diào)用工具] {name} 參數(shù){args}) result TOOL_MAP[name](**args) print(f[工具結(jié)果] {result}) messages.append({ role: tool, tool_call_id: tool_call.id, content: str(result), }) print([警告] 達到最大輪次強制結(jié)束) return None if __name__ __main__: run_agent(現(xiàn)在上海幾點順便幫我算一下 128 加 256 等于多少)這份配置里Base URL、Key、Model ID 三件套齊全。你把它保存下來python agent.py就能跑。跑通之后我們再逐項驗證概念。4. 跑通第一個 Agent 并逐項驗證十個核心概念是否生效現(xiàn)在運行python agent.py你會看到類似這樣的輸出[調(diào)用工具] get_current_time 參數(shù){city: 上海} [工具結(jié)果] 上海 當前時間2026-01-15 14:32:07 [調(diào)用工具] add_numbers 參數(shù){a: 128, b: 256} [工具結(jié)果] 128 256 384 [最終回答] 上海現(xiàn)在是 2026-01-15 14:32:07128 加 256 等于 384。一次任務里模型先調(diào)時間工具再調(diào)加法工具最后匯總回答。這個過程里十個核心概念其實都在悄悄起作用。我們逐項對照。核心循環(huán)Perceive 是用戶輸入Think 是模型決定調(diào)哪個工具Act 是執(zhí)行工具Observe 是工具結(jié)果回填到 messages。循環(huán)在for turn in range(max_turns)里轉(zhuǎn)了兩圈才結(jié)束。你可以把max_turns改成 1會看到它只調(diào)一個工具就被強制結(jié)束——這就是循環(huán)邊界的作用。工具調(diào)用模型輸出的tool_calls就是 Function Calling。它自己不執(zhí)行只是表達“我要調(diào) get_current_time參數(shù)是上海”。真正執(zhí)行的是TOOL_MAP[name](**args)。MCP 在這個最小例子里沒出現(xiàn)但你可以理解為如果工具變多就需要一個協(xié)議來管理工具從哪來、怎么連那就是 MCP 要解決的問題。規(guī)劃與任務分解用戶一句話里有兩個需求模型自動拆成兩步先時間后加法。它沒有一次性把兩個工具都調(diào)了而是按順序來。這就是最樸素的規(guī)劃。你可以試著問“先算 11再告訴我北京幾點最后把兩個結(jié)果拼起來”觀察它怎么排順序。記憶系統(tǒng)messages列表就是短期記憶。工具結(jié)果被 append 進去模型下一輪能看到。如果你把messages清空再問同樣的問題它就不知道之前算過什么。長期記憶需要你額外寫文件比如把用戶偏好存到MEMORY.md下次啟動時讀進來。上下文窗口管理這個例子里消息很短看不出壓力。但如果你把max_turns調(diào)到 20再讓它反復讀大文件就會遇到上下文超限。策略是按需加載——只把相關(guān)工具結(jié)果放進 messages不要把所有歷史都塞進去。ReAct 范式模型在調(diào)工具前其實內(nèi)部有 Thought只是這個例子里沒顯式打印。你可以在 system prompt 里加一句“每次調(diào)用工具前先用一句話說明你的理由”然后打印msg.content就能看到它的推理過程。多 Agent 協(xié)作最小例子里只有一個 Agent。要驗證多 Agent你可以起兩個進程一個負責查時間一個負責算數(shù)用主進程調(diào)度。但入門階段先不用急單 Agent 跑順了再擴展。錯誤處理把add_numbers的參數(shù)故意傳成字符串看模型怎么反應。它可能會重試也可能直接報錯。你可以在工具函數(shù)里加 try/except返回錯誤信息給模型讓它自己糾正。安全與對齊這個例子里工具都是只讀的沒有風險。如果你加一個“刪除文件”工具就應該在描述里寫“調(diào)用前必須確認”并在代碼里加確認邏輯。四層防御里人類確認是最后一道。編排框架選型現(xiàn)在你是用原生 SDK 手寫循環(huán)。等任務復雜了可以考慮 LangGraph 這類框架。但入門階段手寫一遍能讓你真正理解每個環(huán)節(jié)后面用框架時才知道它在幫你做什么。跑完這一遍十個概念就不再是名詞而是你代碼里能指認出來的具體位置。5. 常見報錯排查401、local proxy failed 與 reading choices 怎么解Agent 開發(fā)入門階段報錯比概念更勸退。下面這幾個是我和身邊人最常遇到的對照著排查能省不少時間。401 Unauthorized最常見的原因是 Key 沒讀到。先確認.env文件在項目根目錄且load_dotenv()在OpenAI()之前調(diào)用。然后打印一下os.getenv(TAOTOKEN_API_KEY)看是不是 None。如果 Key 讀到了還報 401檢查 Key 有沒有多余空格或者是不是已經(jīng)失效。還有一種情況Base URL 寫成了https://taotoken.net/api/帶尾斜杠某些 SDK 會拼出雙斜杠導致鑒權(quán)失敗去掉尾斜杠即可。local proxy failed / connection error這個報錯通常出現(xiàn)在網(wǎng)絡層。先確認你的 Base URL 是https://taotoken.net/api不要寫成其他地址。然后在終端里用 curl 直接測一下curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5-20250929,messages:[{role:user,content:hi}]}如果 curl 通而 Python 不通那是 SDK 或環(huán)境變量的問題如果 curl 也不通檢查本機網(wǎng)絡設(shè)置。注意不要在任何配置里寫代理地址Agent 項目里混入代理配置會讓排查變得非?；靵y。reading choices 報錯 / choices 為空這個報錯說明請求發(fā)出去了但返回結(jié)構(gòu)里沒有choices。常見原因有三個。一是 Model ID 寫錯了比如把claude-sonnet-4-5-20250929拼成了別的服務端返回錯誤信息而不是正常補全。二是請求體里messages格式不對比如 role 寫成了assistant但 content 是空。三是觸發(fā)了內(nèi)容過濾返回了一個沒有 choices 的結(jié)構(gòu)。排查方法把response整個打印出來看response.error里有沒有信息。OAuth 相關(guān)報錯如果你在 Claude Code 或類似工具里看到 OAuth 報錯通常是因為工具嘗試用賬號登錄而不是 API Key。在 Agent 代碼里我們用的是 API Key 模式不會走 OAuth。如果你在配置 Claude Code 時遇到檢查它的 settings 里是不是把認證方式設(shè)成了 API KeyBase URL 填https://taotoken.net/apiKey 填你創(chuàng)建的 KeyModel ID 填對應模型。工具調(diào)用參數(shù)解析失敗如果json.loads(tool_call.function.arguments)報錯說明模型返回的參數(shù)不是合法 JSON。這通常是因為工具描述里的 parameters schema 寫得不嚴謹。檢查required字段和properties是否對應類型是否寫對。另外有些模型在參數(shù)里會帶注釋導致 JSON 解析失敗可以在解析前做一次清洗。循環(huán)不退出如果 Agent 一直調(diào)工具不返回最終回答先看max_turns是不是設(shè)太大了。然后檢查工具結(jié)果是不是讓模型誤以為任務沒完成。比如時間工具返回了結(jié)果但模型覺得還需要再確認一次。可以在 system prompt 里加一句“拿到工具結(jié)果后如果信息足夠直接給出最終回答”。6. 把概念變成手感下一步用統(tǒng)一 Key 繼續(xù)練跑通最小示例之后你對 Agent 開發(fā)入門的十個核心概念已經(jīng)有了手感。接下來最有效的練習是每次只改一個變量觀察行為變化。比如把工具描述改模糊看模型選錯工具把max_turns改成 1看循環(huán)怎么被截斷把 messages 清空看記憶怎么丟失。這種對照實驗比讀十篇文章都管用。如果你想把模型調(diào)用通道固定下來繼續(xù)用 TaoToken 的 API 就行Base URL 還是https://taotoken.net/apiKey 在 https://taotoken.net/api-keys 創(chuàng)建。想直接對話驗證模型行為可以打開 https://taotoken.net/model-chat 試幾句。如果你打算長期寫 Agent、跑編碼類任務可以看看 Coding Planhttps://taotoken.net/coding-plan 它更適合高頻調(diào)用場景。接入文檔在 https://taotoken.net/doc 配置細節(jié)都在里面。最后留一個練習給最小 Agent 加一個“寫文件”工具但要求它在調(diào)用前先輸出一句確認語。觀察模型會不會遵守這個約束如果不遵守你打算在哪一層攔截。這個練習會把你對安全與對齊的理解從概念推到代碼。 做 Agent 開發(fā)入門必懂的 10 個 Agent 核心概念：用 TaoToken 統(tǒng)一 Key 跑通第一個 Agent 示例
1. 從“會聊天”到“會干活”Agent 開發(fā)入門到底在學什么很多人第一次接觸 Agent 開發(fā)腦子里其實只有一個模糊印象不就是讓大模型自己調(diào)工具、自己干活嗎但真動手寫的時候問題立刻冒出來——它為什么知道該調(diào)哪個工具它怎么記住上一輪說過的話任務拆到一半卡住了怎么辦這些疑問背后其實對應的是 Agent 的十個核心概念。把這十個概念串起來你才算真正跨過了 Agent 開發(fā)入門的門檻。這篇內(nèi)容聚焦一件事把抽象概念落到可運行的最小 Agent 示例上。我會用統(tǒng)一的 Key 和 API 通道在本地跑通一個能規(guī)劃、能調(diào)工具、能記住上下文的 Agent然后逐項檢查每個概念是否真的生效。你不需要先啃完論文跟著配置和代碼走一遍概念自然就對應上了。適合誰看如果你已經(jīng)會調(diào)用大模型 API但沒寫過 Agent 循環(huán)或者用過 Claude Code 這類工具卻說不清它內(nèi)部怎么“思考”再或者想自己搭一個能查天氣、能讀寫文件的小助手這篇就是為你準備的。核心檢索詞就三個Agent、開發(fā)、核心概念——我們邊跑邊理解。先明確一個前提Agent 不是某個具體框架而是一種運行模式。它的最小骨架就是“感知 → 思考 → 行動 → 觀察”的循環(huán)。你后面看到的所有高級能力規(guī)劃、記憶、多 Agent 協(xié)作都是在這個循環(huán)上疊加出來的。所以第一步我們先把循環(huán)跑起來再談其他。2. 用 TaoToken 統(tǒng)一 Key 打通 Agent 的模型調(diào)用通道寫 Agent 最煩的一件事是模型調(diào)用通道不統(tǒng)一。今天試這個模型明天換那個接口Key 散落在各個環(huán)境變量里調(diào)試的時候光找配置就耗掉一半精力。我的做法是用一個統(tǒng)一的 API 通道把模型調(diào)用固定下來Agent 代碼里只認一個 Base URL 和一個 Key換模型只改一個 Model ID。這里我用 TaoToken 來做這件事。它的 API 地址是 https://taotoken.net/api兼容常見的 OpenAI 風格調(diào)用方式所以你在 Agent 代碼里用 openai 這個 SDK 就能直接連。對 Agent 開發(fā)入門來說這一點很關(guān)鍵——你不需要為每個模型寫一套適配層統(tǒng)一通道能讓你的循環(huán)邏輯保持干凈。先拿 Key。打開 https://taotoken.net/api-keys 登錄后創(chuàng)建一個 API Key復制出來。注意這個 Key 只顯示一次先存到安全的地方。然后我們把它寫進環(huán)境變量不要硬編碼在代碼里。在項目根目錄建一個.env文件TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用 Python裝兩個包pip install openai python-dotenv然后在代碼里這樣初始化客戶端import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) MODEL_ID claude-sonnet-4-5-20250929 # 按需替換這里有個細節(jié)Base URL 結(jié)尾不要帶/v1SDK 會自己拼路徑。如果你寫成https://taotoken.net/api/v1請求會變成/api/v1/v1/chat/completions直接 404。這個坑我踩過排查了半天。統(tǒng)一通道的好處在你寫 Agent 循環(huán)時會特別明顯。因為 Agent 一次任務可能要調(diào)用模型十幾次每次的請求格式都一樣只是消息歷史在變。如果通道不統(tǒng)一你會在不同模型的參數(shù)差異上浪費大量時間?，F(xiàn)在你只需要關(guān)心消息怎么組織、工具怎么描述、循環(huán)怎么退出。另外提醒一句Key 不要提交到 Git。把.env加進.gitignore團隊協(xié)作時用環(huán)境變量注入。Agent 項目里經(jīng)常會有多個工具和子進程Key 泄露的風險比普通腳本高這點要養(yǎng)成習慣。3. 可復制的 Agent 最小配置Base URL、Key 與 Model ID 三件套概念要落地得先有一個能跑的最小 Agent。我們不追求功能多只追求把核心循環(huán)、工具調(diào)用、記憶這三件事跑通。下面這份配置你可以直接復制改掉 Key 就能用。先看目錄結(jié)構(gòu)mini-agent/ ├── .env ├── agent.py └── tools.py.env就是上一步那兩行。tools.py里定義兩個最簡單的工具一個查時間一個算加法。工具描述要寫清楚因為模型靠描述決定調(diào)哪個。# tools.py import datetime def get_current_time(city: str) - str: 獲取指定城市的當前時間。當用戶詢問時間相關(guān)問題時使用。 now datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) return f{city} 當前時間{now} def add_numbers(a: float, b: float) - str: 計算兩個數(shù)字的和。當用戶需要做加法運算時使用。 return f{a} {a b} TOOL_MAP { get_current_time: get_current_time, add_numbers: add_numbers, } TOOLS_SCHEMA [ { type: function, function: { name: get_current_time, description: 獲取指定城市的當前時間。當用戶詢問時間相關(guān)問題時使用。, parameters: { type: object, properties: { city: {type: string, description: 城市名稱} }, required: [city], }, }, }, { type: function, function: { name: add_numbers, description: 計算兩個數(shù)字的和。當用戶需要做加法運算時使用。, parameters: { type: object, properties: { a: {type: number, description: 第一個數(shù)字}, b: {type: number, description: 第二個數(shù)字}, }, required: [a, b], }, }, }, ]注意工具描述里的“當用戶……時使用”。這不是寫給人看的注釋是寫給模型看的觸發(fā)條件。描述越具體模型選錯工具的概率越低。我試過把描述寫成“處理數(shù)據(jù)”結(jié)果模型在需要算加法時去調(diào)了時間工具因為它覺得“處理”也能涵蓋。然后是主循環(huán)agent.py# agent.py import json import os from dotenv import load_dotenv from openai import OpenAI from tools import TOOL_MAP, TOOLS_SCHEMA load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) MODEL_ID claude-sonnet-4-5-20250929 def run_agent(user_input: str, max_turns: int 5): messages [ {role: system, content: 你是一個會使用工具的助手。需要時調(diào)用工具不要憑空猜測。}, {role: user, content: user_input}, ] for turn in range(max_turns): response client.chat.completions.create( modelMODEL_ID, messagesmessages, toolsTOOLS_SCHEMA, tool_choiceauto, ) msg response.choices[0].message messages.append(msg) if not msg.tool_calls: print(f[最終回答] {msg.content}) return msg.content for tool_call in msg.tool_calls: name tool_call.function.name args json.loads(tool_call.function.arguments) print(f[調(diào)用工具] {name} 參數(shù){args}) result TOOL_MAP[name](**args) print(f[工具結(jié)果] {result}) messages.append({ role: tool, tool_call_id: tool_call.id, content: str(result), }) print([警告] 達到最大輪次強制結(jié)束) return None if __name__ __main__: run_agent(現(xiàn)在上海幾點順便幫我算一下 128 加 256 等于多少)這份配置里Base URL、Key、Model ID 三件套齊全。你把它保存下來python agent.py就能跑。跑通之后我們再逐項驗證概念。4. 跑通第一個 Agent 并逐項驗證十個核心概念是否生效現(xiàn)在運行python agent.py你會看到類似這樣的輸出[調(diào)用工具] get_current_time 參數(shù){city: 上海} [工具結(jié)果] 上海 當前時間2026-01-15 14:32:07 [調(diào)用工具] add_numbers 參數(shù){a: 128, b: 256} [工具結(jié)果] 128 256 384 [最終回答] 上海現(xiàn)在是 2026-01-15 14:32:07128 加 256 等于 384。一次任務里模型先調(diào)時間工具再調(diào)加法工具最后匯總回答。這個過程里十個核心概念其實都在悄悄起作用。我們逐項對照。核心循環(huán)Perceive 是用戶輸入Think 是模型決定調(diào)哪個工具Act 是執(zhí)行工具Observe 是工具結(jié)果回填到 messages。循環(huán)在for turn in range(max_turns)里轉(zhuǎn)了兩圈才結(jié)束。你可以把max_turns改成 1會看到它只調(diào)一個工具就被強制結(jié)束——這就是循環(huán)邊界的作用。工具調(diào)用模型輸出的tool_calls就是 Function Calling。它自己不執(zhí)行只是表達“我要調(diào) get_current_time參數(shù)是上海”。真正執(zhí)行的是TOOL_MAP[name](**args)。MCP 在這個最小例子里沒出現(xiàn)但你可以理解為如果工具變多就需要一個協(xié)議來管理工具從哪來、怎么連那就是 MCP 要解決的問題。規(guī)劃與任務分解用戶一句話里有兩個需求模型自動拆成兩步先時間后加法。它沒有一次性把兩個工具都調(diào)了而是按順序來。這就是最樸素的規(guī)劃。你可以試著問“先算 11再告訴我北京幾點最后把兩個結(jié)果拼起來”觀察它怎么排順序。記憶系統(tǒng)messages列表就是短期記憶。工具結(jié)果被 append 進去模型下一輪能看到。如果你把messages清空再問同樣的問題它就不知道之前算過什么。長期記憶需要你額外寫文件比如把用戶偏好存到MEMORY.md下次啟動時讀進來。上下文窗口管理這個例子里消息很短看不出壓力。但如果你把max_turns調(diào)到 20再讓它反復讀大文件就會遇到上下文超限。策略是按需加載——只把相關(guān)工具結(jié)果放進 messages不要把所有歷史都塞進去。ReAct 范式模型在調(diào)工具前其實內(nèi)部有 Thought只是這個例子里沒顯式打印。你可以在 system prompt 里加一句“每次調(diào)用工具前先用一句話說明你的理由”然后打印msg.content就能看到它的推理過程。多 Agent 協(xié)作最小例子里只有一個 Agent。要驗證多 Agent你可以起兩個進程一個負責查時間一個負責算數(shù)用主進程調(diào)度。但入門階段先不用急單 Agent 跑順了再擴展。錯誤處理把add_numbers的參數(shù)故意傳成字符串看模型怎么反應。它可能會重試也可能直接報錯。你可以在工具函數(shù)里加 try/except返回錯誤信息給模型讓它自己糾正。安全與對齊這個例子里工具都是只讀的沒有風險。如果你加一個“刪除文件”工具就應該在描述里寫“調(diào)用前必須確認”并在代碼里加確認邏輯。四層防御里人類確認是最后一道。編排框架選型現(xiàn)在你是用原生 SDK 手寫循環(huán)。等任務復雜了可以考慮 LangGraph 這類框架。但入門階段手寫一遍能讓你真正理解每個環(huán)節(jié)后面用框架時才知道它在幫你做什么。跑完這一遍十個概念就不再是名詞而是你代碼里能指認出來的具體位置。5. 常見報錯排查401、local proxy failed 與 reading choices 怎么解Agent 開發(fā)入門階段報錯比概念更勸退。下面這幾個是我和身邊人最常遇到的對照著排查能省不少時間。401 Unauthorized最常見的原因是 Key 沒讀到。先確認.env文件在項目根目錄且load_dotenv()在OpenAI()之前調(diào)用。然后打印一下os.getenv(TAOTOKEN_API_KEY)看是不是 None。如果 Key 讀到了還報 401檢查 Key 有沒有多余空格或者是不是已經(jīng)失效。還有一種情況Base URL 寫成了https://taotoken.net/api/帶尾斜杠某些 SDK 會拼出雙斜杠導致鑒權(quán)失敗去掉尾斜杠即可。local proxy failed / connection error這個報錯通常出現(xiàn)在網(wǎng)絡層。先確認你的 Base URL 是https://taotoken.net/api不要寫成其他地址。然后在終端里用 curl 直接測一下curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5-20250929,messages:[{role:user,content:hi}]}如果 curl 通而 Python 不通那是 SDK 或環(huán)境變量的問題如果 curl 也不通檢查本機網(wǎng)絡設(shè)置。注意不要在任何配置里寫代理地址Agent 項目里混入代理配置會讓排查變得非?；靵y。reading choices 報錯 / choices 為空這個報錯說明請求發(fā)出去了但返回結(jié)構(gòu)里沒有choices。常見原因有三個。一是 Model ID 寫錯了比如把claude-sonnet-4-5-20250929拼成了別的服務端返回錯誤信息而不是正常補全。二是請求體里messages格式不對比如 role 寫成了assistant但 content 是空。三是觸發(fā)了內(nèi)容過濾返回了一個沒有 choices 的結(jié)構(gòu)。排查方法把response整個打印出來看response.error里有沒有信息。OAuth 相關(guān)報錯如果你在 Claude Code 或類似工具里看到 OAuth 報錯通常是因為工具嘗試用賬號登錄而不是 API Key。在 Agent 代碼里我們用的是 API Key 模式不會走 OAuth。如果你在配置 Claude Code 時遇到檢查它的 settings 里是不是把認證方式設(shè)成了 API KeyBase URL 填https://taotoken.net/apiKey 填你創(chuàng)建的 KeyModel ID 填對應模型。工具調(diào)用參數(shù)解析失敗如果json.loads(tool_call.function.arguments)報錯說明模型返回的參數(shù)不是合法 JSON。這通常是因為工具描述里的 parameters schema 寫得不嚴謹。檢查required字段和properties是否對應類型是否寫對。另外有些模型在參數(shù)里會帶注釋導致 JSON 解析失敗可以在解析前做一次清洗。循環(huán)不退出如果 Agent 一直調(diào)工具不返回最終回答先看max_turns是不是設(shè)太大了。然后檢查工具結(jié)果是不是讓模型誤以為任務沒完成。比如時間工具返回了結(jié)果但模型覺得還需要再確認一次。可以在 system prompt 里加一句“拿到工具結(jié)果后如果信息足夠直接給出最終回答”。6. 把概念變成手感下一步用統(tǒng)一 Key 繼續(xù)練跑通最小示例之后你對 Agent 開發(fā)入門的十個核心概念已經(jīng)有了手感。接下來最有效的練習是每次只改一個變量觀察行為變化。比如把工具描述改模糊看模型選錯工具把max_turns改成 1看循環(huán)怎么被截斷把 messages 清空看記憶怎么丟失。這種對照實驗比讀十篇文章都管用。如果你想把模型調(diào)用通道固定下來繼續(xù)用 TaoToken 的 API 就行Base URL 還是https://taotoken.net/apiKey 在 https://taotoken.net/api-keys 創(chuàng)建。想直接對話驗證模型行為可以打開 https://taotoken.net/model-chat 試幾句。如果你打算長期寫 Agent、跑編碼類任務可以看看 Coding Planhttps://taotoken.net/coding-plan 它更適合高頻調(diào)用場景。接入文檔在 https://taotoken.net/doc 配置細節(jié)都在里面。最后留一個練習給最小 Agent 加一個“寫文件”工具但要求它在調(diào)用前先輸出一句確認語。觀察模型會不會遵守這個約束如果不遵守你打算在哪一層攔截。這個練習會把你對安全與對齊的理解從概念推到代碼。