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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （这个不加 UTM）。创建 Key 的页面在 console 里，路径是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，API Keys 管理页是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。
这里有个关键点：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/macOS）：
export TAOTOKEN_API_KEY="你的Key"Windows 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(path="settings.json"): with open(path, "r", encoding="utf-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_key=api_key, base_url=provider["base_url"], timeout=provider["timeout_seconds"], max_retries=provider["max_retries"], )关键在 base_url 这一行，它把请求指向统一通道。max_retries 设 3 次，网络抖动时自动重试，省得自己写退避逻辑。
4.3 第三步：跑通单轮请求
先别急着上多轮，单轮通了再说：
model_cfg = settings["model"] resp = client.messages.create( model=model_cfg["name"], max_tokens=model_cfg["max_tokens"], temperature=model_cfg["temperature"], system=settings["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="", flush=True) reply = "" try: with client.messages.stream( model=model_cfg["name"], max_tokens=model_cfg["max_tokens"], temperature=model_cfg["temperature"], system=settings["assistant"]["system_prompt"], messages=messages, ) as stream: for delta in stream.text_stream: print(delta, end="", flush=True) reply += delta except anthropic.APIError as e: print(f"\nAPI 错误: {e}") messages.pop() continue print() messages.append({"role": "assistant", "content": reply})实测下来，流式输出对交互体验提升很明显，尤其是长回答时用户不会干等。历史裁剪那几行别省，聊久了 token 消耗会失控。
4.5 第五步：接入工具调用
工具调用是让助手“能做事”的关键。先定义工具 schema：
import 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( model=model_cfg["name"], max_tokens=model_cfg["max_tokens"], system=settings["assistant"]["system_prompt"], tools=tools, messages=messages, ) 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( model=model_cfg["name"], max_tokens=model_cfg["max_tokens"], system=settings["assistant"]["system_prompt"], tools=tools, messages=messages, ) 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_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。接入细节和参数说明看文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
7. 下一步怎么走：按场景选通道
代码跑通之后，接下来看你的使用场景。如果只是验证模型回答质量、调系统提示，直接在模型对话页试最快：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 。如果你要把这套助手接进长期运行的编码工具或 Agent 流程，走 Coding Plan 更合适：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。如果你在接 Claude Code 这类工具，Anthropic 兼容入口在这里：https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite 。
我自己的习惯是：先用模型对话页把系统提示调满意，再把提示词固化进 settings.json，最后用 Coding Plan 跑长期任务。这样调参和运行分开，不会互相干扰。
