用Claude API开发应用：消息接口、系统提示词与工具调用入门

用 Claude API 开发应用，核心只有三步：申请并保管好密钥、用官方 SDK 调用消息接口发送对话、按需要加上系统提示词和工具调用。对有一点编程基础的开发者来说，半小时就能跑通一个最小示例。本文讲的是 Claude API 接入的基本流程和工程上必须注意的事项，用 Python 做示例。模型名称、参数、价格和地区可用性都会更新，代码里的模型名一律用占位符，请以官方文档的最新说明为准。

一、准备工作：账号、密钥与SDK

1. 开通接口权限。 在官方开发者平台注册账号并创建密钥，注册条件、可用地区和计费方式以官方说明为准。
2. 保管好密钥。 密钥相当于账号密码：不要写进前端代码、不要提交到代码仓库、不要发在聊天群里。推荐放进环境变量或专门的密钥管理服务。
3. 安装官方 SDK。 Python 示例：

pip install anthropic
export ANTHROPIC_API_KEY="你的密钥"   # Windows 用 setx 或系统环境变量设置

SDK 默认会读取环境变量 ANTHROPIC_API_KEY，所以代码里不需要出现密钥本身。

二、最小示例：messages接口

import anthropic

client = anthropic.Anthropic()  # 自动读取环境变量中的密钥

message = client.messages.create(
    model="<模型名，以官方文档为准>",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "用三句话解释什么是响应式网页设计"}
    ],
)

print(message.content[0].text)

几个关键点：

• model：要使用的模型，不同模型在能力、速度和成本上不同，先用能力较强的模型调试，再评估是否换成更轻量的。
• max_tokens：本次回答最多生成多少 token，必须设置。它同时也是控制成本的手段之一。
• messages：对话内容的列表，每条包含 role（user 或 assistant）和 content。
• 返回的 content 是一个内容块列表，普通文本回答取列表中首个块的 text 即可。

三、系统提示词：给模型设定角色和规则

系统提示词通过 system 参数传入，用来设定角色、语气、边界和输出格式，和用户消息分开：

message = client.messages.create(
    model="<模型名，以官方文档为准>",
    max_tokens=1024,
    system=(
        "你是一家网站建设公司的售前助手。"
        "只回答与建站、小程序、软件开发相关的问题；"
        "不确定的价格和工期，请回答“需要根据需求评估”，不要编造。"
        "回答控制在 200 字以内。"
    ),
    messages=[{"role": "user", "content": "做一个企业官网大概要多久？"}],
)

写系统提示词的建议：规则写具体，不要写“请友好专业”这类空话；把“不知道怎么办”的处理方式写清楚；输出格式（比如固定的 JSON 字段）要明确。

四、多轮对话：自己维护历史

接口本身不会替你保存对话历史。要实现多轮对话，需要每次把完整的历史消息一起发送，user 和 assistant 交替出现：

history = []

def chat(user_text):
    history.append({"role": "user", "content": user_text})
    reply = client.messages.create(
        model="<模型名，以官方文档为准>",
        max_tokens=1024,
        messages=history,
    )
    answer = reply.content[0].text
    history.append({"role": "assistant", "content": answer})
    return answer

历史越长，每次请求消耗的 token 越多，成本和延迟都会上升。实际项目里通常要做历史截断，或者把早期对话压缩成摘要后再带上。

五、工具调用：让模型使用你的函数

工具调用（Tool Use）让模型在需要时“请求”你的程序去执行某个函数，比如查订单、查库存、查天气。流程要点是：模型只负责决定调用什么和传什么参数，真正执行函数的是你的代码。

1. 定义工具。 在请求里通过 tools 参数声明工具的名称、说明和参数结构（JSON Schema）：

tools = [{
    "name": "get_order_status",
    "description": "根据订单号查询订单状态",
    "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string", "description": "订单号"}},
        "required": ["order_id"],
    },
}]

