Building with the API and the Agent SDK

So far you have used Claude through its products. This module crosses to the other side: the API, the door through which your own program talks to the model. With no code (the course shows none), you will understand what goes into a request, what it costs, how the model uses tools, how to make it cheaper and when the Agent SDK is the right call, so you can design your first agent or commission one knowing what to ask for.

Features and prices are verified as of October 2026; prices change, the logic of how they are calculated does not.

What is the Claude API, and how do I get a key?

An API is how two programs talk to each other without a person in between. Your system (a script, an endpoint on your site, a step in n8n) sends text to Anthropic’s API and gets the model’s reply back. No chat app, no projects: just the engine and whatever you build around it.

The key to the door is the API key. You create it in the Claude Console (platform.claude.com) on the API keys page, with a name and an expiration date. It starts with sk-ant- and the Console shows it in full exactly once; if you lose it, you create another. Usage is paid with prepaid credits you buy under Settings > Billing; if they run out, the API stops answering, and they expire after a year.

You pay per token, as you saw in module 1: the ones going in (system prompt, documents, history) and the ones coming out (the reply), each with its own price per million. As of October 2026, per Anthropic’s pricing page: Claude Haiku 5.5 costs $0.10 per million input tokens and $0.50 per million output tokens (for prompts up to 100,000 tokens); Sonnet 5.5, $2 and $10; Opus 5.5, $4 and $20; Fable 5.1, $10 and $50.

The formula: (input tokens ÷ 1,000,000 × input price) + (output tokens ÷ 1,000,000 × output price). A 300-token guest message, with a 2,000-token system prompt and a 400-token reply, is 2,300 in and 400 out: under a tenth of a cent on Haiku 5.5, just under two cents on Opus 5.5. Every reply carries the exact count: you do not guess, you measure.

What does an API request look like, in plain words?

The main API is called Messages. A request is a JSON package with four things: the model (its exact identifier, for example claude-haiku-5-5), an optional {{system prompt|prompt-de-sistema}} (role, rules and fixed context, like a project’s instructions in module 6), the messages (the conversation so far; the API remembers nothing between calls, so you send the full history every time) and max_tokens, the ceiling on the reply.

The reply carries what your code reads: the content, as a list of blocks; the stop_reason, why the model stopped (end_turn if it finished, max_tokens if it ran out of room, tool_use if it wants a tool); and usage, the input and output tokens you just paid for.

You do not need to write it by hand. Anthropic publishes official SDKs (Python, TypeScript and five other languages) that turn it into a few lines, and the Console has a Playground (it replaced the old Workbench) where you build the request in the browser, see the reply with its token count and export it as code. It is the best place for your first test.

How does the model use tools when you build with the API?

Module 16 explained the agent loop; over the API, tool use works like this. You describe your tools in the request, each with a name, a description and a parameter schema. The model never executes anything: when it needs a tool, it replies with stop_reason tool_use and a block naming which one and with which parameters. Your code runs it (say, a lookup in the booking system), returns the result in a tool_result block and calls the API again with the whole history. This repeats as long as the model asks for tools and ends with end_turn. That "as long as" is the loop your program controls, with a cap on iterations and a log of every step.

There is a second kind: server tools, which Anthropic runs for you. As of October 2026: web search ($10 per thousand searches, plus tokens), web fetch and code execution (Python and bash in an isolated container with no internet; free alongside web search, and on its own with 1,550 free hours a month). The results come back in the same reply. The SDKs also ship a tool runner (in beta) that drives the loop for you when you do not need fine control.

What weighs most is not the code but the description. Anthropic’s recommendations, condensed:

• Extremely detailed descriptions. What it does, when to use it and when not to, what each parameter means, what it does not return. Anthropic asks for at least three or four sentences per tool and calls this "by far the most important factor".
• Few, capable tools. Group related operations into one tool with an action parameter, with the system name as a prefix (stays_find_booking).
• High-signal responses. Only the fields the model needs for its next step, with readable identifiers.
• Errors that explain. What happened and what to do, not a numeric code.

When you need data in a fixed shape rather than an action, use structured outputs: you put a JSON schema in the request and the API guarantees the reply conforms to it. It is the API version of what you did in module 8 with invoices: the format is guaranteed. The value is not: validation in code (subtotal plus tax equals total, tax ID on your supplier list) remains your job.

I am going to build an agent with the Claude API. Its task: [ONE SENTENCE]. The systems it can reach: [LIST, for example booking system, supplier spreadsheet, drafts inbox].

Define the tools following Anthropic’s recommendations for writing tools for agents:
- Few and capable: group related operations; prefix names with the system they belong to.
- For each one: name (lowercase with underscores), a description of at least four sentences (what it does, when to use it and when not to, what each parameter means, what it does NOT return), parameters with type and description and which are required, what it returns (only high-signal fields, with readable identifiers), and the possible errors with a message that says what to do.
- Mark which tools are read-only and which have side effects; the latter must create a draft or a pending request, never execute the final action.

Then write three test cases per tool: a valid input, an invalid one and an edge case, with the expected result for each.

How do I make the flow cheaper and faster?

Three levers, verified as of October 2026.

