Introduction

Claude isn't just a chatbot—it's a powerful AI platform you can integrate into your own applications. Whether you're building a customer support agent, a code assistant, or a creative writing tool, the Claude API gives you direct access to the same models that power claude.ai.

This guide covers everything you need to go from zero to your first production-ready Claude integration. You'll learn about the two main developer surfaces—Messages API and Managed Agents—and get hands-on with code examples, model selection, and the full developer lifecycle.

Prerequisites

Before you start, make sure you have:

• A Claude API account (sign up for free credits)
• Python 3.8+ installed on your machine
• Basic familiarity with REST APIs and JSON

Step 1: Get Your API Key

Your API key is the credential that authenticates your requests to Claude. To get one:

• Log in to the Anthropic Console
• Navigate to API Keys
• Click Create Key and copy the value

⚠️ Security note: Never hardcode your API key in source code. Use environment variables or a secrets manager.

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

Step 2: Install the SDK

Anthropic provides official SDKs for Python, TypeScript, Go, Java, Ruby, PHP, and C#. For this guide, we'll use Python.

pip install anthropic

Step 3: Make Your First API Call

Here's the simplest possible Claude integration—a single message exchange:

import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)
print(message.content[0].text)

Run this script, and you'll see Claude's friendly response printed to your terminal. Congratulations—you've just made your first API call!

Breaking Down the Code

• client.messages.create() — The core method for sending messages to Claude
• model — Specifies which Claude model to use (we'll cover model selection next)
• max_tokens — Limits the length of Claude's response
• messages — An array of conversation turns; each has a role (user or assistant) and content

Step 4: Choose Your Model

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

Recommendation: Start with Sonnet for most use cases. It's the sweet spot of capability and cost. Upgrade to Opus when you need deeper reasoning, and switch to Haiku when you need lightning-fast responses.

Step 5: Choose Your Developer Surface

Claude offers two ways to build:

Messages API (Direct Model Access)

With the Messages API, you have full control. You construct every turn of the conversation, manage conversation state yourself, and write your own tool loop. This is ideal for:

• Custom chat interfaces
• Workflows where you need fine-grained control
• Applications that already have their own state management

# Example: Multi-turn conversation
import anthropic
client = anthropic.Anthropic()
conversation = [
    {"role": "user", "content": "What's the capital of France?"}
]
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=256,
    messages=conversation
)
Add assistant response to conversation history
conversation.append({"role": "assistant", "content": response.content[0].text})
Ask a follow-up
conversation.append({"role": "user", "content": "What's its population?"})
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=256,
    messages=conversation
)
print(response.content[0].text)

Managed Agents (Fully Managed Infrastructure)

Managed Agents handle the heavy lifting for you. They run in stateful sessions with persistent event history, so you don't need to manage conversation state. This is ideal for:

• Autonomous agents that need to maintain context over long interactions
• Rapid prototyping without worrying about infrastructure
• Applications where you want to delegate tool use and memory management to Claude

# Example: Managed Agent (conceptual)
import anthropic
client = anthropic.Anthropic()
Create an agent session
agent = client.agents.create(
    model="claude-sonnet-4-6",
    instructions="You are a helpful customer support agent for an e-commerce store."
)
Interact with the agent—state is managed automatically
response = agent.message("I need to return a pair of shoes I bought last week.")
print(response.text)

Note: Managed Agents are a newer feature. Check the API reference for the latest syntax and availability.

Step 6: Explore Advanced Features

Once you've mastered the basics, Claude's API offers several powerful capabilities:

Extended Thinking

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

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    thinking={"type": "enabled", "budget_tokens": 1024},
    messages=[{"role": "user", "content": "Solve this complex math problem..."}]
)

Vision

Send images to Claude for analysis:

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

Tool Use (Function Calling)

Give Claude the ability to call external APIs and functions:

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

Other Features

• Prompt Caching — Reduce latency and cost for repeated system prompts
• Streaming — Get responses token-by-token for real-time UX
• Structured Outputs — Force Claude to return JSON or other structured formats
• Code Execution — Let Claude run code in a sandboxed environment

Step 7: The Developer Journey — From Idea to Production

Anthropic maps out a clear lifecycle for building with Claude:

Phase 1: Get Started

• Get API key — Done!
• Choose a model — See Step 4 above
• Install an SDK — See Step 2
• Try the Workbench — Use the Claude Workbench in the console to experiment with prompts before writing code

Phase 2: Build

Implement the features you need using the Messages API or Managed Agents. Start with simple single-turn calls, then layer on:

• Multi-turn conversations
• Tool use
• Streaming
• Vision

Phase 3: Evaluate & Ship

Before going to production:

• Run evals — Test your system against a set of expected inputs/outputs
• Batch testing — Run large-scale tests to catch edge cases
• Set up guardrails — Use content filtering and safety checks
• Monitor rate limits & errors — Implement retry logic and backoff
• Optimize costs — Use prompt caching and choose the right model

Phase 4: Operate

Once live:

• Workspaces & admin — Organize your API keys and projects
• Usage monitoring — Track token consumption and costs
• Model migration — Plan for upgrading to newer Claude models as they release

Best Practices for Production

• Always set max_tokens — Prevents runaway responses
• Implement retry logic — Handle transient errors with exponential backoff
• Use environment variables — Never expose your API key
• Log interactions — For debugging and auditing (but respect user privacy)
• Start with Sonnet — It's the most cost-effective for most use cases

Next Steps

• Dive into the API Reference for full parameter documentation
• Explore the Cookbook for code samples and patterns
• Try the Quickstarts for deployable starter apps
• Learn about Claude Code for agentic coding in your terminal

Key Takeaways

• Two developer surfaces: Choose Messages API for full control or Managed Agents for hands-off infrastructure
• Three models: Opus (deep reasoning), Sonnet (balanced), Haiku (speed)—start with Sonnet
• Python SDK is your friend: One pip install anthropic and a few lines of code gets you started
• Advanced features: Extended thinking, vision, tool use, and streaming unlock powerful applications
• Follow the lifecycle: Build → Evaluate → Ship → Operate for a smooth path to production

Happy building with Claude!