2. 模型请求调用。 当模型判断需要用工具时，返回的内容里会出现类型为 tool_use 的内容块，包含工具名、参数和一个调用 id，同时结束原因（stop_reason）表示是因为要使用工具而停止。
3. 你的代码执行并回传结果。 解析参数，调用你自己的函数，然后把结果放进新的 user 消息中，以 tool_result 内容块的形式带上对应的调用 id，再次请求。
4. 模型给出最终回答。 模型根据工具结果组织最终的自然语言回复。

具体的字段名和消息格式以官方文档为准，建议直接参考官方的工具调用示例，不要凭印象手写。几条工程建议：

• 工具的 description 要写清楚什么时候该用、参数是什么含义，写得越清楚，模型调用越准确。
• 对模型传来的参数一律做校验，不要直接拼进 SQL 或系统命令。
• 涉及写操作（下单、退款、删除）的工具，要加权限判断和人工确认，不要让模型自行决定。

六、流式输出：让用户更早看到回答

模型生成长回答需要一段时间，如果等全部生成完再返回，用户会感觉“卡住了”。官方 SDK 支持流式输出，边生成边返回：

with client.messages.stream(
    model="<模型名，以官方文档为准>",
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一段 200 字的产品介绍"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

做网页聊天界面时，服务端把流式内容通过 SSE 或 WebSocket 转发给前端，用户体验会明显更好。注意流式场景下的异常处理：连接中途断开时，要决定是丢弃已生成的部分，还是保留并提示用户重试。具体的事件类型和用法以官方文档为准。

七、调试与测试建议

• 固定一组测试用例。 把典型问题和期望要点整理成清单，每次修改系统提示词或换模型后都跑一遍，避免“改好一个、坏了三个”。
• 记录每次的输入输出。 出现异常回答时，才能复现和定位是提示词、历史还是工具返回的数据有问题。
• 对输出做程序化校验。 要求返回 JSON 时，用代码解析并校验字段，失败就重试或降级，不要假设模型每次都格式正确。
• 准备兜底方案。 接口超时或限流时，给用户明确的提示或转人工，不要让页面一直转圈。

八、生产环境必须考虑的工程问题

1. 密钥安全。 所有调用都放在你自己的服务端，前端只和你的服务端通信。绝不能把密钥放进网页、小程序或 App 的安装包里，否则会被人提取盗用。

2. 成本控制。 接口按输入和输出的 token 用量计费，具体价格以官方为准。常用手段：限制 max_tokens；截断过长的历史；按任务难度选择不同模型；对重复问题做缓存；给每个用户设置调用额度。

3. 超时与重试。 网络波动、限流都会导致失败。官方 SDK 自带一定的重试机制，也可以在创建客户端时调整：

client = anthropic.Anthropic(max_retries=3, timeout=30.0)

对限流和服务端错误做指数退避重试，对参数错误则不要重试。具体的异常类型和错误码以官方文档为准。

4. 日志与审计。 记录请求的摘要、耗时、用量和错误，便于排查问题和核算成本。但日志里不要保存用户的敏感信息和密钥。

5. 内容与合规。 面向公众的应用，需要考虑用户输入的合规审核、生成内容的标识和数据保护要求，按所在地区和行业规定处理。

常见问题

必须用 Python 吗？ 不必。官方提供多种语言的 SDK，也可以直接用 HTTP 请求调用，具体支持范围以官方文档为准。

Claude API 和网页版是同一套计费吗？ 不是，接口按用量计费，网页版按订阅套餐，规则以官方说明为准。

可以让模型直接操作我的数据库吗？ 不建议。正确做法是通过工具调用，让模型请求一个受你控制的函数，由你的代码做权限校验和参数检查后再执行。

回答格式不稳定怎么办？ 在系统提示词里明确要求格式，必要时给出示例，并在代码里对返回内容做校验，不合格就重试。

如果你的公司想做智能客服、知识库问答、内部助手这类大模型应用开发，广州万户网络提供软件与 AI 应用开发服务，可以先说明业务场景和数据情况，我们帮你评估接入方案，咨询电话：13535321113。更多开发服务见 软件开发 页面。完成 Claude API 接入只是起点，真正决定应用好不好用的，是工具设计、权限控制和成本管理这些工程细节。