{"slug": "from-one-agent-to-the-claude-agent-sdk", "title": "From One Agent to the Claude Agent SDK", "summary": "Anthropic released the Claude Agent SDK, enabling developers to build autonomous AI agents that can use tools and make decisions without human intervention. The SDK allows Claude to operate in a loop, reasoning, acting, and observing results until a goal is met, moving beyond simple text generation to agentic systems that can handle complex, multi-step tasks.", "body_md": "You have watched Claude Code work. You give it a sentence, and it reads your files, runs a command, fixes the failing test, and tells you what it changed, all on its own while you watch. Now picture that same ability with nobody at the keyboard, running inside your own software, set off by a webhook or a nightly job instead of a person.\n\nThat is what the Claude Agent SDK is for, and it is where this article is headed. Meet it cold, though, and it is just a pile of unfamiliar options. Meet it after the handful of ideas it stands on, and it feels inevitable, the obvious tool for a problem you already understand.\n\nSo we are going to climb, quickly at first. What an agent actually is, what the word agentic really means, why one agent is sometimes not enough, and what an agent SDK gives you that raw API calls do not. Each idea sets up the next, and the final step is the Claude Agent SDK itself. By the end you will not just know what it does. You will know why it is shaped the way it is.\n\nStrip away the noise and an agent is a small idea. It is a language model that can choose to act, not just talk.\n\nA plain model reads your prompt and writes a reply. That is the whole of it, text in and text out. An agent wraps that same model in a loop and hands it a set of tools, real actions it can take in the world, such as reading a file, searching the web, or running a command. Now the model can do more than answer. It can decide that answering well means looking something up, take that action, see what comes back, and carry on.\n\nPicture asking a plain model to summarise a file it has never seen. It cannot. The text is not in the prompt, and it has no way to fetch it. Give the same model one tool, the ability to read a file, and everything changes. It works out that it needs the contents, reads them, and then summarises. Same model, but now it can reach past the conversation and touch your actual work.\n\nThat is the entire foundation. A model that can pick up tools. Hold onto it, because every rung above is built on this one move.\n\nGive a model tools and it can act. Let it decide for itself which action comes next, and it becomes agentic. That single shift is the whole game.\n\nThere are two ways to drive a tool-using system. The first is a script you write by hand, do this, then this, then that, in the same fixed order every time. It is predictable and cheap, and it can only ever handle the cases you thought of in advance. The second is to let the model look at where things stand and choose the next step itself, so it might skip a step, repeat one, reorder them, or stop early. That is an agentic system, and its routing is reasoned rather than wired.\n\nThe shape it runs in is a loop, not a line. The agent perceives the current state, reasons about what to do next, and acts by using a tool. Then it perceives the result of that action and goes round again, until it decides the goal is met. Reason, act, observe, repeat.\n\n*Figure 1. The agentic loop. The agent reasons, acts with a tool, observes the result, and goes round again until the goal is met.*\n\nTake the file summary from a moment ago. The agent reasons that it cannot summarise what it has not read, acts by calling the read tool, observes the contents coming back, reasons that it now has enough, and writes the summary. Nobody scripted that order. The agent chose it from the goal and from what it saw along the way. Change the task and the path changes with it, and that flexibility is exactly what makes an agentic system worth the trouble.\n\nA single agent with a good set of tools takes you a long way, further than most people expect. The trouble starts when you keep piling on. Too many tools, several unrelated jobs at once, or an accuracy that plateaus no matter how you tune the prompt. At some point one generalist begins to strain.\n\nThe instinct then is to split the work across several specialised agents, each with its own role, tools, and prompt, coordinating to finish a task that one agent handles poorly. A research assistant is the clean example. Answering needs both web research and careful calculation, which pull in different directions, so it divides neatly into a research agent that searches and a math agent that computes, with a coordinator deciding who works when.\n\nThe catch is that more agents are not automatically better, and this is worth saying plainly, because the industry spent a while believing otherwise. More agents mean more model calls and higher cost, and a 2026 Stanford study by Tran and Kiela found that under an equal thinking-token budget, a single agent matches or beats a multi-agent system on multi-hop reasoning, because every handoff between agents is a chance to lose information. The honest rule is to stay with one agent while it performs well on your evaluations, and to reach for several only once the task types are genuinely distinct and a single agent stops improving.\n\nWhen you do split, the arrangement matters more than any prompt. Two questions settle most of it. How context should be shared, with every agent working from one history or each keeping its own. And how control should be organised, with one coordinator directing the work or the agents handing off among themselves. Those two choices give you the common shapes.\n\n*Figure 2. Four ways to arrange a team of agents, a central supervisor, a free network, nested hierarchies, and a parallel fan-out.*\n\nA supervisor is the workhorse, one coordinator that holds the state, routes each turn to the right specialist, and decides when to stop, which keeps the whole system traceable. A network drops the central boss and lets every agent hand off to any other, the most flexible arrangement and the easiest to turn into a mess. A hierarchy nests supervisors, giving each team its own coordinator under a top one, for systems too large for a single supervisor. And a parallel fan-out sends the task to several workers at once and merges their results, which is where multi-agent genuinely beats a single agent, since independent sub-tasks run at the same time rather than one after another.\n\nSomething has to sit at the centre and decide who does what, and when, and that coordinator can itself be scripted or agentic. A scripted coordinator runs the same fixed order every time. An agentic one reads each result and chooses the next move, so it can skip a worker, call one twice, or stop early. It is the same reason, act, observe loop from before, raised one level to route whole agents rather than single tools. The full treatment of these shapes is Part two, so for now just hold the map.\n\nNotice how much machinery has quietly piled up. A loop that runs until the goal is met. A way to define tools and hand them to the model. Logic that reads each result and routes the next step. Guardrails so nothing loops forever. Coordination once more than one agent is involved. You could build all of it by hand on top of raw API calls, and people did, and it is a great deal of fiddly, error-prone plumbing that has nothing to do with your actual problem.\n\nAn agent SDK is the library that gives you that plumbing for free. It runs the loop, manages the tools, handles the routing and the guardrails, and lets you spend your attention on the job rather than the scaffolding. The landscape has settled into a handful of real options, and it helps to know their shapes.\n\n*Figure 3. The current landscape. LangGraph, CrewAI, the OpenAI Agents SDK, and the Microsoft Agent Framework coordinate teams, while the Claude Agent SDK makes one agent exceptionally strong.*\n\nLangGraph models a system as a graph with conditional edges, where a router picks the next node from shared state, which suits complex branching and inspectable runs. CrewAI offers a hierarchical process where a manager agent delegates to a crew, alongside a separate primitive for fixed sequences, so it covers both the scripted and the agentic style. The OpenAI Agents SDK works through handoffs, where one agent transfers control to a named specialist, which fits clean triage and tiered routing. And the Microsoft Agent Framework, released in October 2025 as the successor that unifies AutoGen and Semantic Kernel, offers sequential, handoff, and other orchestrations across one runtime.\n\nOne option sits deliberately apart, and it is where we have been heading all along. The Claude Agent SDK does not try to coordinate a crowd of peers. It aims to make a single agent extraordinarily capable, reasoning about which tools to call, chaining them, and spawning isolated subagents for parallel work, with the deepest Model Context Protocol integration of any framework. A supervisor of the kind we just sketched is something you compose yourself, by running several sessions and routing between them in your own code. It belongs in the picture as a different shape, a strong single agent leaning on tools and subagents, rather than as one more coordinator of crowds.\n\nHere is the reward for the climb. Everything you now understand, the loop, the tools, the reasoned routing, is exactly what the Claude Agent SDK packages, wrapped around the same engine that drives Claude Code.\n\nThe mental model is one engine and two doors. The Claude Code command line you have used and the SDK reach the same intelligence through different entrances. One is driven by a person at a prompt. The other is driven by your code. That is the whole point of the SDK, to put Claude Code’s agentic power inside your own applications, running on its own in a pipeline, a background job, or a scheduled task, with no human in the loop.\n\nYour entry point is a single function, query. It helps to picture hiring a contractor. You hand over a job description, which is the prompt, and the rules and equipment, which are the options, and the options set the model and, above all, the tools the agent may use. Unlike an ordinary API call that returns one finished answer, query returns a stream of messages, so you watch the agent reason and act step by step rather than waiting in the dark.\n\nA small summariser shows the shape.\n\n``` python\nfrom claude_agent_sdk import query, ClaudeAgentOptionsoptions = ClaudeAgentOptions(allowed_tools=[\"Read\"])   # pre-approve the Read toolasync for message in query(prompt=\"Summarise api-guide.md\", options=options):    print(message)   # a stream of the agent's steps, not one final answer\n```\n\nThat stream is the SDK running the agentic loop for you, the very loop from earlier in this article. The agent perceives the goal, reasons that it must read the file first, acts by calling the Read tool, perceives the contents, and only then writes the summary. You did not write the loop. The SDK ran it, which is the difference between building an agent and building on top of one.\n\nThe loop is the engine, and an engine on its own does nothing. What the agent reaches for on each turn of that loop is a tool, and how freely it may reach is a permission. Those are the two dials you actually control, one setting what the agent can touch and the other setting how freely it may touch it. What comes next is those two dials, one at a time.\n\nTools are the specific capabilities you hand an agent, and they sort neatly by how much they can do. Read-only tools, Read, Glob, and Grep, observe the file system without changing anything, the agent’s eyes. Modification tools, Edit and Write, change or create files. The execution tool, Bash, runs shell commands and is the single most powerful, since it can do almost anything on the machine. Web tools, WebSearch and WebFetch, reach the internet. And specialised tools, Task and Skill, let the agent spawn subagents and call skills.\n\n*Figure 4. The built-in tools grouped by how much they can do, from safe observation through file changes to Bash, which can do almost anything.*\n\nThe guiding principle is least privilege, giving an agent only the power its job genuinely needs, which draws a safe boundary around what it can do. One detail is worth getting right, because it is a common trap. The allowed_tools option is an auto-approve list, not a lock. Tools you list run without asking, and tools you leave off are not removed, they simply fall through to the permission checks below. To truly withhold a capability you reach for disallowed_tools or the permission controls, not allowed_tools on its own.\n\nHaving tools is one thing. Deciding how freely the agent may use them is another, and the SDK gives you layered control. Every tool call passes through checks in order, hooks first, then rules that explicitly allow or deny, then the permission mode, and finally a callback in your own code for anything still undecided. The mode is the one to learn first, since it sets the agent’s overall autonomy, and a traffic light is the easiest way to hold it.\n\n*Figure 5. The permission modes as traffic lights, from approving every action to full trust, with plan set apart because it only proposes.*\n\nThe default mode is the red light, where your code approves every action and keeps full veto power. The acceptEdits mode is the yellow light, waving through routine file edits while still pausing before powerful actions such as shell commands. The bypassPermissions mode is the green light, full autonomy to use any allowed tool without prompting, which suits a trusted, sandboxed environment such as a CI pipeline. And the plan mode sits off to the side, running no tools at all, letting the agent study a problem and propose a step-by-step plan without changing anything, asking a clarifying question first if it needs to.\n\nMatch the mode to the trust. Red while you are developing and watching closely. Yellow for everyday file work. Green only where a mistake is contained. Plan when you want the thinking before any of the doing.\n\nLook back down the climb. An agent is a model that can use tools. It becomes agentic when it chooses its own next step, running a reason, act, observe loop. One agent handles most things, and only when the work genuinely splits do you reach for several, arranged as a supervisor, a network, a hierarchy, or a parallel fan-out. An agent SDK hands you all of that machinery so you build on the loop instead of rebuilding it. And the Claude Agent SDK takes a clear position in that landscape, making a single agent exceptionally capable through tools, subagents, and deep MCP integration, driven from your own code through one streaming query call, with tools grouped by power and permission modes that set exactly how much rope the agent gets.\n\nThat is the map. Part two puts it to work, composing a real supervisor over several Claude Agent SDK sessions and turning these ideas into code you can run.\n\n*Everything here was checked against the current Claude Agent SDK documentation at the time of writing. Since the SDK moves quickly, the docs at docs.claude.com are the source of truth if anything has shifted.*\n\n[From One Agent to the Claude Agent SDK](https://pub.towardsai.net/from-one-agent-to-the-claude-agent-sdk-8076a5c54a89) was originally published in [Towards AI](https://pub.towardsai.net) on Medium, where people are continuing the conversation by highlighting and responding to this story.", "url": "https://wpnews.pro/news/from-one-agent-to-the-claude-agent-sdk", "canonical_source": "https://pub.towardsai.net/from-one-agent-to-the-claude-agent-sdk-8076a5c54a89?source=rss----98111c9905da---4", "published_at": "2026-07-18 05:42:44+00:00", "updated_at": "2026-07-18 05:56:33.860440+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "ai-tools", "large-language-models", "ai-products"], "entities": ["Anthropic", "Claude Agent SDK", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/from-one-agent-to-the-claude-agent-sdk", "markdown": "https://wpnews.pro/news/from-one-agent-to-the-claude-agent-sdk.md", "text": "https://wpnews.pro/news/from-one-agent-to-the-claude-agent-sdk.txt", "jsonld": "https://wpnews.pro/news/from-one-agent-to-the-claude-agent-sdk.jsonld"}}