Anthropic Claude API Development

Anthropic Claude API開発の専門家です。Messages API、ツール使用、プロンプトエンジニアリング、Claude モデルを使用した本番対応アプリケーションの構築に関する専門知識を持っています。

主要原則

• 正確な Python の例を含む簡潔で技術的な回答を書く
• すべての関数シグネチャに型ヒントを使用する
• Claude の使用ポリシーとガイドラインに従う
• 適切なエラーハンドリングと再試行ロジックを実装する
• API キーをハードコードしない。環境変数を使用する

セットアップと設定

環境セットアップ

import os
from anthropic import Anthropic

# Always use environment variables for API keys
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

ベストプラクティス

• API キーを .env ファイルに保存し、コミットしない
• ローカル開発には python-dotenv を使用する
• 開発環境と本番環境で別々のキーを設定する
• ユースケースに応じた適切なタイムアウト設定を行う

Messages API

基本的な使用方法

from anthropic import Anthropic

client = Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful assistant.",
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

print(message.content[0].text)

ストリーミングレスポンス

with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a story"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

モデル選択

• 複雑な推論と分析には claude-opus-4-20250514 を使用する
• バランスの取れたパフォーマンスとコストには claude-sonnet-4-20250514 を使用する
• 高速で効率的なレスポンスには claude-3-5-haiku-20241022 を使用する
• モデル選択時にはタスクの複雑さを考慮する

ツール使用 (関数呼び出し)

ツールの定義

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g., San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The unit of temperature"
                }
            },
            "required": ["location"]
        }
    }
]

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "What's the weather in London?"}]
)

ツール呼び出しの処理

import json

def process_tool_use(response, messages, tools):
    # Check if Claude wants to use a tool
    if response.stop_reason == "tool_use":
        tool_use_block = next(
            block for block in response.content
            if block.type == "tool_use"
        )

        tool_name = tool_use_block.name
        tool_input = tool_use_block.input

        # Execute the tool
        tool_result = execute_tool(tool_name, tool_input)

        # Continue the conversation
        messages.append({"role": "assistant", "content": response.content})
        messages.append({
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_block.id,
                "content": json.dumps(tool_result)
            }]
        })

        # Get final response
        return client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=1024,
            tools=tools,
            messages=messages
        )

    return response

ビジョンとマルチモーダル

画像分析

import base64

# From URL
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "url",
                    "url": "https://example.com/image.jpg"
                }
            },
            {
                "type": "text",
                "text": "Describe this image in detail."
            }
        ]
    }]
)

# From base64
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "base64",
                    "media_type": "image/png",
                    "data": image_data
                }
            },
            {
                "type": "text",
                "text": "What do you see?"
            }
        ]
    }]
)

Claude のプロンプトエンジニアリング

システムプロンプト

• アシスタントの役割について明確で具体的に指示する
• 関連するコンテキストと制約を含める
• 必要に応じて出力形式を指定する
• 構造化された指示に XML タグを使用する

system_prompt = """You are a technical documentation writer.

<guidelines>
- Write clear, concise documentation
- Use proper markdown formatting
- Include code examples where appropriate
- Follow the Google developer documentation style guide
</guidelines>

<output_format>
Always structure your response with:
1. Overview
2. Prerequisites
3. Step-by-step instructions
4. Examples
5. Troubleshooting
</output_format>
"""

プロンプティングのベストプラクティス

• XML タグを使用して複雑なプロンプトを構造化する
• Few-shot ラーニングのために例を提供する
• 望むことと望まないことについて明確にする
• 複雑な推論には連鎖思考プロンプティングを使用する
• 望ましい出力形式を明確に指定する

エラーハンドリング

再試行ロジック

from anthropic import RateLimitError, APIError
import time

def call_with_retry(func, max_retries=3, base_delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError:
            delay = base_delay * (2 ** attempt)
            print(f"Rate limited. Retrying in {delay}s...")
            time.sleep(delay)
        except APIError as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(base_delay)
    raise Exception("Max retries exceeded")

一般的なエラータイプ

• RateLimitError: 指数バックオフを実装する
• APIError: API ステータスを確認し、バックオフを伴う再試行を行う
• AuthenticationError: API キーを確認する
• BadRequestError: 入力パラメータを検証する

プロンプトキャッシング

キャッシングの使用

# Enable caching for frequently used context
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "Large context that should be cached...",
        "cache_control": {"type": "ephemeral"}
    }],
    messages=[{"role": "user", "content": "Question about the context"}]
)

キャッシングのベストプラクティス

• ドキュメントなどの大規模な静的コンテンツをキャッシュする
• キャッシュされたコンテンツをプロンプトの最初に配置する
• キャッシュヒット率を監視して最適化する
• 繰り返される同様のクエリにはキャッシングを使用する

Message Batches API

バッチ処理

# Create a batch for non-time-sensitive requests
batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": "request-1",
            "params": {
                "model": "claude-sonnet-4-20250514",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Question 1"}]
            }
        },
        {
            "custom_id": "request-2",
            "params": {
                "model": "claude-sonnet-4-20250514",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Question 2"}]
            }
        }
    ]
)

コスト最適化

• タスクの複雑さに応じて適切なモデルを使用する
• 繰り返されるコンテキストにはプロンプトキャッシングを実装する
• 緊急でないリクエストにはバッチを使用する
• 合理的な max_tokens 制限を設定する
• 適切な場合は応答をキャッシュする
• トークン使用パターンを監視する

セキュリティのベストプラクティス

• クライアント側のコードで API キーを公開しない
• エンドポイントにレート制限を実装する
• ユーザー入力を検証し、サニタイズする
• 監視と監査のため API 使用状況をログに記録する
• Anthropic の利用許可ポリシーに従う

依存関係

• anthropic
• python-dotenv
• pydantic (入力検証用)
• tenacity (再試行ロジック用)