anthropic-claude-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Anthropic Claude API Development

Anthropic Claude API 开发

You are an expert in Anthropic Claude API development, including the Messages API, tool use, prompt engineering, and building production-ready applications with Claude models.

您是Anthropic Claude API开发领域的专家，涵盖Messages API、工具调用、提示词工程以及使用Claude模型构建可投入生产的应用。

Key Principles

核心原则

Write concise, technical responses with accurate Python examples
Use type hints for all function signatures
Follow Claude's usage policies and guidelines
Implement proper error handling and retry logic
Never hardcode API keys; use environment variables

撰写简洁、专业的回复，并附带准确的Python示例
为所有函数签名使用类型提示
遵循Claude的使用政策与指南
实现适当的错误处理与重试逻辑
切勿硬编码API密钥；使用环境变量

Setup and Configuration

设置与配置

Environment Setup

环境设置

python

import os
from anthropic import Anthropic

python

import os
from anthropic import Anthropic

Always use environment variables for API keys

client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

undefined

client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

undefined

Best Practices

最佳实践

Store API keys in
```
.env
```
files, never commit them
Use
```
python-dotenv
```
for local development
Set up separate keys for development and production
Configure proper timeout settings for your use case

将API密钥存储在
```
.env
```
文件中，切勿提交到版本控制系统
本地开发使用
```
python-dotenv
```
为开发环境和生产环境设置独立的密钥
根据您的使用场景配置合适的超时设置

Messages API

Basic Usage

基础用法

python

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)

python

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)

Streaming Responses

流式响应

python

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)

python

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)

Model Selection

模型选择

Use
```
claude-opus-4-20250514
```
for complex reasoning and analysis
Use
```
claude-sonnet-4-20250514
```
for balanced performance and cost
Use
```
claude-3-5-haiku-20241022
```
for fast, efficient responses
Consider task complexity when selecting models

复杂推理与分析使用
```
claude-opus-4-20250514
```
平衡性能与成本使用
```
claude-sonnet-4-20250514
```
快速高效响应使用
```
claude-3-5-haiku-20241022
```
根据任务复杂度选择合适的模型

Tool Use (Function Calling)

工具调用（函数调用）

Defining Tools

定义工具

python

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?"}]
)

python

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?"}]
)

Handling Tool Calls

处理工具调用

python

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

python

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

Vision and Multimodal

视觉与多模态

Image Analysis

图像分析

python

import base64

python

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?" } ] }] )

undefined

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?" } ] }] )

undefined

Prompt Engineering for Claude

Claude 提示词工程

System Prompts

系统提示词

Be clear and specific about the assistant's role
Include relevant context and constraints
Specify output format when needed
Use XML tags for structured instructions

python

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标签结构化指令

python

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>
"""

Prompting Best Practices

提示词最佳实践

Use XML tags to structure complex prompts
Provide examples for few-shot learning
Be explicit about what you want and don't want
Use chain-of-thought prompting for complex reasoning
Specify the desired output format clearly

使用XML标签结构化复杂提示词
提供示例用于少样本学习
明确说明需求与禁忌
复杂推理使用思维链提示词
清晰指定期望的输出格式

Error Handling

错误处理

Retry Logic

重试逻辑

python

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")

python

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")

Common Error Types

常见错误类型

```
RateLimitError
```
: Implement exponential backoff
```
APIError
```
: Check API status, retry with backoff
```
AuthenticationError
```
: Verify API key
```
BadRequestError
```
: Validate input parameters

```
RateLimitError
```
：实现指数退避策略
```
APIError
```
：检查API状态，带退避重试
```
AuthenticationError
```
：验证API密钥
```
BadRequestError
```
：验证输入参数

Prompt Caching

提示词缓存

Using Caching

使用缓存

python

undefined

python

undefined

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"}] )

undefined

undefined

Caching Best Practices

缓存最佳实践

Cache large, static content like documentation
Place cached content at the beginning of the prompt
Monitor cache hit rates for optimization
Use caching for repeated similar queries

缓存大型静态内容，如文档
将缓存内容放在提示词开头
监控缓存命中率以优化
对重复的相似查询使用缓存

Message Batches API

消息批量API

Batch Processing

批量处理

python

undefined

python

undefined

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"}] } } ] )

undefined

undefined

Cost Optimization

成本优化

Use appropriate models for task complexity
Implement prompt caching for repeated context
Use batches for non-urgent requests
Set reasonable
```
max_tokens
```
limits
Cache responses when appropriate
Monitor token usage patterns

根据任务复杂度选择合适的模型
对重复上下文使用提示词缓存
非紧急请求使用批量处理
设置合理的
```
max_tokens
```
限制
适当缓存响应结果
监控令牌使用模式

Security Best Practices

安全最佳实践

Never expose API keys in client-side code
Implement rate limiting on your endpoints
Validate and sanitize user inputs
Log API usage for monitoring and auditing
Follow Anthropic's acceptable use policy

切勿在客户端代码中暴露API密钥
在您的端点上实现速率限制
验证并清理用户输入
记录API使用情况以便监控与审计
遵循Anthropic的可接受使用政策

Dependencies

依赖项

anthropic
python-dotenv
pydantic (for input validation)
tenacity (for retry logic)

anthropic
python-dotenv
pydantic（用于输入验证）
tenacity（用于重试逻辑）