Set Up and Run Your First Claude Agent

The Claude Agent SDK embeds the agent loop and tools that power Claude Code in a Python or TypeScript application. Its query() interface streams lifecycle, assistant, tool-result, and final messages. Start in a disposable directory with read-only tools, a turn limit, and an API key—then inspect every message type before allowing edits.

What will you be able to do?

You will install the Python SDK, run a repository summary agent, handle final results, and explain how the SDK differs from a direct Claude API client.

What do you need before starting?

Python 3.10+ or Node.js 18+.
An Anthropic account and API key.
A disposable practice directory with non-sensitive files.

The Python package is claude-agent-sdk; the TypeScript package is @anthropic-ai/claude-agent-sdk. Both bundle a native Claude Code binary for supported platforms, so a separate Claude Code install is not normally required.

How do you install it?

bash

mkdir supportops-claude && cd supportops-claude
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
export ANTHROPIC_API_KEY="replace-with-your-key"

The SDK reads the key from the process environment and does not automatically load .env files. Production credentials should come from a secrets manager or short-lived credential path.

How do you run a read-only agent?

Create README.md with a short fictional project description, then create first_agent.py:

python

import asyncio

from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ResultMessage,
    query,
)


async def main() -> None:
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
        disallowed_tools=["Edit", "Write", "Bash"],
        max_turns=4,
    )

    async for message in query(
        prompt="Read this practice project and summarize its purpose with file evidence.",
        options=options,
    ):
        if isinstance(message, AssistantMessage):
            print(f"Assistant turn: {len(message.content)} block(s)")
        elif isinstance(message, ResultMessage):
            print(f"Status: {message.subtype}")
            if message.subtype == "success":
                print(message.result)


if __name__ == "__main__":
    asyncio.run(main())

allowed_tools auto-approves listed tools; disallowed_tools blocks the dangerous tools even if other settings would permit them. The process working directory defines the default file scope, so run the lab only inside the disposable folder.

How do you prove it works?

Observe assistant messages followed by a result message.
Confirm the result cites or names the practice file.
Ask the agent to edit the README and confirm the denied tool prevents it.
Reduce max_turns and observe a non-success result subtype when the task needs more tool cycles.

Trace this run: query() starts a session, emits initialization, loops through assistant/tool messages, and ends with ResultMessage. Iterate the stream to completion; some lifecycle events can follow the result.

How does it fail safely?

Run with the key unset and confirm a clear configuration failure. Run from the wrong directory and stop immediately rather than granting broad file access to “make the demo work.”

What mistakes should you avoid?

Confusing the Agent SDK with the direct Anthropic Client SDK.
Enabling Edit or Bash in a real repository for the first run.
Assuming the current working directory is harmless.
Breaking out of the message stream before cleanup completes.
Offering end users your claude.ai login; use supported API authentication.

Check your understanding

What does the SDK bundle?
How do allowed_tools and disallowed_tools differ?
Which message marks the final run disposition?

Expert extension

Wrap query() in a domain boundary that emits normalized run.started, tool.observed, and run.completed events without logging file contents.

Official references

Set Up and Run Your First Claude Agent

What do you need before starting?

Python 3.10+ or Node.js 18+.

An Anthropic account and API key.

A disposable practice directory with non-sensitive files.

How do you install it?

bash

mkdir supportops-claude && cd supportops-claude
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
export ANTHROPIC_API_KEY="replace-with-your-key"

The SDK reads the key from the process environment and does not automatically load .env files. Production credentials should come from a secrets manager or short-lived credential path.

How do you run a read-only agent?

Create README.md with a short fictional project description, then create first_agent.py:

python

import asyncio

from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ResultMessage,
    query,
)


async def main() -> None:
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
        disallowed_tools=["Edit", "Write", "Bash"],
        max_turns=4,
    )

    async for message in query(
        prompt="Read this practice project and summarize its purpose with file evidence.",
        options=options,
    ):
        if isinstance(message, AssistantMessage):
            print(f"Assistant turn: {len(message.content)} block(s)")
        elif isinstance(message, ResultMessage):
            print(f"Status: {message.subtype}")
            if message.subtype == "success":
                print(message.result)


if __name__ == "__main__":
    asyncio.run(main())

How do you prove it works?

Observe assistant messages followed by a result message.

Confirm the result cites or names the practice file.

Ask the agent to edit the README and confirm the denied tool prevents it.

Reduce max_turns and observe a non-success result subtype when the task needs more tool cycles.

Trace this run: query() starts a session, emits initialization, loops through assistant/tool messages, and ends with ResultMessage. Iterate the stream to completion; some lifecycle events can follow the result.

What mistakes should you avoid?

Confusing the Agent SDK with the direct Anthropic Client SDK.

Enabling Edit or Bash in a real repository for the first run.

Assuming the current working directory is harmless.

Breaking out of the message stream before cleanup completes.

Offering end users your claude.ai login; use supported API authentication.