When to Use Claude Agent SDK? Agent Harness Explained transcript

Claude Agent SDK is an exciting, but also a perplexing product. When you really understand what it is and how it's positioned, and that takes a second, you're left with this question of, "Okay, but then why would I ever use Claude Agent SDK when I could do all of that with the Claude code CLI?" Well, I'm going to explain how it's positioned, and then I'm going to answer that question. But, I'm going to start by explaining the term harness and what an agent harness is.

It's very much in vogue at the moment. Remember that an agent is where you have an LLM with tools in a loop to achieve a goal. That's the definition of an AI agent. Well, there's another way that you can describe an AI agent, too. It's also popular to say that an agent is where you have an LLM in a harness. An LLM plus a harness is an agent. In other words, all those other things, the tools, the loop, the goal, they form the harness.

And that's what we mean when we talk about an agent harness. And that is where Claude Agent SDK fits in. So, suppose you want to build your own AI agent. Well, you're going to have to call an LLM and put it in some kind of a harness. And you could do this just by making direct API calls to LLMs, but there are some frameworks, some libraries out there that make it easier for you. They do some of the job for you. And there's in fact a whole spectrum of different frameworks in terms of how much of a helping hand they give you.

So, on one end of the spectrum are lightweight agent frameworks. And these are things like OpenAI Agents SDK and Google ADK that make it easier to do things like calling tools. That's on one end. On the other end, there are batteries included agent harnesses that take care of everything for you. A opinionated setup out of the box. They handle tools, they've got built-in tools, they do planning, they have sub-agents, they compact the context, they deal with the sandbox and memory and all of that.

And they are sometimes called agent harnesses. And examples of agent harnesses include LangChain's deep agents and of course Claude agent SDK. And it makes sense to think of that when you want to get all the functionality that you might have in Claude code and be able to have that in an agent SDK that you can deliver. And perhaps the only special thing about the Claude agent SDK compared to the others is that you can only use it or at least you're only supposed to use it with Anthropic's models.

That's how it's designed to be used where things like LangChain deep agents can be used with any models. The Claude agent SDK itself is wonderfully simple to use as you will see there is just this query function that we will call and you iterate over the results. It's an SDK that lets you programmatically call Claude code. It's as simple as that. Here are some things that Anthropic says about it. They say, "Build AI agents that autonomously read files, run commands, search the web, edit code and more.

It gives you the same tools, agent loop and context management that power Claude code, programmable in Python and TS." And then just to make it super clear why you would use this instead of one of the lightweight frameworks, Anthropic puts on the site, "Look, the SDK includes built-in tools for reading files, running commands, editing code so your agent starts working immediately without you having to implement tool execution." All right, got it.

We understand why you would pick Claude agent SDK over a lightweight framework. But that kind of begs the question, "Okay, but why would you drive it from Python code when you can drive it from the Claude code CLI really effectively? It's got all of the tooling that you might want to handle permissions and how the loop should run and then you can just run it and ask your questions and interact that way. Why interact through Python code when you can interact effectively through the CLI?

And that's what I will show you right now and to do it we're going to go to the lab." And I'm in a repo called tutor and I'll put details in the description below and let me walk you through using the Claude agent SDK. So it's the same engine that powers Claude Code exposed through this one function, query, giving us a way to programmatically drive Claude Code through software rather than the CLI. So, in order to answer the question of why not just use the CLI, we are going to go through and build a language tutor.

Something It's again, something to try and teach me español, but you can have it teach you any language you want. Change it to Esperanto, change it to German, whatever you want, you just change this word here from Spanish to a language of your choice, ancient Greek perhaps, and you can learn that language. Let's now press ahead with the first step, the simplest possible agent loop to teach us a language using the Claude agent SDK.

It's as simple as this. I have a system prompt. You're speaking with a beginner at Spanish and having a friendly conversation to help them learn. And then query, that is the big function and we iterate over it. For message in query, we pass in the prompt all and then we see what comes next and we print it out. That is running right now and note that it doesn't need to use an API key because I'm logged in to Claude AI.

