Introduction

Claude, developed by Anthropic, is a family of large language models designed for safe, capable, and scalable AI applications. Whether you're building a chatbot, automating code generation, or processing documents, Claude offers two primary integration paths: the Messages API for direct, fine-grained control, and Claude Managed Agents for long-running, asynchronous tasks.

This guide is your practical starting point. You'll learn how to set up your environment, make your first API call, understand the request/response structure, choose the right model, and explore the features that make Claude a powerful tool for developers.

Prerequisites

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

Step 1: Make Your First API Call

Let's start with the quickest path to a working Claude integration. We'll use the Python SDK.

Install the SDK

pip install anthropic

Set Your API Key

Export your API key as an environment variable:

export ANTHROPIC_API_KEY="sk-ant-..."

Send Your First Message

Create a file first_call.py:

import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude! What can you do?"}
    ]
)
print(message.content[0].text)

Run it:

python first_call.py

You should see Claude's response printed to the console. This is the foundation for everything else.

Step 2: Understand the Messages API

The Messages API is the core interface for interacting with Claude. It supports multi-turn conversations, system prompts, and structured outputs.

Request Structure

A basic request includes:

• model: The Claude model identifier (e.g., claude-sonnet-4-20250514)
• max_tokens: Maximum number of tokens in the response
• messages: An array of message objects, each with a role (user or assistant) and content
• system (optional): A system prompt to set the assistant's behavior

Multi-Turn Conversation Example

import anthropic
client = anthropic.Anthropic()
messages = [
    {"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=messages
)
print(response.content[0].text)

Handling Stop Reasons

Every response includes a stop_reason field. Common values:

• "end_turn": Claude finished naturally
• "max_tokens": The response was cut off due to token limit
• "stop_sequence": A custom stop sequence was encountered

You can use this to decide whether to continue the conversation or truncate the response.

Step 3: Choose the Right Model

Claude offers several models optimized for different use cases:

Recommendation: Start with Sonnet 4.6 for most use cases. Switch to Opus for tasks requiring deep reasoning, and Haiku for high-throughput, low-latency applications.

Step 4: Explore Key Features

Claude's API supports a rich set of features. Here are the most impactful ones for developers:

Extended Thinking

Enable chain-of-thought reasoning for complex tasks:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=2048,
    thinking={"type": "enabled", "budget_tokens": 1024},
    messages=[
        {"role": "user", "content": "Solve this math problem step by step: 15 * 23 + 7"}
    ]
)
print(response.content[0].text)

Structured Outputs

Get JSON-formatted responses for programmatic consumption:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Extract the name, date, and amount from this invoice: 'Invoice #1234 - John Doe - $500 - Due 2025-06-01'"}
    ],
    response_format={"type": "json_object"}
)
print(response.content[0].text)

Tool Use (Function Calling)

Claude can call external tools or APIs:

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }
]
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "What's the weather in Tokyo?"}
    ],
    tools=tools
)
print(response.content[0].text)

Vision and PDF Support

Claude can process images and PDFs:

import base64
with open("document.pdf", "rb") as f:
    pdf_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": "Summarize this PDF"},
                {"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": pdf_data}}
            ]
        }
    ]
)
print(response.content[0].text)

Step 5: Managed Agents (For Long-Running Tasks)

If you need to run complex, multi-step tasks asynchronously, use Claude Managed Agents. They handle state management, tool orchestration, and error recovery.

agent = client.agents.create(
    name="my-agent",
    model="claude-sonnet-4-20250514",
    instructions="You are a research assistant. Find the latest news about AI and summarize it.",
    tools=["web_search", "web_fetch"]
)
Start a task
task = agent.tasks.create(
    input="Find the top 3 AI news stories from today"
)
Check status later
status = agent.tasks.retrieve(task.id)
print(status.output)

Best Practices

• Use system prompts to set Claude's behavior and constraints.
• Set appropriate max_tokens to avoid truncated responses.
• Handle stop reasons to manage conversation flow.
• Use streaming for real-time user experiences.
• Cache frequently used prompts with Prompt Caching to reduce costs.

Next Steps

• Explore the Claude Cookbook for interactive Jupyter notebooks
• Test prompts in the Developer Console
• Read the Messages API documentation for advanced usage

Key Takeaways

• Start with the Messages API for direct control; use Managed Agents for complex, long-running workflows.
• Choose your model wisely: Opus for deep reasoning, Sonnet for balanced performance, Haiku for speed and cost efficiency.
• Leverage structured outputs and tool use to build reliable, programmatic integrations.
• Always handle stop reasons to gracefully manage response length and conversation flow.
• Use streaming and prompt caching to optimize latency and cost in production applications.