Claude Agent SDK Tutorial for Business Agents: Build With Control

Claude Agent SDK Tutorial for Business Agents: Build With Control

To build a business agent with the Claude Agent SDK, define one narrow workflow, give the agent a few tools, restrict its permissions, write clear instructions, log every action, and only then run a pilot with an agreed success metric. The SDK provides the agent loop (model, tools and context). What makes the agent safe for your company is what you build around it. This tutorial follows the order we recommend building in.

Key takeaways

• The SDK provides the agent loop and ready-made tools. Scope, limits, logging and evaluation remain the responsibility of whoever implements it.
• Start with the process, not the code: one real workflow, with a baseline and a success criterion defined in advance.
• Tools and permissions are the main risk lever. Start with read-only access and require human approval for any action that changes data or talks to a customer.
• Hooks and logs turn written rules into enforced rules and make every decision auditable.
• Parameter names and features change between versions. Always check the official SDK documentation before copying a configuration.

What the Claude Agent SDK gives you and what stays your job

The Claude Agent SDK is a library (there are Python and TypeScript versions) that lets you run, inside your own systems, the same kind of agent that powers Claude Code. In practical terms, you send a task, the model decides which tools to use, the SDK runs those tools, returns the result to the model, and repeats until the task is done or a limit you set is reached.

That means you do not have to write the decision loop, basic context management or the most common tools, such as reading files, searching text and running commands. The official documentation also describes features such as MCP servers for connecting systems, subagents, resumable sessions, permission modes and hooks.

What the SDK does not decide for you: which process is worth automating, which data the agent may see, which actions need approval, how to measure whether it worked, and who is accountable when something goes wrong. Those are business decisions. For the conceptual background behind this split, Anthropic's article on building effective agents clearly separates predictable workflows from agents that choose their own path, and recommends the simplest solution that solves the problem.

What are the steps to build the agent?

Use this sequence as a work plan. Each step has a concrete output you can review before moving on.

• Step 1, map: describe the current process with its stages, who performs them, which systems it touches and where people hesitate. Record the baseline (how the process works today) without inventing numbers you have not measured.
• Step 2, scope: pick a single workflow and write in one sentence what the agent does and what it never does.
• Step 3, list tools: for each stage, define which tool is needed and whether it only reads or also writes.
• Step 4, set permissions: explicitly allow only what the workflow requires and block everything else.
• Step 5, write instructions and context: business rules, tone, escalation cases and output format.
• Step 6, instrument: record the input, the tool called, its parameters, the result, the decision and the cost per run.
• Step 7, evaluate: build a set of real, anonymized cases, including the hard ones, and run it before any real user touches the agent.
• Step 8, pilot and decide: run it on a real workflow with a human in the loop, then decide whether to expand, adjust or stop.

Steps one and two involve no code, and they are the ones that prevent the most rework. If you are still choosing which process to tackle first, the decision matrix for choosing which processes to automate helps you prioritize without betting on the most ambitious workflow.

How do you give the agent tools without opening too much?

The SDK offers built-in tools and lets you create your own, usually exposed as an MCP server (Model Context Protocol, the open standard for connecting models to systems and data). The business question is the same in both cases: what does this agent really need to touch?

A good rule is to split tools into three groups:

• Read: check an order status, look up a customer record, read a policy document. Low risk, start here.
• Reversible write: create a draft, open a ticket, log a note. Acceptable with logging and review.
• Irreversible or external write: send a message to a customer, change a value, cancel, issue. Requires human approval at the start.

On the design of each tool, Anthropic has published guidance on writing tools for agents. The points that matter most day to day are clear names and descriptions, unambiguous parameters, lean responses that do not dump unnecessary data into the context, and error messages that help the agent correct its next attempt. A poorly described tool produces wrong calls, and people often read that as a model defect when it is really an interface defect.

If your internal system does not yet have a suitable API, read the guide on how to build an MCP server for internal systems, which argues for starting with read-only access. For third-party integrations, treat the server as code that runs with company credentials and audit it before installing.

How do you set permissions and hooks so the agent stays within limits?

The SDK works with allowed and denied tools, plus permission modes that define what the agent can do without asking for confirmation. The official documentation describes the available modes and how each behaves. Our recommended method is simple: start from the most restrictive setting and open up by exception, never the other way around. A mode that approves everything automatically suits experiments in an isolated environment, not an agent connected to customer data.