It can use your subscription account. If you make this into a product for other people to use, it would have to use your API key. And back we've got a response. That response came from running a Claude Code agent behind the scenes in a short loop that came up with that answer. And now on to step two, we start to give it capabilities. We're going to point it at a local folder we're going to create called data. And data is going to be where it will store all of its information, its knowledge about me.

We're going to give it a prompt. You are a warm, patient Spanish tutor and you're going to speak mostly in Spanish and keep memory of your learner as files in your working directory. The vocab I've learned, my grammar, my mistakes, notes about me, and the phases of my learning journey. And then we set up the Claude agent options with this prompt. We tell it we want it to be low reasoning Sonnet models. We give it access to read, write, and edit, and we say that it can edit these files.

We give it the current working directory, this data directory, and we say we don't want any settings from the local Claude code config. And that is all it should take. And then, I can say, "My name's Ed, and guess what I like? I like bananas." Okay, so I've now kicked that off, and you can see it's just this very simple loop, again with query as the keyword. And what's happening now is that basically, Claude code is running behind the scenes.

It's been programmatically launched. It's running. It's got access to the tools that it has here, the file tools to read and write and edit. There's this data directory that's been created. It will hopefully write some stuff in there as it thinks about how to respond to the fact that apparently, I like bananas. And there we go, it's replied. It's happy with the way that I did it. Let's look in here, and indeed, it's created a bunch of files, too.

And you can check out the files that it left itself, the notes that it recorded, including the fact that I know the word for bananas. And then, I've got some notes here about the fact that it can handle compacting your context as it builds up, something you get in the package that you wouldn't get with a lightweight framework. And then, there's stuff here so that you can stream back if you wish to. It's a little bit more verbose here.

There's a bit of code here to to test what kind of thing is coming back and stream it as it needs, show when it's using different tools. So, we can see that, but it just gives you a sense that you can do the kinds of things you might do with a lightweight framework, but you can do it operating all of Claude code. And this is showing, and there you see it wrote the vocab at the end of it. We see it using its tools, running its agent loop, responding to me, editing its notes about me right here.

Lots going on as Claude code runs programmatically. Okay, now we're going to kick it up a notch. We're going to create another agent, which is going to be an agent that can look at the overall learning journey and can rewrite, update, tune the learning journey based on mistakes I've made, based on the vocab that I'm learning. It's going to be like a second agent, and it's not as much It's not like a sub agent, like when you have Claude code just delegate something off and then come back again.

This is going to be like another agent that's running that we can programmatically decide when it runs. So, this is a interesting different dimension that we have more control over because we're writing it programmatically. Let's see. So, we're saying here, "You're a Spanish curriculum coach working quietly behind the scenes. You read in the learner's files and then you prepare the progressive plan in phases." So, this will be continually refining the learning journey phases, and that's something that our main agent is going to be reading.

So, this can be happening in parallel. So, we set up those options. I've got like this function, refine journey, right here, and then we can kick it off. So, I'm going to kick off a task to be having my agent refining the journey. And meanwhile, I'm going to tell the main agent, "Oh, I've got two dogs and they're called Mango and Salsa," which is not true, but it's just something to put out there. And uh we will then let it think about that.

And meanwhile, the coach will be running at the same time. So, there's now two different Claude code processes going on in parallel. One of them is answering my question. How lovely. Uh Mango and Salsa, I love those names. Uh that is all running. Uh you see I'm getting better with my Spanish. That's all running. But meanwhile, at the same time, the journey is also running, too. So, this is a bit akin to starting two different terminals and running Claude code twice and having them run on tasks independently and yet operating against the same files.

So, that's happening, and you can see that it's all going on right now, and I'll see you in a second when everything completes. So, the conversation finished after 33 seconds and then the coach was done after 55 seconds. They were working in parallel and presumably this learning journey phases by I've got a preview of this. This is something that's now been written by the the learning coach. It's written quite a lot.