1. 1{{Prompt caching|cache-de-prompts}}. If every call repeats the same prefix (tools, system prompt, the property bible), you mark it with cache_control and the API keeps it for five minutes (or one hour, at a higher cost). Writing costs 1.25 times the input price; reading, 10 percent (5 on Opus 5.5 and Sonnet 5.5, 2.5 on Fable 5.1), and replies come back faster. The prefix must be identical byte for byte and there is a minimum of about 512 tokens. The reply tells you how many tokens were read from cache; if it is zero, something is invalidating it.
2. 2Batch processing (Batch API). For anything that can wait (the month’s reviews, five hundred PDFs), you send up to 100,000 requests in one batch and pay half, on input and output. Most batches finish in under an hour, the limit is 24 hours and results stay available for 29 days.
3. 3The small model wherever it is enough. Anthropic describes the routing pattern: a cheap first step classifies and decides what comes next; only the hard cases reach the big model. The rule is the evaluations of module 20: you change the model on one step and measure whether quality holds.

Help me estimate the monthly cost of a flow built on the Claude API. First ask me, one at a time, for whatever you are missing: how many cases per month, how many AI steps each case has, which model each step uses, how many input tokens a typical case has (system prompt + context + message) and how many output tokens, which part of the prompt repeats on every call (a caching candidate) and which part of the volume can wait hours (a batch candidate).

With my answers, show the full arithmetic:
1. Cost per case = (input tokens ÷ 1,000,000 × input price) + (output tokens ÷ 1,000,000 × output price), step by step.
2. Monthly cost with no optimization.
3. Monthly cost with prompt caching on the repeated part (explain the read and write multipliers I should verify).
4. Monthly cost if the volume that can wait goes through batches.
5. A variant with a smaller model on the simplest step, and which evaluation it would have to pass before I adopt it.

Use the prices I give you: [PRICES FROM ANTHROPIC’S PRICING PAGE, WITH THE DATE]. If I do not give them, leave the prices as variables and tell me to check them at platform.claude.com. End with the range (best and worst case) and the two assumptions that move the result the most.

What is the Agent SDK, and when do I use it instead of the API?

Building that loop by hand, with permissions, context and retries, is real work. Claude Code already has it solved, and the Agent SDK is exactly that: according to its documentation, the same tools, agent loop and context management that power Claude Code, programmable in Python and TypeScript. You install a package (claude-agent-sdk in Python, @anthropic-ai/claude-agent-sdk in TypeScript) and call a query function with a prompt and options: which tools it may use (read, edit, run commands, search the web), which permission mode, which system prompt, which MCP servers, hooks and subagents. It authenticates with your API key and is billed per token.

The decision, as a mental table:

• One API call (or a few chained): classify, extract, summarize, draft. Most small-business automations live here, and it is where Anthropic recommends starting: the simplest solution, with complexity only when needed.
• The API with your own tools (your own loop or the tool runner): when the agent queries your systems and you want full control over every turn and every permission.
• The Agent SDK: when the agent needs to read and edit files, run commands or search the web inside your own process: a contract reviewer, an internal assistant with access to your repository.
• Claude Code itself (an interactive session or a cloud routine, module 15): when there is a person at the keyboard or the job fits in a scheduled prompt against a repository.
• Claude Managed Agents (in beta as of October 2026): Anthropic runs the loop and the sandbox for you, with persistent sessions and scheduled runs, in exchange for state living on its servers.

How do I design my first agent for the business?

With a one-page design you can evaluate before paying for a single call. The most common case in hospitality and customer service: classify incoming messages and draft replies that a person approves. The pieces:

1. 1Inputs. The guest’s message, their booking data (from your system, not from the model) and the property’s context document, the bible from module 2.
2. 2Tools. Three or four: find the booking by code, read the bible, create a draft in your inbox, escalate to a person with the reason. None of them sends anything.
3. 3Models. Haiku 5.5 to classify (information, change, complaint, other) and Sonnet 5.5 or Opus 5.5 to draft; decided with evaluations.
4. 4Human checkpoint. Every draft waits for approval; booking changes, refunds and discounts are escalated. It is the human in the loop rule from module 9 and the best defense against prompt injection: a supposed guest can hide instructions in a message, but cannot approve their own draft.
5. 5Cost. Measure the tokens of a typical case in the Playground and apply the formula to the month’s volume, with caching for the bible and the system prompt.
6. 6{{Acceptance criteria|criterios-de-aceptacion}}. A hundred real messages with the correct category and an approved reply, as module 17 asks, to measure every version.

The other equally good starting point is invoice extraction with validation in code (module 8). In both cases the test from module 16 applies: if the process can be described as fixed steps, it is a workflow, not an agent, and it costs less.

Act as an engineer who designs systems on the Claude API for a small business. My business: [WHAT IT DOES, CITY, SIZE]. The process I want to automate: [DESCRIBE IT IN 3 TO 5 SENTENCES: what comes in, what must come out, who does it today and how long it takes]. Approximate volume: [N CASES PER MONTH]. Systems where the data lives: [LIST].

Deliver a one-page design with these sections:
1. Inputs: what the system receives in each case and where each piece of data comes from (the system, the context document or the message).
2. Fixed workflow or agent? If the steps can be fixed in advance, propose a step-by-step workflow; use an agent with a loop only if you justify why.
3. Tools: at most four, with name, purpose, parameters and what they return. None that sends, pays or deletes without approval.
4. Model per step: which one and why (classify, extract, draft), and which evaluation would confirm that a smaller model is enough.
5. Human review point: where the system stops, what the person sees, and what happens if they reject.
6. Cost estimation method: which tokens to measure in a typical case, which formula to apply, and which levers (caching, batches, smaller model) apply here.
7. Risks: personal data involved, prompt injection, what happens if the API or a system is down.
Do not invent prices: tell me what to look up on Anthropic’s pricing page.

The next module closes the loop: "Evals, cost control and failure modes", where today’s design gets measured with evaluations, watched in production and protected against the most common ways these systems fail.