Anthropic SDK Go 版（anthropic sdk go）：安装、首个请求、流式与错误处理（2026）

Anthropic SDK Go 版是 Claude API 的官方 Go 客户端，发布在 github.com/anthropics/anthropic-sdk-go。它用带类型的请求和响应结构体封装了 Messages API，内置重试与流式处理，还能把请求指向任意兼容的 Base URL。本文讲清安装、第一个请求、流式输出、错误处理，以及生产环境里真正要关心的客户端选项。

Anthropic SDK Go 版能帮你做什么

用 net/http 直接调 Claude API 当然可以，但 SDK 帮你省掉了那些最容易写错的部分：

• 带类型的参数与响应：字段拼错在编译期就会报错，而不是线上返回 400。
• 自动重试：遇到连接错误和 429、5xx 这类可重试状态码时自动退避重试。
• 流式辅助：读取服务端事件流（SSE），并可把事件累积成完整消息。
• 客户端选项：统一配置 API Key、Base URL、超时与重试次数。

如果你同时用其他语言，同样的概念也出现在 Anthropic SDK Python 版和 Anthropic SDK TypeScript 版里。

安装 Anthropic SDK Go 版

在 Go module 里添加依赖：

go get github.com/anthropics/anthropic-sdk-go

SDK 遵循语义化版本。跨大版本升级前先看仓库的 Release 说明，因为大版本之间类型名和辅助函数可能会变。生产服务请在 go.mod 里锁定版本。

用 Go 客户端发第一个请求

客户端默认读取环境变量 ANTHROPIC_API_KEY，所以最小程序不需要显式传 Key：

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient() // 读取 ANTHROPIC_API_KEY

	msg, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		Model:     "claude-sonnet-5-5", // 换成你实际使用的模型
		MaxTokens: 1024,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("用两句话解释 Go 的 channel。")),
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	for _, block := range msg.Content {
		if block.Type == "text" {
			fmt.Println(block.Text)
		}
	}
}

有三点要注意：

• MaxTokens 是必填项，它限制的是回复长度，不是提示词大小。
• 响应的 Content 是一组内容块。文本最常见，但工具调用会以单独的块返回，所以要先判断块类型，别默认第一个块就是文本。
• msg.Usage 会返回输入与输出 token 数，计费就按它来。从第一天起就把它记进日志。

流式输出

聊天界面和长输出建议用流式，让用户边生成边看到文字：

stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
	Model:     "claude-sonnet-5-5",
	MaxTokens: 1024,
	Messages: []anthropic.MessageParam{
		anthropic.NewUserMessage(anthropic.NewTextBlock("写一首关于延迟的俳句。")),
	},
})

message := anthropic.Message{}
for stream.Next() {
	event := stream.Current()
	if err := message.Accumulate(event); err != nil {
		log.Fatal(err)
	}
	// 在这里检查 event，可实时打印文本增量。
}
if err := stream.Err(); err != nil {
	log.Fatal(err)
}
// 此时 message 已是完整响应，包含 usage。

固定套路是 Next() → Current() → 循环结束后检查 Err()。漏掉最后的 Err() 是最常见的流式 bug：连接中断时循环会悄悄结束，程序把半截答案当成完整结果。事件序列在 HTTP 层面怎么运作，见我们的 Claude API 流式输出指南。

错误、重试与超时处理

API 错误以 *anthropic.Error 返回，里面带有 HTTP 状态码：

import "errors"

_, err := client.Messages.New(ctx, params)
var apiErr *anthropic.Error
if errors.As(err, &apiErr) {
	log.Printf("status %d", apiErr.StatusCode)
}

常见状态码的处理方式：

客户端默认会对可重试错误重试少量次数。调整重试与超时请用选项，而不是在每个调用外面自己包一层：

import (
	"time"

	"github.com/anthropics/anthropic-sdk-go/option"
)

client := anthropic.NewClient(
	option.WithMaxRetries(4),
	option.WithRequestTimeout(60*time.Second),
)

速率限制按组织和模型设定，加并发之前值得先搞清楚。它的计量方式见 Anthropic API 速率限制。

客户端选项：API Key 与 Base URL

两个选项覆盖了大部分配置需求：

• option.WithAPIKey("...")：显式设置 Key，而不是读环境变量。请从密钥管理服务加载，绝不要写死在代码里。
• option.WithBaseURL("https://...")：把请求发到另一个端点，比如内部网关、区域中转或兼容代理。SDK 会自动拼接 API 路径，所以只传 Base URL 即可。

client := anthropic.NewClient(
	option.WithAPIKey(os.Getenv("MY_CLAUDE_KEY")),
	option.WithBaseURL(os.Getenv("CLAUDE_BASE_URL")),
)

更换 Base URL 后，在切生产流量之前先确认该端点支持你依赖的功能，比如流式和工具调用。要检查哪些项，见 Claude API 代理指南。

常见问题

Anthropic 有官方的 Go SDK 吗？

有。Anthropic 维护 github.com/anthropics/anthropic-sdk-go，覆盖 Messages API、流式输出、工具调用和客户端配置。在 Go module 里用 go get 安装即可。

Go SDK 里怎么设置 API Key？

客户端默认从环境变量读取 ANTHROPIC_API_KEY。要显式设置，就在 anthropic.NewClient 里传入 option.WithAPIKey(...)，值从密钥管理服务加载。

Go SDK 能用自定义端点吗？

能。创建客户端时传入 option.WithBaseURL(...)。这样就能经由内部网关或兼容中转发请求，其余代码不用改。

Anthropic Go SDK 会自动重试失败的请求吗？

会。它会对连接错误和 429、5xx 等可重试状态码做几次退避重试。用 option.WithMaxRetries 调整次数，用 option.WithRequestTimeout 设置单次请求超时。

一句话总结

安装 github.com/anthropics/anthropic-sdk-go，创建读取 ANTHROPIC_API_KEY 的客户端，用模型、MaxTokens 和消息调用 client.Messages.New。流式输出用 NewStreaming，循环后务必检查 Err()；通过 *anthropic.Error 读取状态码；重试、超时和 Base URL 都用客户端选项配置。