◉CLAUDE LABEN
●CC 2.1.327 — Claude Code 2.1.327(11/18)で、MCP サーバーの設定を標準入力から渡せる claude mcp add-json が加わりました●MCP.JSON — 同じ版で、project スコープの mcp add・remove が .mcp.json の他のキーを消していた問題が直りました●SONNET 4.5 — Claude API での提供終了は 11/30、残り11日。コードと保存済みのモデル設定を一度に洗い出してください●GATEWAY — 1M 文脈のモデルをゲートウェイ越しに使うと、自動圧縮が遅すぎて1回の応答に数十秒かかる、という報告が出ています●NEON — 11/18 に Gemini 4 Neon が GA。Claude Code と併用するなら、MCP の設定をツールごとに分けておくと混乱しません●NEW — Linked billing の 402 と 403、どの財布が空かを見分ける●CC 2.1.327 — Claude Code 2.1.327(11/18)で、MCP サーバーの設定を標準入力から渡せる claude mcp add-json が加わりました●MCP.JSON — 同じ版で、project スコープの mcp add・remove が .mcp.json の他のキーを消していた問題が直りました●SONNET 4.5 — Claude API での提供終了は 11/30、残り11日。コードと保存済みのモデル設定を一度に洗い出してください●GATEWAY — 1M 文脈のモデルをゲートウェイ越しに使うと、自動圧縮が遅すぎて1回の応答に数十秒かかる、という報告が出ています●NEON — 11/18 に Gemini 4 Neon が GA。Claude Code と併用するなら、MCP の設定をツールごとに分けておくと混乱しません●NEW — Linked billing の 402 と 403、どの財布が空かを見分ける
記事一覧/API & SDK
⬡ API & SDK/2026-04-16上級

Claude API × Go言語 本番実装 — Anthropic Go SDK・並行処理・Tool Use・マイクロサービス統合

Anthropic Go SDK で Claude API を本番運用するための実装パターン。ストリーミング・goroutine による並行処理・Tool Use・Gin/Echo 統合・グレースフルシャットダウンまで、動作するコードとともに整理しています。

gogolangapi-sdk13streaming16tool-use23microservicesproduction87concurrency

✦ プレミアム記事

Go で Claude API を呼び出すコードを書いたとき、最初に気づく「やりにくさ」があります。

ストリーミングレスポンスを goroutine で処理しようとすると、context が早期にキャンセルされてパニックになります。Tool Use の並行実行を試みると、レート制限エラーが散発します。Gin のハンドラーに組み込もうとすると、SSE の flusher 設定でつまずきます。

これらは Go 特有のパターンで、Python や TypeScript の記事からは学べません。いくつかの本番プロジェクトで Claude API を Go に統合してきた中でぶつかった壁を、動作確認済みのコードとともに整理したのがこの記事です。

Anthropic の公式 Go SDK(anthropic-sdk-go)は 2024 年末にリリースされ、現在も活発に開発が続いています。Python SDK ほど情報が多くないため、Go バックエンドエンジニアが実装で詰まりやすい状況が続いています。

Anthropic Go SDK のセットアップと初回呼び出し

まず基本から始めましょう。anthropic-sdk-go の依存追加と、確実に動く最初の呼び出しコードです。

go get github.com/anthropics/anthropic-sdk-go
// main.go
package main
 
import (
    "context"
    "fmt"
    "log"
    "os"
 
    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
)
 
func main() {
    // APIキーは環境変数から取得(ハードコードは絶対にしない)
    client := anthropic.NewClient(
        option.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
    )
 
    ctx := context.Background()
    msg, err := client.Messages.New(ctx, anthropic.MessageNewParams{
        Model:     anthropic.F(anthropic.ModelClaude_Sonnet_4_6),
        MaxTokens: anthropic.F(int64(1024)),
        Messages: anthropic.F([]anthropic.MessageParam{
            anthropic.NewUserMessage(anthropic.NewTextBlock("Go言語の並行処理の特徴を3行で教えてください")),
        }),
    })
    if err != nil {
        log.Fatalf("API呼び出し失敗: %v", err)
    }
 
    for _, block := range msg.Content {
        if block.Type == anthropic.ContentBlockTypeText {
            fmt.Println(block.Text)
        }
    }
}

