Getting Started with Claude: A Practical Guide to the Anthropic API

Claude is Anthropic's family of large language models designed for safe, helpful, and honest AI interactions. Whether you're building a chatbot, automating workflows, or creating intelligent agents, the Claude API gives you direct access to these powerful models.

This guide covers everything you need to go from zero to a working Claude integration. We'll walk through setup, the core API structure, key features, and best practices.

Understanding Your Options: API vs. Managed Agents

Before diving in, it's important to understand the two primary ways to build with Claude:

• Messages API: Direct access to the model. You control the entire request/response loop. Best for custom agent loops and fine-grained control.
• Claude Managed Agents: A pre-built, configurable agent harness that runs on Anthropic's managed infrastructure. Best for long-running tasks and asynchronous work.

For most developers starting out, the Messages API is the recommended path because it gives you full flexibility and a clear understanding of how Claude works.

Prerequisites

To follow this guide, you'll need:

• An Anthropic account (sign up at console.anthropic.com)
• An API key (generated in the Console)
• Python 3.8+ or Node.js 18+ installed
• Basic familiarity with REST APIs and JSON

Step 1: Make Your First API Call

Let's start with the classic "Hello, World!" — but with Claude.

Python Setup

pip install anthropic

import anthropic
client = anthropic.Anthropic(
    api_key="sk-ant-your-api-key-here"  # Replace with your actual key
)
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)
print(message.content[0].text)

TypeScript Setup

npm install @anthropic-ai/sdk

import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
  apiKey: 'sk-ant-your-api-key-here',
});
async function main() {
  const message = await client.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello, Claude!' }],
  });
console.log(message.content[0].text);
}
main();

Expected response: Claude will greet you back with a friendly introduction.

Step 2: Understand the Messages API Structure

The Messages API is the core of Claude's interaction model. Here's what you need to know:

Request Components

Multi-Turn Conversations

To have a back-and-forth conversation, simply append messages:

conversation = [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "What is its population?"}
]
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=256,
    messages=conversation
)

Stop Reasons

Every response includes a stop_reason field that tells you why Claude stopped:

• "end_turn": Claude finished its response naturally
• "max_tokens": The response hit the token limit
• "stop_sequence": Claude encountered a custom stop sequence
• "tool_use": Claude wants to call a tool (more on this later)

response = client.messages.create(...)
print(f"Stop reason: {response.stop_reason}")

Step 3: Choose the Right Model

Claude comes in several flavors, each optimized for different use cases:

Recommendation: Start with Sonnet 4.6 for most use cases. It offers the best balance of intelligence and speed. Switch to Haiku for high-volume, simple tasks, and Opus when you need maximum reasoning capability.

Step 4: Explore Key Features

Once you have the basics down, here are the features that make Claude powerful:

Extended Thinking

Claude can "think" before responding, improving reasoning on complex tasks:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=4096,
    thinking={"type": "enabled", "budget_tokens": 2048},
    messages=[
        {"role": "user", "content": "Solve this step by step: 23 * 47 + 15"}
    ]
)
Access the thinking content
for block in response.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

Structured Outputs

Get Claude to return JSON directly, perfect for API integrations:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="Always respond in valid JSON format.",
    messages=[
        {"role": "user", "content": "Extract the name, age, and city from: John is 28 and lives in Seattle."}
    ]
)

Tool Use (Function Calling)

Claude can call external tools and functions. Here's a minimal example:

def get_weather(location: str) -> str:
    return f"The weather in {location} is sunny, 72°F"
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    ],
    messages=[
        {"role": "user", "content": "What's the weather in Tokyo?"}
    ]
)

When Claude decides to use a tool, the response will contain a tool_use content block with the function name and arguments.

Vision (Image Processing)

Claude can analyze images:

import base64
with open("chart.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this chart."},
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                }
            ]
        }
    ]
)

Streaming Responses

For real-time applications, stream the response token by token:

stream = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)
for chunk in stream:
    if chunk.type == "content_block_delta" and chunk.delta.type == "text_delta":
        print(chunk.delta.text, end="", flush=True)

Best Practices for Production

1. Use System Prompts Effectively

System prompts set the tone and constraints for Claude:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful customer support agent for Acme Corp. "
           "Always be polite, concise, and offer solutions. "
           "If you don't know something, say so honestly.",
    messages=[{"role": "user", "content": "My order hasn't arrived."}]
)

2. Handle Errors Gracefully

try:
    response = client.messages.create(...)
except anthropic.APIError as e:
    print(f"API error: {e}")
except anthropic.APIConnectionError as e:
    print(f"Connection error: {e}")
except anthropic.RateLimitError as e:
    print(f"Rate limited: {e}")

3. Manage Token Usage

• Set max_tokens appropriately for your use case
• Use prompt caching for repeated system prompts
• Monitor token usage in the Anthropic Console

Developer Tools

Anthropic provides several tools to accelerate development:

• Developer Console: Prototype prompts in your browser with the Workbench and prompt generator
• API Reference: Full documentation for all endpoints and SDKs
• Claude Cookbook: Interactive Jupyter notebooks covering PDFs, embeddings, and more

Next Steps

Now that you have the fundamentals, here's what to explore next:

• Build a multi-turn chatbot using the conversation history pattern
• Implement tool use to give Claude access to databases, APIs, or file systems
• Experiment with extended thinking for complex reasoning tasks
• Set up evaluations using the Evaluation Tool in the Console to measure performance

Key Takeaways

• Start with the Messages API for maximum flexibility and control over Claude's behavior
• Choose your model wisely: Sonnet for balance, Haiku for speed, Opus for maximum reasoning
• Master the conversation structure: Messages array with alternating user/assistant roles is the foundation
• Leverage advanced features: Extended thinking, tool use, and structured outputs unlock Claude's full potential
• Use the Developer Console to prototype and test prompts before writing production code