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