ポイント: anthropic.F() は Option 型でラップするヘルパー関数です。Go SDK は「フィールドが設定されているかどうか」を明示的に管理するため、nil と「未設定」を区別します。最初は冗長に見えますが、APIパラメータの省略・必須を型で明確にするための設計になっています。

System Prompt と会話履歴の管理

実際のアプリでは会話履歴を保持する必要があります。Go では構造体でステートを管理するのが自然な設計です。

// conversation.go
package claude
 
import (
    "context"
    "fmt"
 
    anthropic "github.com/anthropics/anthropic-sdk-go"
)
 
// ConversationSession は1会話のステートを管理します
type ConversationSession struct {
    client     *anthropic.Client
    systemText string
    history    []anthropic.MessageParam
    model      anthropic.Model
}
 
func NewConversationSession(client *anthropic.Client, systemPrompt string) *ConversationSession {
    return &ConversationSession{
        client:     client,
        systemText: systemPrompt,
        history:    make([]anthropic.MessageParam, 0),
        model:      anthropic.ModelClaude_Sonnet_4_6,
    }
}
 
// Send はユーザーメッセージを送信し、アシスタントの返答を返します
func (s *ConversationSession) Send(ctx context.Context, userMsg string) (string, error) {
    // ユーザーメッセージを履歴に追加
    s.history = append(s.history, anthropic.NewUserMessage(
        anthropic.NewTextBlock(userMsg),
    ))
 
    params := anthropic.MessageNewParams{
        Model:     anthropic.F(s.model),
        MaxTokens: anthropic.F(int64(2048)),
        Messages:  anthropic.F(s.history),
    }
 
    if s.systemText != "" {
        params.System = anthropic.F([]anthropic.TextBlockParam{
            anthropic.NewTextBlock(s.systemText),
        })
    }
 
    resp, err := s.client.Messages.New(ctx, params)
    if err != nil {
        // エラー時は履歴をロールバック(アシスタント応答なしで終わると次回リクエストが壊れる)
        s.history = s.history[:len(s.history)-1]
        return "", fmt.Errorf("API呼び出し失敗: %w", err)
    }
 
    var result string
    for _, block := range resp.Content {
        if block.Type == anthropic.ContentBlockTypeText {
            result += block.Text
        }
    }
 
    s.history = append(s.history, anthropic.NewAssistantMessage(
        anthropic.NewTextBlock(result),
    ))
 
    return result, nil
}

エラー時に履歴をロールバックする実装が重要です。API 呼び出し失敗後にユーザーメッセージだけ履歴に残ると、次の呼び出しで「アシスタントメッセージが欠落している」エラーが発生します。

Streaming レスポンスの正しい実装

Streaming は Go で最もハマりやすい部分です。よくある間違いと正しい実装を並べてみます。

よくある間違い: goroutine リーク

// BAD: これはgoroutineリークを起こします
func badStreaming(client *anthropic.Client) {
    ctx := context.Background()
    stream := client.Messages.NewStreaming(ctx, anthropic.MessageNewParams{
        Model:     anthropic.F(anthropic.ModelClaude_Sonnet_4_6),
        MaxTokens: anthropic.F(int64(1024)),
        Messages: anthropic.F([]anthropic.MessageParam{
            anthropic.NewUserMessage(anthropic.NewTextBlock("Hello")),
        }),
    })
 
    go func() {
        for stream.Next() {
            event := stream.Current()
            _ = event
        }
        // stream.Close()が呼ばれないとリーク発生
    }()
    // この関数が返った後、goroutineは何も受け取る先がなく宙ぶらりんになる
}
// GOOD: 正しいStreaming実装
func goodStreaming(ctx context.Context, client *anthropic.Client, userMsg string, output chan<- string) error {
    stream := client.Messages.NewStreaming(ctx, anthropic.MessageNewParams{
        Model:     anthropic.F(anthropic.ModelClaude_Sonnet_4_6),
        MaxTokens: anthropic.F(int64(2048)),
        Messages: anthropic.F([]anthropic.MessageParam{
            anthropic.NewUserMessage(anthropic.NewTextBlock(userMsg)),
        }),
    })
    defer stream.Close() // 必ずdeferでCloseする
 
    for stream.Next() {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
        }
 
        event := stream.Current()
        switch event := event.AsUnion().(type) {
        case anthropic.ContentBlockDeltaEvent:
            if delta, ok := event.Delta.AsUnion().(anthropic.TextDelta); ok {
                select {
                case output <- delta.Text:
                case <-ctx.Done():
                    return ctx.Err()
                }
            }
        }
    }
 
    if err := stream.Err(); err != nil {
        return fmt.Errorf("ストリームエラー: %w", err)
    }
    return nil
}

