·SDK 与工具
Claude API 新手友好教程——获取 API key、用 Python 和 TypeScript 发出第一次 messages.create 调用、流式响应，以及接上工具使用让 Claude 调用你定义的函数。
Claude API 入门：第一次调用、流式响应与工具使用
Claude API 是你在自己产品里用上 Claude 的途径——一个客服机器人、一个代码生成器、一个文档摘要器，任何由你掌控循环的场景。好消息是它的接口很小：一个端点、每种语言一个 SDK、几个能相互组合的概念。本指南带你走一遍获取 API key、用 Python 和 TypeScript 发出第一次 messages.create 调用、流式响应，以及接上工具使用（tool use）让 Claude 能调用你定义的函数。
获取 API key
一切都从 Anthropic 控制台开始。注册账号，然后在 API Keys 区创建一个 API key。key 以 sk-ant- 开头，且只显示一次——立刻复制到安全的地方。把它当成密码：任何拿到 key 的人都能花你的额度。
把它设成环境变量，这样 SDK 能自动找到它，而不需要你写死在源码里：
export ANTHROPIC_API_KEY="sk-ant-..."
把这行加到你的 shell 配置里，让它跨终端持久化；在生产里用 .env 文件和加载器。SDK 在你不显式传 key 时会自动读取 ANTHROPIC_API_KEY，这样密钥就不会出现在代码里。
在控制台时，顺便设一个消费上限。API 按 token 计费，一个失控的循环很容易烧光额度。预算上限能把一个 bug 变成一个错误，而不是一张意外账单。
安装 SDK
Anthropic 为 Python 和 TypeScript 维护官方 SDK（其他语言有社区 SDK）。选跟你技术栈匹配的那个。
Python：
pip install anthropic
TypeScript / Node.js：
npm install @anthropic-ai/sdk
两个 SDK 都是同一个 HTTP API 的薄封装，所以概念在它们之间完全互通。下面的例子用 Python，TypeScript 有差异的地方会注明。
你的第一条消息
API 围绕一个端点组织：创建一条消息。你传一个模型、一组消息（每条带角色和内容）、一个最大输出长度，拿回 Claude 的响应。
from anthropic import Anthropic
client = Anthropic() # 自动从环境变量读取 ANTHROPIC_API_KEY
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "用两句话解释什么是 MCP 服务器。"}
],
)
print(response.content[0].text)
关于这次调用，几点值得理解：
model—— 模型 ID。当前一代包括 Claude Opus、Sonnet、Haiku 等家族，各有带版本号的版本。模型 ID 遵循类似claude-sonnet-4-5的模式；务必查官方模型文档获取确切的、当前的 ID 字符串，因为它们会随时间演进。max_tokens—— 响应最多包含多少 token。这是一个硬上限，也是必填字段。开放式生成设宽松些，结构化抽取设紧一些。messages—— 对话，是一组{role, content}轮次。角色是user和assistant。这里不单独传 system 消息；它走可选的顶层system参数。response.content—— 响应是一个内容块列表，不是纯字符串。最常见的块类型是text，但正如你在工具使用里看到的，它也可以是tool_use。取典型响应的文本用response.content[0].text。
TypeScript 调用形态相同：client.messages.create({ model, max_tokens, messages })，返回一个带 .content 数组的对象。
加上系统提示词
系统提示词为整段对话设定 Claude 的角色、语气和基本规则。作为顶层 system 参数传入：
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
system="你是一个严谨的文字编辑。只改语法和清晰度，绝不改变作者原意或添加信息。",
messages=[
{"role": "user", "content": "检查这句话的清晰度：……"}
],
)
系统提示词是放稳定指令的地方——身份、策略、输出格式。用户消息是放变化输入的地方。保持这种分离，提示词才好维护。
流式响应
对交互式应用来说，等完整响应显得慢。流式让你在 token 一产生时就发出。Python SDK 提供了一个流式辅助：
with client.messages.stream(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[{"role": "user", "content": "写一首关于 TCP 的短诗。"}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
stream.text_stream 在文本块生成时逐个 yield，所以你可以实时打印、发到 websocket、或追加到 UI。底层用的是服务器推送事件（server-sent events）；SDK 替你解析。
你也可以调 messages.create(..., stream=True) 自己迭代原始事件流，这给你对单个事件（消息开始、内容块增量、消息结束）更细的控制。对大多数场景，stream() 辅助是更简单的路；原始流用于你需要显式处理每种事件类型时。
工具使用：让 Claude 调用你的函数
工具使用（常被叫做「function calling」）是把 Claude 从文本生成器变成能采取行动的 Agent 的关键。你用名字、描述和入参的 JSON Schema 定义工具。当 Claude 判定某个工具有助于回答用户时，它会发出一个 tool_use 块（而不是、或除了文本之外）。你执行工具、回传 tool_result、Claude 继续。
下面是一个完整最小的例子。我们定义一个 get_weather 工具，让 Claude 调用它：
import json
from anthropic import Anthropic
client = Anthropic()
tools = [
{
"name": "get_weather",
"description": "Get the current weather for a given city.",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "The city name, e.g. 'San Francisco'."}
},
"required": ["city"],
},
}
]
# 真实应用里这里会调一个真正的天气 API。
def get_weather(city: str) -> str:
return json.dumps({"city": city, "condition": "foggy", "temperature_c": 14})
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "What's the weather in San Francisco?"}],
)
# 当 Claude 决定用工具时，stop_reason 是 "tool_use"，且响应内容里出现 tool_use 块。
if response.stop_reason == "tool_use":
# 找到 tool_use 块（一次响应里可能有多个）。
for block in response.content:
if block.type == "tool_use":
result = get_weather(**block.input)
# 把助手的 tool_use 轮次原样回传，再跟一个带 tool_result 的 user 轮次。
# 然后再调一次 create，让 Claude 用结果来回答。
follow_up = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=tools,
messages=[
{"role": "user", "content": "What's the weather in San Francisco?"},
{"role": "assistant", "content": response.content},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": block.id,
"content": result,
}
],
},
],
)
print(follow_up.content[0].text)
else:
print(response.content[0].text)
值得注意的机制：
input_schema是描述工具参数的 JSON Schema。Claude 按 schema 填充input，所以精确的 schema 产生精确的调用。tool_use_id把结果和调用绑起来。如果 Claude 在一次响应里做了两次工具调用，每个结果都需要匹配的 id。- 要把助手那一轮原样回传。 注意后续消息里有
{"role": "assistant", "content": response.content}——完整的原始内容块，而不只是抽出来的文本。这保留了工具使用的上下文，让 Claude 知道它问过什么。 stop_reason == "tool_use"是你判断 Claude 想调工具而非直接回答的方式。
在生产 Agent 循环里，你一直调 create 直到 stop_reason 不再是 tool_use，每轮执行工具并回填结果。这个循环是任何 Agent 的心脏——如果你不想自己写，Claude Agent SDK 已经替你实现了。
实用建议
几条很快见效的习惯：
- 发布前核对模型 ID。 ID 会演进；教程里写死的 ID 可能已过时。官方模型文档是事实来源。
- 慎重设
max_tokens。 太低 Claude 的答案会被半句截断；太高你就放弃了成本控制。对结构化抽取，紧的上限还能把模型往简洁输出上推。 - 开发期间记录完整请求和响应。 出问题时，请求体和原始响应通常足够诊断。生产前剥掉日志，避免记录用户数据。
- 处理错误和限流。 SDK 会为错误、限流和服务器过载抛出类型化异常。对可重试的做指数退避重试。
- 先不用工具，需要时再加。 令人惊讶的大量工作，靠一个好的系统提示词和结构良好的输入就能完成。当模型确实需要采取行动或查它不可能知道的东西时，再加工具使用。
常见问题
怎么获取 Claude API 的 API key？
在 Anthropic 控制台注册账号，从 API Keys 区生成一个 key。key 以 sk-ant- 开头且只显示一次，所以立刻复制。把它设成 ANTHROPIC_API_KEY 环境变量，SDK 就会自动读取；并在控制台设一个消费上限以封顶你的敞口。
messages.create 该传哪个模型名？
模型 ID 遵循「家族-版本」模式，例如 Sonnet 家族的 claude-sonnet-4-5。确切的、当前的 ID 字符串会随新版本发布而演进，所以务必查官方模型文档获取最新 ID，而不是依赖教程里写死的值。
Claude API 的工具使用是怎么工作的？
你向 messages.create 传一个 tools 数组，每个工具有 name、description 和入参的 JSON Schema（input_schema）。当 Claude 判定某个工具有用时，它返回一个 tool_use 内容块，并把 stop_reason 设为 'tool_use'。你执行工具，然后发一条带 tool_result 块（带匹配的 tool_use_id）的后续消息，再调一次 create，让 Claude 用结果来回答。
messages.create 带 stream=True 和 messages.stream 有什么区别？
两者都是流式响应。messages.stream 是一个高层辅助，通过 stream.text_stream yield 已解析的文本块，并替你处理事件解析——对大多数场景最简单。messages.create(..., stream=True) 返回原始事件流，让你对内容块增量等单个事件有更细的控制；当你需要显式处理每种事件类型时用它。
官方参考资料
- Claude API 文档总览
- Anthropic Python SDK（anthropics/anthropic-sdk-python）
- Anthropic TypeScript SDK（anthropics/anthropic-sdk-typescript）
- Claude 工具使用总览
- Claude 模型总览
本文基于截至 2026 年 7 月的公开信息，相关 API 可能演进。