Why This Matters#

Until now, we’ve used Claude Code interactively — entering commands and getting responses. But what if you need to:

• 🔄 Run Claude Code from your scripts automatically
• 📊 Get results in a structured format (JSON)
• 🏭 Embed Claude Code in a data processing pipeline
• 🤖 Create your own agent based on Claude Code

Agent SDK is a set of tools for programmatic control of Claude Code. It’s available as:

• CLI mode (claude -p) — for scripts and command line
• Python SDK — for Python programs
• TypeScript SDK — for TypeScript/JavaScript programs

Basic Usage: CLI Mode#

Running with a Prompt#

The simplest way — the -p (or --print) flag:

# Ask a question about the project
claude -p "What does the file auth.py do?"

# The result is printed to the terminal and Claude exits

Unlike normal mode, -p works non-interactively — Claude completes the task and exits. This is ideal for scripts.

Getting a JSON Response#

claude -p "Describe the project structure" --output-format json

The result will contain:

{
  "result": "Project description...",
  "session_id": "abc123",
  "usage": { "input_tokens": 500, "output_tokens": 200 }
}

Structured Output by Schema#

You can specify what format you want the response in:

claude -p "Find all functions in auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

The result will strictly follow your schema:

{
  "structured_output": {
    "functions": ["login", "logout", "verify_token", "refresh_token"]
  }
}

Streaming Output#

To receive the response as it’s being generated:

claude -p "Write a detailed README" \
  --output-format stream-json \
  --verbose \
  --include-partial-messages

Tool Management#

Allowing Specific Tools#

# Allow only reading, editing, and command execution
claude -p "Fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

Continuing a Conversation#

# First request
claude -p "Find the bug in auth.py" --output-format json > result.json

# Continue from the same point
claude -p "Now fix this bug" --continue --output-format json

Script Examples#

Script: Review All Files in a Folder#

#!/bin/bash
# review-all.sh — checks each file for errors

for file in src/*.py; do
  echo "Reviewing: $file"
  claude -p "Review the file $file for errors and security issues. Give a brief report." \
    --allowedTools "Read" \
    --output-format json | jq -r '.result'
  echo "---"
done

Script: Generate Documentation#

#!/bin/bash
# generate-docs.sh — creates documentation for the project

claude -p "Analyze all files in src/ and create a DOCUMENTATION.md file describing each module, its functions, and usage examples." \
  --allowedTools "Read,Write" \
  --output-format json | jq -r '.result'

Python Example (Using subprocess)#

import subprocess
import json

def ask_claude(prompt, tools="Read"):
    """Runs Claude Code and returns the result."""
    result = subprocess.run(
        ["claude", "-p", prompt,
         "--allowedTools", tools,
         "--output-format", "json"],
        capture_output=True, text=True
    )
    return json.loads(result.stdout)

# Usage
response = ask_claude("What does the main() function in app.py do?")
print(response["result"])

The agent-sdk-dev Plugin#

The Claude Code repository includes an agent-sdk-dev plugin that helps create projects with Agent SDK:

The /new-sdk-app Command#

claude --plugin-dir ./plugins/agent-sdk-dev
> /agent-sdk-dev:new-sdk-app my-agent

This command:

1. Asks for the language (Python or TypeScript)
2. Asks for the agent type (coding, business, custom)
3. Creates all necessary files
4. Installs the latest SDK version
5. Verifies the setup

Verifier Agents#

The plugin includes agents for verifying correct setup:

• agent-sdk-verifier-py — for Python projects
• agent-sdk-verifier-ts — for TypeScript projects

When to Use Agent SDK#

Lesson Summary#

• Agent SDK lets you use Claude Code programmatically, not in interactive mode
• The claude -p flag runs Claude Code in non-interactive mode
• --output-format json returns a structured result
• --json-schema lets you specify the exact response format
• --allowedTools restricts available tools
• --continue lets you continue a previous conversation
• The agent-sdk-dev plugin helps create projects with Agent SDK
• Full SDK packages are available for Python and TypeScript