1. 從一次“寫個(gè)網(wǎng)頁”的任務(wù)說起Trae-Agent 是一個(gè)用自然語言驅(qū)動(dòng)工具完成軟件工程任務(wù)的 Agent它最值得研究的地方不是“能寫代碼”而是它把 LLM 的決策過程拆成了可觀察、可復(fù)現(xiàn)的執(zhí)行鏈路。你給它一句“寫一個(gè)最簡(jiǎn)單的網(wǎng)頁”它不會(huì)直接吐 HTML而是先思考、再建文件、再驗(yàn)證、最后報(bào)告完成。這套鏈路里有兩個(gè)關(guān)鍵詞sequential_thinking 和 ReAct。前者是它的“記事本”負(fù)責(zé)把復(fù)雜任務(wù)拆成有序的思考步驟后者是它的“行動(dòng)循環(huán)”負(fù)責(zé)讓 LLM 在思考與工具調(diào)用之間反復(fù)迭代直到任務(wù)收斂。如果你正在本地折騰 Agent 項(xiàng)目或者想把 Trae-Agent 接到自己的模型通道上跑通一次完整工具調(diào)用這篇文章會(huì)帶你從執(zhí)行思路拆到配置骨架。我會(huì)先講清楚 sequential_thinking 和 ReAct 在 Trae-Agent 里各自扮演什么角色再給出 TaoToken 統(tǒng)一 Key/API 通道在 config.toml 與 settings.json 中的可復(fù)制配置最后用一次真實(shí)的工具調(diào)用鏈路驗(yàn)證整個(gè)流程。適合已經(jīng)了解 LLM 基礎(chǔ)調(diào)用、想深入 Agent 調(diào)度機(jī)制的開發(fā)者也適合想復(fù)現(xiàn) Trae-Agent 執(zhí)行軌跡的工程同學(xué)。2. Trae-Agent 的執(zhí)行骨架LLM 決策 工具執(zhí)行 軌跡記錄Trae-Agent 的核心結(jié)構(gòu)可以用一句話概括LLM 負(fù)責(zé)決策工具負(fù)責(zé)執(zhí)行軌跡負(fù)責(zé)記錄。它采用的是一個(gè)循環(huán)結(jié)構(gòu)每一輪都讓 LLM 根據(jù)當(dāng)前消息歷史選擇下一步動(dòng)作。這個(gè)動(dòng)作可能是調(diào)用 sequential_thinking 繼續(xù)思考可能是調(diào)用 edit_tool 修改文件可能是調(diào)用 bash 執(zhí)行命令也可能是調(diào)用 task_done 宣布任務(wù)完成。從執(zhí)行軌跡看一個(gè)“寫網(wǎng)頁”的任務(wù)大約經(jīng)歷 6 步第 1 步用 sequential_thinking 做規(guī)劃第 2 步用 str_replace_based_edit_tool 創(chuàng)建 HTML 文件第 3 步用同一個(gè)工具查看文件內(nèi)容做驗(yàn)證第 4 步用 bash 啟動(dòng)本地服務(wù)并 curl 測(cè)試第 5 步調(diào)用 task_done 結(jié)束。整個(gè)過程中LLM 并不是一次性輸出所有步驟而是每執(zhí)行完一個(gè)工具就把結(jié)果追加回消息歷史再進(jìn)入下一輪決策。這里的關(guān)鍵點(diǎn)是LLM 本身是無狀態(tài)的它不會(huì)“記住”上一輪做了什么所有上下文都靠消息歷史攜帶。sequential_thinking 工具的作用就是把這些上下文結(jié)構(gòu)化地寫進(jìn)歷史里讓 LLM 在后續(xù)輪次中能“看到自己想過什么、做到哪一步”。這也是為什么 Trae-Agent 的軌跡 JSON 里奇數(shù)步驟幾乎都是 sequential_thinking——它在強(qiáng)制 LLM 按結(jié)構(gòu)化方式思考。核心執(zhí)行偽代碼大致是這樣的async def execute_task(self) - AgentExecution: while step_number max_steps: # 1. LLM 決策 llm_response self.llm_client.chat(messages, tools) # 2. 判斷任務(wù)完成 if self.llm_indicates_task_completed(llm_response): break # 3. 工具調(diào)用 if llm_response.tool_calls: tool_results await self.tool_caller.call(tool_calls) messages.append(tool_results) # 4. 軌跡記錄 self.trajectory_recorder.record_agent_step(step) step_number 1這段循環(huán)就是 ReAct 模式在 Trae-Agent 里的落地ReasonLLM 決策→ Act工具調(diào)用→ Observe結(jié)果回填→ 再 Reason。sequential_thinking 則是 Reason 階段的結(jié)構(gòu)化載體它讓 LLM 的思考不是散落在自然語言里而是以“當(dāng)前思考步數(shù)、預(yù)計(jì)總步數(shù)、當(dāng)前思考內(nèi)容”這樣的字段被記錄下來。3. TaoToken 前置統(tǒng)一 Key 與 API 通道準(zhǔn)備在本地復(fù)現(xiàn) Trae-Agent 執(zhí)行流程之前你需要先準(zhǔn)備好模型通道。Trae-Agent 支持多種 provider但如果你想讓配置更統(tǒng)一、切換模型更方便可以用 TaoToken 作為統(tǒng)一入口。它的作用是提供一個(gè)兼容 OpenAI 風(fēng)格的 API 通道你只需要一個(gè) Key就能在 config.toml 和 settings.json 里配置不同的模型調(diào)用。先到 TaoToken 控制臺(tái)創(chuàng)建一個(gè) API Key。訪問 https://taotoken.net/api-keys 登錄后新建 Key復(fù)制保存。這個(gè) Key 后面會(huì)同時(shí)用在 Trae-Agent 的配置文件和本地驗(yàn)證腳本里。注意不要把 Key 硬編碼到會(huì)提交到 Git 的文件里建議用環(huán)境變量或本地配置文件承載。TaoToken 的 API 基礎(chǔ)地址是 https://taotoken.net/api它不加 UTM 參數(shù)直接作為 base_url 使用。模型名稱按你實(shí)際需要的填比如你想用 Claude 系列做 Agent 決策就在配置里寫對(duì)應(yīng)的模型標(biāo)識(shí)。如果你還不確定選哪個(gè)模型可以先到模型對(duì)話頁面試一下不同模型在工具調(diào)用場(chǎng)景下的表現(xiàn)再?zèng)Q定寫進(jìn)配置。提示Trae-Agent 的工具調(diào)用對(duì)模型的 function calling 能力有要求建議選支持 tool_calls 的模型否則 ReAct 循環(huán)會(huì)在第一步就卡住。4. 可復(fù)制配置config.toml 與 settings.json 骨架Trae-Agent 的配置分兩層config.toml 負(fù)責(zé) Agent 運(yùn)行時(shí)的 provider 和模型參數(shù)settings.json 負(fù)責(zé)本地工具鏈和項(xiàng)目級(jí)設(shè)置。下面給出的是可復(fù)制的骨架你只需要把 api_key 替換成自己的。先看 config.toml[llm] provider taotoken model claude-3-5-sonnet base_url https://taotoken.net/api api_key sk-your-taotoken-key max_tokens 8192 temperature 0.2 [agent] max_steps 30 enable_sequential_thinking true trajectory_output ./trajectory.json [tools] enable_edit_tool true enable_bash_tool true enable_task_done true這里幾個(gè)參數(shù)值得說明。max_steps 控制 ReAct 循環(huán)的最大輪次太小會(huì)導(dǎo)致任務(wù)沒完成就退出太大會(huì)浪費(fèi) tokenenable_sequential_thinking 打開后LLM 會(huì)被引導(dǎo)優(yōu)先調(diào)用 sequential_thinking 工具做結(jié)構(gòu)化思考trajectory_output 指定執(zhí)行軌跡的落盤路徑方便你事后分析每一步的工具調(diào)用。再看 settings.json{ project_root: ./workspace, tool_permissions: { bash: { allowed_commands: [python3, curl, ls, cat, grep, find], timeout_seconds: 30 }, edit: { allow_create: true, allow_modify: true, max_file_size_kb: 512 } }, llm_channel: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY } }settings.json 里的 api_key_env 表示從環(huán)境變量讀取 Key這樣比明文寫在文件里安全。你可以在 shell 里執(zhí)行export TAOTOKEN_API_KEYsk-your-taotoken-key兩個(gè)配置的分工是config.toml 決定“用哪個(gè)模型、跑多少步”settings.json 決定“工具能做什么、在哪個(gè)目錄做”。如果你想讓 Agent 在特定項(xiàng)目目錄下工作把 project_root 指向你的代碼倉(cāng)庫即可。注意 bash 的 allowed_commands 是白名單機(jī)制不在列表里的命令會(huì)被拒絕這是防止 Agent 執(zhí)行危險(xiǎn)操作的第一道閘。5. 驗(yàn)證請(qǐng)求跑通一次工具調(diào)用鏈路配置寫好后用一條最簡(jiǎn)單的任務(wù)驗(yàn)證整條鏈路。在終端執(zhí)行trae-cli run 寫一個(gè)最簡(jiǎn)單的網(wǎng)頁 --config ./config.toml如果配置正確你會(huì)看到 Agent 開始輸出執(zhí)行日志。它第一輪大概率會(huì)調(diào)用 sequential_thinking輸出類似“當(dāng)前思考步數(shù) 1預(yù)計(jì)總步數(shù) 5計(jì)劃創(chuàng)建 HTML 文件并驗(yàn)證”的內(nèi)容。第二輪會(huì)調(diào)用 edit_tool 創(chuàng)建 simple_page.html第三輪查看文件第四輪用 bash 啟動(dòng)本地服務(wù)并 curl 測(cè)試第五輪調(diào)用 task_done。執(zhí)行完成后檢查 trajectory.json你會(huì)看到類似這樣的精簡(jiǎn)結(jié)構(gòu){ task: 寫一個(gè)最簡(jiǎn)單的網(wǎng)頁, provider: taotoken, model: claude-3-5-sonnet, execution_summary: { total_steps: 6, tools_used: [sequentialthinking, str_replace_based_edit_tool, bash, task_done], key_actions: [ { step: 1, action: 思考規(guī)劃, tool: sequentialthinking }, { step: 2, action: 創(chuàng)建文件, tool: str_replace_based_edit_tool, file: simple_page.html }, { step: 3, action: 驗(yàn)證文件, tool: str_replace_based_edit_tool, command: view }, { step: 4, action: 測(cè)試網(wǎng)頁, tool: bash, command: python3 -m http.server 8000 curl localhost:8000/simple_page.html }, { step: 5, action: 完成任務(wù), tool: task_done } ] }, result: { status: success, output_file: simple_page.html } }看到 status 為 success說明整條 ReAct 鏈路跑通了。你可以打開生成的 simple_page.html內(nèi)容應(yīng)該是一個(gè)最基礎(chǔ)的 Hello World 頁面。這一步驗(yàn)證的不只是“模型能寫代碼”而是“模型能在工具調(diào)用循環(huán)里自主決策并收斂”。如果你想單獨(dú)驗(yàn)證 TaoToken 通道是否可用可以先用 curl 發(fā)一個(gè)最小請(qǐng)求curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-3-5-sonnet, messages: [{role: user, content: 回復(fù) ok}], max_tokens: 16 }返回里有 choices 字段就說明通道正常。這一步能幫你把“通道問題”和“Agent 邏輯問題”分開排查。6. 本篇常見錯(cuò)排查第一個(gè)常見錯(cuò)是模型不支持 tool_calls。表現(xiàn)是 Agent 第一輪就返回純文本不調(diào)用任何工具循環(huán)直接結(jié)束。排查方法是看 trajectory.json 里 tools_used 是否為空。解決方式是換一個(gè)支持 function calling 的模型或者在 config.toml 里確認(rèn)模型名稱拼寫正確。第二個(gè)常見錯(cuò)是 base_url 寫成了帶 /v1 的完整路徑。Trae-Agent 內(nèi)部會(huì)自己拼接 /v1/chat/completions如果你在 config.toml 里寫成 https://taotoken.net/api/v1最終請(qǐng)求會(huì)變成 /api/v1/v1/chat/completions直接 404。正確寫法是只寫到 https://taotoken.net/api。第三個(gè)常見錯(cuò)是 bash 工具被權(quán)限白名單攔住。表現(xiàn)是 Agent 調(diào)用 bash 后返回 permission denied然后反復(fù)重試同一條命令。檢查 settings.json 里的 allowed_commands把需要的命令加進(jìn)去。注意不要圖省事寫通配符白名單越具體越安全。第四個(gè)常見錯(cuò)是 max_steps 設(shè)得太小。復(fù)雜任務(wù)在 10 步內(nèi)完不成Agent 會(huì)在中途被強(qiáng)制退出trajectory 里 status 會(huì)是 incomplete。建議從 30 起步觀察實(shí)際用了多少步再調(diào)整。第五個(gè)常見錯(cuò)是環(huán)境變量沒生效。settings.json 里寫的是 api_key_env但你在當(dāng)前 shell 沒 exportAgent 啟動(dòng)時(shí)會(huì)報(bào) Key 為空。用 echo $TAOTOKEN_API_KEY 確認(rèn)一下或者直接在啟動(dòng)命令前加上環(huán)境變量。7. 繼續(xù)深入的方向跑通一次基礎(chǔ)鏈路后你可以試著改任務(wù)復(fù)雜度比如讓 Agent 修一個(gè)真實(shí)的小 bug觀察 sequential_thinking 的思考步數(shù)如何隨任務(wù)難度增長(zhǎng)。也可以把 trajectory.json 喂給分析腳本統(tǒng)計(jì)不同工具的使用頻率和平均步數(shù)這對(duì)理解 Agent 的決策偏好很有幫助。如果你打算長(zhǎng)期跑編碼類 Agent 任務(wù)可以關(guān)注 TaoToken 的 Coding Plan它在多輪工具調(diào)用場(chǎng)景下的通道穩(wěn)定性更適合持續(xù)使用。配置文檔在 https://taotoken.net/doc 可以查到最新的參數(shù)說明。模型對(duì)話入口在 https://taotoken.net/chat適合在寫配置前先試模型。API Key 管理在 https://taotoken.net/api-keys接入文檔在 https://taotoken.net/doc。Claude Code 相關(guān)配置可以參考 https://taotoken.net/claude-code。真正值得花時(shí)間的地方是把 sequential_thinking 的提示詞拿出來逐條讀一遍。它規(guī)定了 LLM 必須設(shè)置 total_thoughts、必須分步思考、可以在思考之間插入 bash 命令。這套約束才是 Trae-Agent 能把 ReAct 跑穩(wěn)的關(guān)鍵。你可以試著改一改提示詞里的步數(shù)下限看 Agent 的行為會(huì)怎么變——這比單純讀代碼更能理解 Agent 調(diào)度。