Your Complete Guide to Building with the Claude API: From First Call to Production

Introduction

Claude isn't just a chatbot—it's a powerful API that you can integrate into your own applications, workflows, and agentic systems. Whether you're building a customer support bot, a code assistant, or a data analysis tool, the Claude API gives you direct access to the same models that power the Claude web interface.

This guide covers everything you need to know to start building with Claude: from your first API call to advanced features like tool use, streaming, and managed agents. By the end, you'll have a clear roadmap for taking your project from idea to production.

Getting Started: Your First API Call

1. Get an API Key

Before you can make any API calls, you need an API key. Head to the Claude Console and create a new key. Keep it secure—treat it like a password.

2. Choose Your Model

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

For most production workloads, Sonnet offers the best trade-off. Use Opus when you need maximum reasoning power, and Haiku for simple, fast responses.

3. Install an SDK

Anthropic 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:

npm install @anthropic-ai/sdk

4. Make Your First Call

Here's the classic "Hello, Claude" example in both Python and TypeScript.

Python:

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

TypeScript:

import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
async function main() {
  const message = await client.messages.create({
    model: 'claude-sonnet-4-6',
    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.

Building with the Messages API

The Messages API is the core interface for interacting with Claude. You send an array of messages (each with a role of user or assistant) and Claude responds with a new message.

Key Parameters

• model: The model ID (e.g., claude-sonnet-4-6)
• max_tokens: Maximum tokens in the response
• messages: Array of conversation turns
• system: (Optional) System prompt to set Claude's behavior
• temperature: (Optional) Controls randomness (0.0 to 1.0)

Handling Stop Reasons

When Claude finishes generating, the response includes a stop_reason. Common values:

• "end_turn": Claude naturally completed its response
• "max_tokens": The response hit the token limit
• "tool_use": Claude wants to call a tool

You should always check stop_reason to decide what to do next—especially if you're building a tool-using agent.

Advanced Features

Tool Use (Function Calling)

Claude can call external tools and functions. This is how you give Claude the ability to fetch data, run calculations, or interact with your systems.

Define a tool:

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

Handle tool calls in your loop:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=messages,
    tools=tools
)
if response.stop_reason == "tool_use":
    # Extract tool call from response
    tool_call = response.content[-1]
    # Execute the tool (your code)
    result = get_weather(tool_call.input["location"])
    # Send result back to Claude
    messages.append({"role": "user", "content": f"Tool result: {result}"})

Claude also supports parallel tool calls, strict tool use, and tool use with prompt caching for advanced workflows.

Streaming Responses

For a better user experience, stream Claude's response token by token:

Python:

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

Prompt Caching

Reduce costs and latency by caching repeated system prompts or large context blocks. This is especially useful when you have a long system prompt that stays the same across many requests.

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

Vision and PDF Support

Claude can analyze images and PDFs. Just include them in your message content:

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

Managed Agents: The Easy Path to Production

If you don't want to build your own tool loop and state management, Claude's Managed Agents offer a fully managed infrastructure. You define the agent's instructions and tools, and Claude handles the rest—including persistent sessions, event history, and automatic tool execution.

This is ideal for:

• Customer support bots
• Research assistants
• Code review agents
• Data analysis workflows

Choosing Your Development Path

Best Practices for Production

• Use prompt caching for repeated system prompts to reduce costs.
• Stream responses for better user experience.
• Handle stop reasons properly in your tool loop.
• Set appropriate max_tokens to avoid unexpected truncation.
• Run evaluations using the Evaluation Tool in the Console to test your prompts.
• Monitor usage through the Console's usage monitoring dashboard.

Key Takeaways

• The Claude API gives you direct access to Opus, Sonnet, and Haiku models via the Messages API or Managed Agents.
• Start with the Python or TypeScript SDK for the fastest onboarding experience.
• Use tool use, streaming, and prompt caching to build responsive, cost-effective applications.
• Choose Managed Agents when you want to skip building your own infrastructure.
• Always check stop_reason in responses to handle tool calls and token limits correctly.