Beyond the permission list, the SDK supports hooks: points where your own code runs before or after a tool is used. This is where a business rule becomes an enforced rule. Examples:

• Before a write tool runs, check whether the value is within the agreed limit and, if not, block it and escalate to a person.
• Before any external send, require a recorded approval.
• After every call, write the event to the log with the run identifier.
• Mask personal data that does not need to reach the model, in line with the data minimization principle of Brazil's LGPD.

The concept is the same one discussed in Claude Code hooks, and the validation layer for input, output and action is covered in guardrails for AI agents. One point of caution: text coming from emails, web pages or customer messages can contain disguised instructions. The OWASP Top 10 for LLM applications treats this as a central risk, and the defense is not just a better prompt. It is limiting what the agent can do even if it is tricked.

Finally, credentials. The agent should not hold broad-use keys. Use service accounts with the least access possible, keep secrets out of the code and out of the model's context, and have a rotation plan.

What instructions and context should the agent receive?

The agent works with what is in its context. In the SDK, that includes the system prompt, project instruction files (such as a CLAUDE.md, if you choose to load it in the settings) and whatever the tools return. Anthropic has an article on context engineering for agents whose central idea is useful for business: context is a limited resource, so provide the smallest amount of high-signal information instead of pasting in the company's entire manual.

A lean set of instructions for a business agent usually includes:

• Role and goal in a few sentences.
• What it may do and what is forbidden.
• When to stop and call a person, with concrete examples.
• The expected output format, to make automatic validation easier.
• The source of truth: where prices, deadlines and policies come from (never from the model's memory).

That last rule reduces invented answers. If a piece of information changes, it should be fetched by a tool, not written into the prompt. For prompt writing in customer support, there is a specific guide on instructions for an AI support agent.

How do you log, evaluate and pilot before going to production?

Without logs, all you can say is that the agent seems to work. With logs, you can answer what it did, why and at what cost. Record per run: an identifier, the input (with sensitive data masked), each tool call with parameters and result, the final output, whether it escalated, the time taken and token usage. The concepts of traces, metrics and logs from the OpenTelemetry observability primer apply directly, and treating each run as a trace made of steps helps with debugging.

On evaluation, Anthropic's material on evals for agents insists on a practical point: evaluate both the outcome and the path, with realistic tasks and edge cases, and read the transcripts to understand failures instead of looking only at an aggregate score. Build the case set before the pilot and rerun it every time you change an instruction, a tool or the model.

Illustrative scenario: a distributor wants an agent to prepare replies to customer questions about order status. The team maps the current workflow, decides that the agent only reads the order system and writes a draft, and that a person approves each send. A hook blocks any write tool. The log stores the order looked up, the draft generated and whether the person edited or approved it. After the pilot period, the team reviews the most edited drafts, adjusts the instructions, and decides whether to allow automatic sending for one simple type of question, keep things as they are, or stop. No numbers appear in this example because it is only a process sketch.

This is where our method applies directly: map the process and the baseline, limit data and actions, pilot one real workflow with logs and an agreed success metric, then hand over operations and decide whether to expand, adjust or stop. To define pilot metrics and decision criteria, see how to measure an AI automation pilot.

Frequently asked questions

Do I need to know how to code to use the Claude Agent SDK? Yes. The SDK is a library for Python or TypeScript, so someone on the team has to write and maintain the code. The business side, such as mapping the process, setting limits and evaluating results, can and should be led by the people who know the operation.

Is the Claude Agent SDK suitable for WhatsApp agents? It can be the decision core of an agent that serves customers on WhatsApp, but the channel is a separate layer: message intake, queues, service windows and platform rules sit outside the SDK. Treat the channel and the agent as separate components, with logs on both.

How much human control is needed at the start? For any action that changes data, sends a message to a customer or involves money, begin with human approval on every case. As logs and evaluation show stable behavior on a specific type of task, you can reduce approval for that type only, while keeping the ability to roll back.

What changes under LGPD when using an agent built with the SDK? The agent becomes one more processing of personal data, so purpose, minimization, access control and record-keeping apply. Define which data reaches the model, mask what is not needed, document the flow and, if the case is sensitive, ask your legal team whether an impact assessment is advisable. The ANPD is the official source for guidance in Brazil.

Sources

• Anthropic: Building effective agents
• Anthropic: Writing effective tools for agents
• Anthropic: Demystifying evals for AI agents
• OpenTelemetry: observability concepts