So, that's been developed and that will now automatically be used by the tutor in the future. So, that's pretty cool and yeah, it's going to show the text right there. So, that is now showing a more sophisticated system that we've put together and we are orchestrating these different agents using code. And now I've taken the code we've gone through and I put it into tutor core.py, a module with just the most recent code and then I've also got an app that organizes it into a Gradio app and there's some styling in tutor style and this will allow me to launch a Gradio app to do much the same thing.

I will launch it right now and then we will take a look at it. And here it is. This is the Gradio app. Gradio is so easy to work with. I've also I deleted the data directory so we start fresh. And let me start by saying, "Hola." Let's see what we get back. We're talking to our Claude agent. "Hola." Uh okay. Come chilling with us. All right. So, let's see if I can handle this live. Let's give it a shot. Let it do its thing.

Uh it says, "You're so Claude." It did that so it knows who he is and I'll definitely say, "Estoy muy bien." There we go. We'll see how we do. Look on the right. We're at level one. We've got 65 out of 100 to get to level two and we're seeing some of the recent words that we've used. Okay, well, it's asked me what I like and I think I know what I like. We can give it the same answer. We can make sure that it's quite clear on my preferences.

And look what just happened. The learning journey just appeared on the right. That's been going in the background. The other agent has been working on the learning journey. And meanwhile, the progress just updated, the recent words just updated. We have a real language tutor here that's on the move with two different agents working on it. And conveniently, the learning journey has when it was updated, and it's got lots of useful stuff in here.

It's asking me what else do I like to eat? And I don't think I'm going to tell it what I like to eat. I think I'm going to tell it >> [laughter] >> You knew I was going to say that. Uh let's give it something to think about. See how it does that. Uh okay, there we go. And uh hopefully, this will update with those words, and the learning journey will update. It's set so that the learning journey will update every few times that we chat with it, so that it's not like every time that it's changing the learning journey, but as there's something more to say.

But of course, the progress and the words updates frequently as it's running its tools behind the scenes. So, this is really giving you that sense that we have Claude Code running behind the scenes, and we're driving it programmatically. And now, it's time to answer that big question. So, obviously, many reasons why you might choose to have a framework like Claude Agent SDK over a lightweight agent framework. But why would you choose it over just using the Claude Code CLI?

Well, it might now be obvious to you, but here are three reasons from my perspective. The first reason is the one that Anthropic really pushes home in their docs, which is that if you've worked interactively with Claude Code on some process, you can then productionize it with Claude Agent SDK. I'm not sure how often I would need to do that myself. I can see maybe with a CICD pipeline, it might be useful. But that's certainly one of their stated reasons.

But the second reason is the one that really nails it for me. It's about if you want to build your own product, like maybe a language tutor, and you want to have it powered by the Claude agent, the agent that sits behind Claude Code. You love using Claude Code. You love that harness, and you want the power of that harness as the brains behind your product. That's a reason to use the Claude Agent SDK in your product. And the third example is if you have a sophisticated Claude code setup where you want to be able to have, let's say, multiple agents will have slightly different prompts, and you want those prompts to be programmatically constructed, like having the word language passed in, like Spanish, but something more complicated than that.

And you could see how trying to stitch all that together every time in the Claude code CLI might be quite a pain, particularly if you're creating lots of agents in different terminals and so on. Well, of course, this gives you a way to programmatically configure a complex Claude code setup, and that makes total sense. I don't think it's as common, but I can see how it might be very useful. Well, that's my take anyway.

If you have a different take or other use cases, please put them in the comments below, and I look forward to reading them. And if you enjoyed this, then please do like and subscribe. That's the way I know you're really there and that you want me to keep making these, and I will. And I hope to see you very soon for another video, by which point I'll hopefully be speaking fluent Spanish.