A practical guide to the Python Claude Agent SDK

A ton of buzz has been floating around about Anthropic’s developer SDK for building AI agents, and honestly, it’s for a good reason. It’s like giving developers a key to build autonomous tools that can use a computer just like a person would.

Now, if you go looking for the original "claude-code-sdk" package that got everyone talking, you’ll find it’s been deprecated. But don’t worry, its successor, the "claude-agent-sdk", is here to carry the torch with even more power under the hood. This guide will walk you through what the Python Claude Code SDK (now the Agent SDK) is all about, what you can do with it, and some real-world things to think about before you decide to build your own business agents from the ground up.

What is the Python Claude Code SDK and why is it now the agent SDK?

Let's clear up the name situation first. If you search for the Python Claude Code SDK, you’ll see that the original "claude-code-sdk" package on PyPI is officially deprecated. It’s been replaced by the much more fitting "claude-agent-sdk". So, why the switch? Anthropic pretty quickly figured out that the tools they were building for coding could be used for a whole lot more.

The Claude Agent SDK is a library, available for Python and TypeScript, that essentially lets you give Claude access to a local computer. Think of it as giving Claude a body, not just a brain.

Instead of just spitting out text in response to a prompt, an agent built with this SDK can actually use tools to interact with its environment. It can read and write files, look through your codebase, and run terminal commands like "grep" to find info or kick off scripts. It basically gives Claude a set of hands to gather its own context and take action, transforming it from a simple chatbot into a real collaborator.

What can you build with the Python Claude Code SDK?

The SDK is a pretty powerful toolkit for developers, opening up a whole world of possibilities for creating custom, automated workflows. Here’s a peek at what makes it so interesting.

Local file and terminal access

The biggest leap forward here is giving Claude a presence in your local environment. Instead of being some detached brain in the cloud, it can now do things on your machine.

For example, you could ask an agent to "find the database connection string in our project." A normal chatbot would just give up. But an agent built with the SDK could use the "grep" command to search for "DATABASE_URL" across all the files, read the right one, and give you the answer. This "agentic search" is a huge deal, letting the AI actively find the information it needs instead of passively waiting for you to feed it everything.

A flexible toolset for any task

The SDK comes with a bunch of built-in tools that will feel familiar to any developer:

• Read/Write: For basic file operations.

• Bash: For running any command-line script or shell command you can think of.

• Grep/Glob: For searching inside files or finding files that match a specific pattern.

• WebFetch/WebSearch: For pulling information down from the internet.

But you're not stuck with just these. The SDK supports something called the Model Context Protocol (MCP), which lets you define your own Python functions and turn them into new tools for Claude. For instance, a customer support team could build a custom tool called "lookup_order(order_id)" that hooks into their Shopify store's API. When a user asks about their order, the agent can call this tool to grab real-time details on its own.

Advanced features for creating complex agents

As your ideas get bigger, the SDK has features to help you manage the complexity and add more control.

You can create subagents, which are like specialized little agents designed for one specific job. For example, your main agent could hand off a tricky security question to a "security-reviewer" subagent that has its own set of instructions and a very limited toolkit. This helps keep things organized and allows more complicated tasks to be broken down and even run at the same time.

The SDK also includes hooks, which let you inject your own logic at important points in the agent's process. You could use a hook to double-check a file path before a "Write" tool is used, adding a simple safety net to prevent it from accidentally overwriting the wrong file.

Plan the application around the work it needs to do

The Claude Agent SDK supplies the agent loop, tools, and context management. Your Python application still needs the right integrations, permissions, and tests. You can use existing MCP servers where they fit instead of implementing a custom tool for every system.

For support, decide whether you need a new agent application or access to a teammate that already has the relevant instructions and knowledge. The latter is where eesel CLI fits.

Use eesel CLI from a Python support workflow

eesel CLI exposes an eesel AI teammate through terminal commands. A developer can run them directly, a Python script can invoke them, and a coding agent can use their JSON output to help configure or inspect the teammate. The commands operate the same workspace as the dashboard, so support colleagues can manage the same setup.

For example, a Python release-check script could report the teammate's source download status before a person reviews whether its knowledge needs updating. A successful status check is not a guarantee of correct answers; it gives the reviewer information about the connected sources.

Read workspace status with a Python script

For an existing eesel workspace, install the CLI with Node.js 18.17 or newer, log in, and list the agents:

npm install -g @eesel/cli
eesel login
eesel agents

Choose the intended support agent and set EESEL_AGENT_ID to its ID in your environment. This example invokes the installed eesel command and prints its status result:

import json
import os
import subprocess

agent_id = os.environ["EESEL_AGENT_ID"]

result = subprocess.run(
    ["eesel", "status", "--agent", agent_id],
    capture_output=True,
    text=True,
    timeout=30,
    check=False,
)

if result.returncode != 0:
    raise RuntimeError(
        f"eesel status failed ({result.returncode}): {result.stderr.strip()}"
    )

status = json.loads(result.stdout)
print(json.dumps(status, indent=2))

The example uses a fixed command with a separate argument list, not a shell string assembled from a prompt. It assumes the CLI is on your PATH and the process can access your login credentials. A missing agent ID, missing executable, or timeout stops the script rather than silently treating the check as successful.

For a headless environment, the CLI supports EESEL_API_URL and EESEL_API_TOKEN instead of browser login. Supply them through your deployment's secret handling, not source code. Scope the command to the intended agent and avoid sharing private status or error output publicly.

Extend inspection to a policy review

You can inspect standing rules with eesel instructions --agent <agent-id> and recent work with eesel activity --agent <agent-id>. These give a coding agent useful context for proposing an update.

After a person approves the change, upload the actual policy file with eesel files upload ./support-policy.pdf --agent <agent-id>. Confirm success, then use eesel chat "What does our policy say about a late cancellation?" --agent <agent-id> and compare the answer with the document. Connected-source download status and successful local uploads are separate checks.

Keep this workflow explicit. A script that reads status is not automatically authorized to change instructions or approve actions. For writes, --dry-run previews the server request without sending it; test the teammate's answers separately.

Connect the Python agent through MCP

If you want the SDK agent to select eesel tools during its work, use the eesel MCP setup. Run eesel mcp token --agent <agent-id> after login to obtain the server URL, headers, and token.

Configure those values in the Python SDK's mcp_servers option or a configuration file it loads, following the SDK MCP guide. Verify the connection and allow only the tools needed for your task. The CLI's generated Claude Code setup command is not a Python SDK configuration.

The token lasts 30 days and captures your workspace role when issued. Mint a new one and update the headers after a role change or expiry. Workspace approval rules still apply; SDK permissions do not replace them.

Compare ownership and cost, not just package names

A custom Python agent gives you control over the application you build. eesel CLI gives that application, or a developer working beside it, access to an existing teammate's knowledge and work. The two can be complementary.

Budget for the custom application's model usage, hosting, and maintenance, plus eesel usage if you connect the workspace. eesel billing shows its current billing state. Neither a successful script nor an MCP connection means the two services share a subscription.

If your next Python automation task needs support context, try eesel and start with the CLI guide. Read status first, inspect the relevant instructions, and review a realistic answer before expanding what the workflow can change.