Skip to main content
Build your first agent with the Claude Agent SDK and see how an AI that talks becomes an AI that does. You’ve used chatbots: you type a question and get an answer. A chatbot is useful for explanations and drafting text, but it cannot act on your environment. An agent is different: it can run commands, read and write files, and use tools on its own to complete tasks from start to finish. The key difference is not a “smarter” model — it’s that the agent has hands. Ask an agent what’s in your folder and it will run the command, read the output, and tell you what it finds. How does an agent actually get work done? Through a repeating cycle called the agent loop.
  • Think: the agent parses your instruction and plans the next step.
  • Act: the agent chooses a tool (e.g., Bash, Read, Write) and the SDK runs it.
  • Observe: the agent inspects the tool’s output.
  • Decide: determine if the job is complete or if the loop repeats.
A circular flowchart titled "One Loop: Think → Act → Observe → Decide" with four boxes labeled Think (read the prompt), Act (run a tool), Observe (read the result), and Decide (done, or loop again) connected by dashed arrows. Small buttons labeled "Bash", "Read", "Write" and a © KodeKloud watermark appear near the bottom.
You never write this loop yourself when using the Claude Agent SDK — it runs inside the library. The SDK streams each step back to you as structured messages so you can inspect and debug the agent in real time. Why use the SDK instead of calling the raw API?
  • Less boilerplate: the SDK manages message history and tool execution.
  • Built-in tooling: automatic tool invocation and secure whitelisting.
  • Streaming: inspect decision steps as they happen.
  • Cost & performance tracking: summary stats are returned at the end of every run.
Quick streaming example (the loop, tools, and cost/perf tracking are handled by the SDK):
Agent configuration and common imports You typically import these four items from the SDK:
  • query: runs a single agent turn and streams structured messages.
  • ClaudeAgentOptions: configuration object for the agent.
  • AssistantMessage: container for the assistant’s content and reasoning.
  • TextBlock: text content within assistant messages.
Also commonly used: asyncio for asynchronous execution and os for environment variables. Configure the agent by constructing a ClaudeAgentOptions object. The most important fields:
Setting permission_mode="acceptEdits" allows the agent to execute whitelisted tools without prompting each time. Use this in trusted automation contexts only.
A minimal, complete example that streams the assistant’s textual response blocks:
Understanding the streaming message types Because query streams structured messages rather than returning one string, you’ll receive different message types during a run. Inspect these types to follow the agent loop and debug:
A UI mockup titled "Not One String — a Stream of Messages" showing message cards labeled AssistantMessage, SystemMessage, and ResultMessage. The assistant card includes "Checking your AWS account..." and a ToolUseBlock, while the result card shows duration (13,375 ms), cost ($0.0105), tokens (945) and turns (3).
That final ResultMessage is why cost and performance tracking come for free: the SDK includes those numbers automatically at the end of each run. Concrete example: fetching AWS account information Task: ask Claude to run the AWS CLI command aws sts get-caller-identity and summarize the account details. You simply provide a plain-English instruction and the agent handles planning, tool invocation, observation, and summarization. Loop walkthrough:
  1. Think — Claude decides it needs the Bash tool.
  2. Act — Claude emits a ToolUseBlock instructing the SDK to run aws sts get-caller-identity.
  3. Observe — the SDK runs the command and provides the JSON output to Claude.
  4. Decide — Claude parses the JSON (account ID, user ID, ARN) and writes a clean summary.
You do not need to call the AWS SDK, parse JSON manually, or manage the loop: describe the goal and the agent executes it. Security and operational notes
Do not hardcode credentials. Keep your API keys and AWS credentials in environment variables or a secure secrets manager. Only enable permission_mode="acceptEdits" in trusted environments where the listed allowed_tools are safe to run.
Next steps and extensibility
  • Add more tools (e.g., Git, HTTP, file read/write) to allowed_tools to expand capabilities.
  • Use richer prompts or system instructions to guide multi-step plans.
  • Inspect SystemMessage logs and the ResultMessage summary to optimize cost and performance.
Links and references This article introduced the agent loop, how the Claude Agent SDK manages that loop for you, a minimal streaming example, and a concrete task example. From here you can iterate on prompts, add tools, and integrate agents into automation pipelines — the SDK handles the loop, streaming, and metrics for each run.

Watch Video

Practice Lab