Building with Claude: A Complete Guide to the Platform, APIs, and Developer Tools

Claude isn't just a conversational AI—it's a full-fledged development platform. Whether you're building a simple chatbot, a complex agent with tool use, or a high-volume production system, the Claude API ecosystem gives you the flexibility and power to bring your ideas to life.

This guide covers everything you need to know to start building with Claude: from your first API call to advanced features like extended thinking, vision, and managed agents. We'll explore the key developer surfaces, SDKs, and best practices that will take you from prototype to production.

Understanding the Claude Developer Platform

The Claude platform offers two primary ways to build:

• Messages API: Direct, low-level access to Claude's models. You control every turn, manage conversation state, and write your own tool loops. Best for custom integrations and fine-grained control.
• Managed Agents: Fully managed agent infrastructure. Deploy autonomous agents in stateful sessions with persistent event history. Best for building self-contained agents that can handle complex, multi-step tasks without you managing the orchestration.

Both surfaces are accessible via the same API endpoints and SDKs, so you can start with one and migrate to the other as your needs evolve.

Getting Started: Your First API Call

Before you can build anything, you need an API key and a working development environment.

Step 1: Get Your API Key

Head to the Claude Console and generate an API key. Store it securely—you'll use it to authenticate every request.

Step 2: Install an SDK

Claude provides official SDKs for Python, TypeScript, Go, Java, Ruby, PHP, C#, and more. Here's how to install the two most popular ones:

Python

pip install anthropic

TypeScript/JavaScript

npm install @anthropic-ai/sdk

Step 3: Make Your First API Call

Here's the classic "Hello, Claude" example in Python:

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)

And the same call in TypeScript:

import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
async function main() {
  const message = await client.messages.create({
    model: 'claude-opus-4-7',
    max_tokens: 1024,
    messages: [
      { role: 'user', content: 'Hello, Claude' }
    ]
  });
console.log(message.content[0].text);
}
main();

That's it. You've just made your first API call to Claude.

Choosing the Right Model

Claude offers three model tiers, each optimized for different use cases:

For prototyping, start with Sonnet—it offers the best balance of capability and speed. Move to Opus when you need maximum reasoning power, and switch to Haiku when you're optimizing for cost and throughput.

Building with the Messages API

The Messages API is the core of the Claude platform. It supports a rich set of features that go far beyond simple text generation.

Extended Thinking

For tasks that require deep reasoning—like complex math, code generation, or multi-step analysis—you can enable extended thinking. This gives Claude more time to "think" before responding, often producing higher-quality results.

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    thinking={"type": "enabled", "budget_tokens": 2048},
    messages=[
        {"role": "user", "content": "Solve this complex logic puzzle step by step..."}
    ]
)

Vision

Claude can analyze images, diagrams, and documents. Pass image data as base64-encoded content blocks:

import base64
with open("chart.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")
message = 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 tools, APIs, or functions. Define tools as JSON schemas and Claude will decide when to invoke them:

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

Structured Outputs

Need Claude to return JSON or follow a specific schema? Use structured outputs to enforce response formats:

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Extract the name, date, and amount from this invoice..."}
    ],
    response_format={
        "type": "json_object",
        "schema": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "date": {"type": "string"},
                "amount": {"type": "number"}
            },
            "required": ["name", "date", "amount"]
        }
    }
)

Prompt Caching

For repetitive tasks (like system prompts or few-shot examples), enable prompt caching to reduce latency and cost:

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

Streaming

For real-time user experiences, stream responses token by token:

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

Managed Agents: Autonomous AI Workers

If you want to deploy an AI agent that can operate independently—maintaining state, using tools, and handling multi-turn conversations—Managed Agents are your best bet.

Key Features

• Stateful sessions: The agent remembers context across interactions.
• Persistent event history: Full audit trail of every action.
• Built-in tool loop: No need to write your own orchestration.
• Autonomous operation: Define your agent once, and it handles the rest.

Quickstart

# Create a managed agent
agent = client.agents.create(
    name="customer-support-agent",
    model="claude-sonnet-4-6",
    instructions="You are a helpful customer support agent...",
    tools=[...]  # Your custom tools
)
Start a session
session = client.agents.sessions.create(
    agent_id=agent.id
)
Send a message
response = client.agents.sessions.message(
    session_id=session.id,
    content="I need help with my order"
)

Managed Agents are ideal for customer support, research assistants, code review bots, and any scenario where you want a persistent, autonomous AI worker.

From Development to Production

Building is only half the journey. Here's how to ship with confidence.

Prompting Best Practices

• Be specific and clear in your instructions.
• Use system prompts to set behavior and constraints.
• Provide examples (few-shot prompting) for complex tasks.
• Iterate: test, refine, and test again.

Evaluation & Batch Testing

Run evals to measure performance before deploying changes. Use batch testing to compare model versions or prompt variations at scale.

Safety & Guardrails

Implement content filtering, rate limiting, and input validation. Claude's built-in safety features help, but always add your own guardrails for production.

Rate Limits & Error Handling

Handle 429 (rate limit) and 500 (server error) responses gracefully with exponential backoff and retries.

Cost Optimization

• Use Haiku for simple, high-volume tasks.
• Enable prompt caching for repeated content.
• Monitor token usage in the Claude Console.
• Set max_tokens appropriately—don't over-allocate.

Resources to Keep Learning

The Claude ecosystem is rich with learning materials:

• Interactive Courses: Master Claude through structured lessons.
• Cookbook: Ready-to-use code samples and patterns.
• Quickstarts: Deployable starter apps for common use cases.
• Claude Code: An agentic coding assistant in your terminal.

Key Takeaways

• Two developer surfaces: Choose between the flexible Messages API for custom integrations or Managed Agents for autonomous, stateful workflows.
• Three model tiers: Opus for deep reasoning, Sonnet for balanced production use, Haiku for high-speed, low-cost tasks.
• Rich feature set: Leverage extended thinking, vision, tool use, structured outputs, prompt caching, and streaming to build powerful applications.
• Production readiness: Evaluate, test, and optimize with built-in tools for safety, rate limiting, and cost management.
• Start small, iterate fast: Use the Workbench to prototype, then move to SDKs for production. The platform scales with you.