1. 为什么我建议你先跑通 Claude Messages API 再谈智能助手如果你正在搜 Claude API、智能助手、AI 应用、Messages API、Python 这几个词大概率你已经有想法了想给自己的工具、网站或者自动化脚本加一个能对话、能调工具、能流式输出的助手。但真到动手时问题往往不是“模型聪不聪明”而是“Key 怎么统一管、请求怎么发、历史怎么维护、工具调用怎么接”。我自己搭过几套类似的东西踩过的坑集中在三块一是不同模型供应商的 Key 和接口格式来回切代码里到处是 if-else二是多轮对话的历史管理写得很随意聊几轮就串味三是工具调用Tool Use第一次接的时候tool_use 和 tool_result 的配对老是对不上。这篇就按“5 步打造专属 AI 应用”的路径把 Claude Messages API 从凭证到流式输出、再到工具调用完整走一遍代码可以直接复制。适合谁看有 Python 基础、想快速在本地跑通一个专属智能助手的开发者已经用过 OpenAI 接口、想迁移到 Claude Messages API 的人以及需要统一 Key 通道、不想在多个控制台之间反复横跳的团队。读完你能得到一个可运行的命令行助手支持自定义系统提示、多轮上下文、流式输出和工具调用。2. TaoToken 统一 Key 接入把凭证和通道先理顺在写业务代码之前先把“钥匙”和“门”定下来。Claude Messages API 的请求结构本身不复杂但如果你同时还要接别的模型或者团队里多人共用Key 散落在各个环境变量里就会很乱。我现在的做法是走 TaoToken 的统一 Key 通道一个 Key 管多个模型入口代码里只认一个 base_url 和一个 api_key切换模型只改 model 字段。具体来说TaoToken 提供统一的 API 通道Claude 系列模型可以通过兼容 Messages API 的方式调用。你需要在控制台创建一个 API Key然后把它放进环境变量不要硬编码进代码。地址方面官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM。创建 Key 的页面在 console 里路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理页是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。这里有个关键点Claude 官方 SDK 默认打的是 Anthropic 的域名我们要让它打到统一通道就得在初始化客户端时指定 base_url。这一步很多人会漏结果请求发出去了但一直 401 或者连不上。下面第 3 步的配置骨架里会把这个写清楚。注意Key 只放环境变量或密钥管理服务别写进 settings.json 提交到 Git。我见过有人把 Key 写进配置文件推到公开仓库几分钟就被扫走刷额度。3. 可复制配置settings.json 与 config.toml 骨架在写 Python 之前先把配置文件骨架搭好。这样做的目的是把“模型参数”和“业务逻辑”解耦后面换模型、调温度、改系统提示都不用动主代码。我用两个文件settings.json 放运行时参数config.toml 放项目级配置。先看 settings.json放在项目根目录{ provider: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, timeout_seconds: 60, max_retries: 3 }, model: { name: claude-3-5-sonnet-latest, max_tokens: 1024, temperature: 0.7, stream: true }, assistant: { system_prompt: 你是一位资深技术面试官擅长后端与分布式系统。根据对话历史逐步深入提问语气专业但友好。, history_limit: 20 } }再看 config.toml放一些不常变的项目信息[project] name claude-assistant version 0.1.0 language python [logging] level INFO file logs/assistant.log [tools] enabled [get_current_date, calc_expression]这两个文件的分工是settings.json 里的 api_key_env 指向环境变量名而不是 Key 本身这样配置可以安全地进版本库。base_url 指向统一通道model.name 用 Claude 的模型标识。history_limit 控制保留多少轮历史防止 token 无限膨胀。环境变量这样设Linux/macOSexport TAOTOKEN_API_KEY你的KeyWindows PowerShell$env:TAOTOKEN_API_KEY你的Key配置骨架就位后主代码只需要读这两个文件不用关心 Key 从哪来、模型叫什么。4. 5 步实现对话、流式输出与工具调用这一步是核心按 5 个动作推进装依赖、初始化客户端、跑通单轮、加多轮与流式、接工具调用。每一步都有可验证的结果。4.1 第一步安装依赖并验证环境pip install anthropic python -c import anthropic; print(anthropic.__version__)能打印出版本号就说明 SDK 装好了。这里用的是 Anthropic 官方 Python SDK它支持自定义 base_url正好对接统一通道。4.2 第二步初始化客户端并读取配置import json import os import anthropic def load_settings(pathsettings.json): with open(path, r, encodingutf-8) as f: return json.load(f) settings load_settings() provider settings[provider] api_key os.environ.get(provider[api_key_env]) if not api_key: raise SystemExit(f请设置环境变量 {provider[api_key_env]}) client anthropic.Anthropic( api_keyapi_key, base_urlprovider[base_url], timeoutprovider[timeout_seconds], max_retriesprovider[max_retries], )关键在 base_url 这一行它把请求指向统一通道。max_retries 设 3 次网络抖动时自动重试省得自己写退避逻辑。4.3 第三步跑通单轮请求先别急着上多轮单轮通了再说model_cfg settings[model] resp client.messages.create( modelmodel_cfg[name], max_tokensmodel_cfg[max_tokens], temperaturemodel_cfg[temperature], systemsettings[assistant][system_prompt], messages[{role: user, content: 用一句话解释什么是分布式锁。}], ) print(resp.content[0].text)如果这里能打印出回答说明 Key、base_url、模型名三者都对上了。如果报 401先查 Key报 404查模型名报连接超时查 base_url 有没有写错。4.4 第四步加多轮历史与流式输出多轮的本质就是把历史消息追加进 messages 列表流式则是用 client.messages.stream()def chat_loop(): messages [] limit settings[assistant][history_limit] print(助手已启动输入 exit 退出clear 清空历史。) while True: try: user_input input(你: ).strip() except (KeyboardInterrupt, EOFError): break if not user_input: continue if user_input.lower() exit: break if user_input.lower() clear: messages.clear() print(历史已清空。) continue messages.append({role: user, content: user_input}) # 控制历史长度保留最近 limit 条 if len(messages) limit: messages messages[-limit:] print(助手: , end, flushTrue) reply try: with client.messages.stream( modelmodel_cfg[name], max_tokensmodel_cfg[max_tokens], temperaturemodel_cfg[temperature], systemsettings[assistant][system_prompt], messagesmessages, ) as stream: for delta in stream.text_stream: print(delta, end, flushTrue) reply delta except anthropic.APIError as e: print(f\nAPI 错误: {e}) messages.pop() continue print() messages.append({role: assistant, content: reply})实测下来流式输出对交互体验提升很明显尤其是长回答时用户不会干等。历史裁剪那几行别省聊久了 token 消耗会失控。4.5 第五步接入工具调用工具调用是让助手“能做事”的关键。先定义工具 schemaimport datetime tools [ { name: get_current_date, description: 获取当前日期返回 YYYY-MM-DD 格式。, input_schema: {type: object, properties: {}, required: []}, } ] def run_tool(name): if name get_current_date: return datetime.date.today().isoformat() raise ValueError(f未知工具: {name})然后在请求里带上 tools并处理 tool_use 块resp client.messages.create( modelmodel_cfg[name], max_tokensmodel_cfg[max_tokens], systemsettings[assistant][system_prompt], toolstools, messagesmessages, ) if resp.stop_reason tool_use: tool_results [] for block in resp.content: if block.type tool_use: result run_tool(block.name) tool_results.append({ type: tool_result, tool_use_id: block.id, content: result, }) messages.append({role: assistant, content: resp.content}) messages.append({role: user, content: tool_results}) # 再次请求拿到最终文本回复 final client.messages.create( modelmodel_cfg[name], max_tokensmodel_cfg[max_tokens], systemsettings[assistant][system_prompt], toolstools, messagesmessages, ) print(final.content[0].text)这里最容易错的是 tool_use_id 的配对tool_result 里的 tool_use_id 必须等于对应 tool_use 块的 id否则模型会报“找不到工具结果”。另外 assistant 的 content 要原样塞回 messages不能只塞文本。5. 验证请求与成功结果怎么确认真的跑通了跑通的标准不是“没报错”而是几个可观察的信号。第一单轮请求返回的 resp.content[0].text 有实际内容不是空字符串。第二流式输出时字符是逐个出现的不是一次性刷出来。第三工具调用时 resp.stop_reason 等于 tool_use且第二轮请求能拿到基于工具结果的最终回答。你可以用这个测试序列验证你: 今天几号 助手: 触发 get_current_date返回日期后组织语言回答 你: 出一道关于分布式事务的面试题。 助手: 流式输出题目 你: clear 历史已清空。如果工具调用那步卡住先打印 resp.stop_reason 和 resp.content 的类型确认 tool_use 块真的出现了。如果流式没生效检查是不是用了 create 而不是 stream。如果多轮串味检查 messages 里 role 是否严格交替、有没有把 assistant 回复漏加。6. 本篇常见错排查401、404、tool_use 不触发怎么办401 未授权九成是 Key 没读到。先确认环境变量名和 settings.json 里的 api_key_env 一致再确认 Key 没有多余空格。如果用的是统一通道确认 base_url 写的是 https://taotoken.net/api 别多加路径。404 模型不存在模型名写错了。Claude 的模型标识会更新用控制台或文档里列出的当前可用名称。别凭记忆写旧版本号。连接超时base_url 拼错或者网络环境有额外限制。先 curl 一下基址看能不能通。tool_use 不触发工具 description 写得太模糊模型判断不需要调用。把 description 写具体比如“获取当前日期”比“日期工具”更容易触发。另外 input_schema 要合法properties 为空对象也要写。流式中断网络波动导致。SDK 的 max_retries 能兜一部分生产环境建议在 stream 外层加 try 并记录断点。历史导致 token 超限history_limit 设小一点或者只保留最近 N 轮。长对话场景可以配合摘要压缩把早期历史总结成一段话再塞回去。排障时如果怀疑是 Key 或通道问题直接去 API Keys 页面核对https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。7. 下一步怎么走按场景选通道代码跑通之后接下来看你的使用场景。如果只是验证模型回答质量、调系统提示直接在模型对话页试最快https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。如果你要把这套助手接进长期运行的编码工具或 Agent 流程走 Coding Plan 更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。如果你在接 Claude Code 这类工具Anthropic 兼容入口在这里https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 。我自己的习惯是先用模型对话页把系统提示调满意再把提示词固化进 settings.json最后用 Coding Plan 跑长期任务。这样调参和运行分开不会互相干扰。