defer stream.Close() が必須です。また、channel への送信時にも ctx.Done() を監視することで、クライアント切断時に goroutine が正しく終了するようになります。

Gin での SSE ストリーミングエンドポイント

// handler/stream.go
package handler
 
import (
    "fmt"
    "net/http"
 
    "github.com/gin-gonic/gin"
)
 
func (h *Handler) StreamChat(c *gin.Context) {
    var req struct {
        Message string `json:"message" binding:"required"`
    }
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
 
    // SSEヘッダーの設定
    c.Header("Content-Type", "text/event-stream")
    c.Header("Cache-Control", "no-cache")
    c.Header("Connection", "keep-alive")
    c.Header("X-Accel-Buffering", "no") // nginxのバッファリングを無効化(重要)
 
    flusher, ok := c.Writer.(http.Flusher)
    if !ok {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "SSE非対応環境です"})
        return
    }
 
    ctx := c.Request.Context()
    tokenCh := make(chan string, 10)
    errCh := make(chan error, 1)
 
    go func() {
        defer close(tokenCh)
        err := h.claude.StreamMessage(ctx, req.Message, tokenCh)
        errCh <- err
    }()
 
    for {
        select {
        case token, ok := <-tokenCh:
            if !ok {
                fmt.Fprintf(c.Writer, "data: [DONE]\n\n")
                flusher.Flush()
                return
            }
            fmt.Fprintf(c.Writer, "data: %s\n\n", token)
            flusher.Flush()
 
        case err := <-errCh:
            if err != nil {
                fmt.Fprintf(c.Writer, "event: error\ndata: %s\n\n", err.Error())
                flusher.Flush()
            }
            return
 
        case <-ctx.Done():
            return
        }
    }
}

X-Accel-Buffering: no ヘッダーは nginx を使っている場合に忘れがちですが、これがないとレスポンスがバッファリングされてリアルタイム性が失われます。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること
✦Anthropic Go SDKの罠(Streaming時のgoroutineリーク・context cancelの正しい扱い)で詰まっていた人が、本番で安定動作するパターンを今日から実装できるようになります
✦Tool Use を errgroup で並行実行しながら、429/529 を full jitter のバックオフで散らして再送する構成まで、動作するコードで追えます
✦Gin/Echoへの統合からDockerコンテナ化・Kubernetes対応まで、実プロダクトで動く完全なマイクロサービスアーキテクチャを手に入れられます
Stripe による安全な決済 · いつでもキャンセル可能
✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または
メンバーシップなら全記事が読み放題 →
シェア

お読みいただきありがとうございます

Claude Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

関連記事

⬡ API & SDK2026-04-26
Claude API でジェネレーティブ UI を本番投入する — JSON Schema と Tool Use で動的コンポーネントをストリーミング描画する実装パターン
Claude API のツール呼び出しと部分 JSON ストリーミングを組み合わせ、AI が動的に組み立てた UI コンポーネントを安全に描画する本番設計を、コンポーネントレジストリ・型安全性・フォールバック含めて解説します。
⬡ API & SDK2026-05-26
Claude API の構造化レスポンスを本番で安定させる — tool_use と JSON Schema、多層検証の実装メモ
Claude API の応答を JSON で受け取る実装は数行で書けますが、本番運用では「形は正しいが意味が壊れている」レスポンスにどう備えるかが分かれ目になります。tool_use・JSON Schema・ドメイン検証を組み合わせた多層パイプラインを、壁紙アプリの分類処理での実体験を交えて整理しました。
⬡ API & SDK2026-05-22
Claude API の tool_result could not be submitted が再発しないための回復ハンドラ設計
Claude API でエージェントを長時間動かしていると、ある日突然 'tool_result could not be submitted' が連発し始めることがあります。再試行しても直らない、ストリーミング途中で死ぬ、そして次のセッションでもまた出る — 常時稼働のエージェント基盤で実際に踏み抜いた4種類の原因と、TypeScript で書いた回復ハンドラの実装を整理しました。