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.