EnglishРусский中文

为什么需要这个#

到目前为止，我们一直在交互式地使用 Claude Code——输入命令并获取回答。但如果你需要：

  • 🔄 从自己的脚本自动运行 Claude Code
  • 📊 获取结构化格式（JSON）的结果
  • 🏭 将 Claude Code 集成到数据处理流水线中
  • 🤖 基于 Claude Code 创建自己的代理

Agent SDK 是一组用于编程控制 Claude Code 的工具。它提供以下形式：

  • CLI 模式（claude -p）——用于脚本和命令行
  • Python SDK ——用于 Python 程序
  • TypeScript SDK ——用于 TypeScript/JavaScript 程序

基本用法：CLI 模式#

使用提示运行#

最简单的方式——使用 -p（或 --print）标志：

# 询问关于项目的问题
claude -p "auth.py 文件是做什么的？"

# 结果输出到终端，Claude 随后退出

与普通模式不同，-p 以非交互式方式工作——Claude 完成任务后退出。这非常适合脚本使用。

获取 JSON 响应#

claude -p "描述项目结构" --output-format json

结果将包含：

{
  "result": "项目描述...",
  "session_id": "abc123",
  "usage": { "input_tokens": 500, "output_tokens": 200 }
}

按模式的结构化输出#

你可以指定希望获取的响应格式：

claude -p "查找 auth.py 中的所有函数" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

结果将严格按照你的模式：

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

流式输出（Streaming）#

要在生成时获取响应：

claude -p "写一个详细的 README" \
  --output-format stream-json \
  --verbose \
  --include-partial-messages

工具管理#

允许特定工具#

# 只允许读取、编辑和执行命令
claude -p "修复 auth.py 中的 bug" --allowedTools "Read,Edit,Bash"

继续对话#

# 第一个请求
claude -p "查找 auth.py 中的 bug" --output-format json > result.json

# 从上次的位置继续
claude -p "现在修复这个 bug" --continue --output-format json

脚本示例#

脚本：检查文件夹中的所有文件#

#!/bin/bash
# review-all.sh — 检查每个文件的错误

for file in src/*.py; do
  echo "检查中：$file"
  claude -p "检查文件 $file 是否有错误和安全问题。给出简要报告。" \
    --allowedTools "Read" \
    --output-format json | jq -r '.result'
  echo "---"
done

脚本：生成文档#

#!/bin/bash
# generate-docs.sh — 为项目创建文档

claude -p "分析 src/ 中的所有文件并创建 DOCUMENTATION.md 文件，描述每个模块、其函数和使用示例。" \
  --allowedTools "Read,Write" \
  --output-format json | jq -r '.result'

Python 示例（使用 subprocess）#

import subprocess
import json

def ask_claude(prompt, tools="Read"):
    """运行 Claude Code 并返回结果。"""
    result = subprocess.run(
        ["claude", "-p", prompt, 
         "--allowedTools", tools,
         "--output-format", "json"],
        capture_output=True, text=True
    )
    return json.loads(result.stdout)

# 使用
response = ask_claude("app.py 中的 main() 函数是做什么的？")
print(response["result"])

agent-sdk-dev 插件#

Claude Code 仓库中有一个 agent-sdk-dev 插件，帮助创建使用 Agent SDK 的项目：

/new-sdk-app 命令#

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

此命令会：

  1. 询问语言（Python 或 TypeScript）
  2. 询问代理类型（编码、业务、自定义）
  3. 创建所有必要的文件
  4. 安装最新版本的 SDK
  5. 验证设置

验证代理#

插件包含用于检查设置是否正确的代理：

  • agent-sdk-verifier-py ——用于 Python 项目
  • agent-sdk-verifier-ts ——用于 TypeScript 项目

何时使用 Agent SDK#

任务 方法
关于代码的一次性问题 普通 claude
CI/CD 中的自动检查 claude -p
处理多个文件 使用 claude -p 的 Bash 脚本
集成到自己的应用 Python/TypeScript SDK
创建自定义代理 Agent SDK

课程总结#

  • Agent SDK 允许以编程方式使用 Claude Code，而不是交互模式
  • claude -p 标志以非交互模式运行 Claude Code
  • --output-format json 返回结构化结果
  • --json-schema 允许指定精确的响应格式
  • --allowedTools 限制可用工具
  • --continue 允许继续之前的对话
  • agent-sdk-dev 插件帮助创建使用 Agent SDK 的项目
  • 完整的 SDK 包可用于 Python 和 TypeScript