快速入门

原文：Quickstart

一句话

快速上手 Agent SDK，构建能自主查找和修复代码错误的 AI 代理

什么时候翻这页

1. 首次使用 Agent SDK 需要快速设置环境
2. 想了解如何构建能自主工作的 AI 代理
3. 需要创建能自动分析代码并修复错误的工具
4. 想测试 Agent SDK 的基本功能

核心概念

1. Agent SDK：用于构建 AI 代理的软件开发工具包，支持 Python 和 TypeScript
2. 自主代理：能够独立执行任务，无需人工干预的 AI 系统
3. 工具（Tools）：代理可以执行的操作，如 Read、Edit、Glob、Bash 等
4. 权限模式（Permission modes）：控制代理行为的方式，决定是否需要人工批准
5. 查询（Query）：启动代理并与之交互的主要方法，返回异步迭代器

怎么做

1. 设置项目环境

   • 创建项目文件夹：mkdir my-agent 并 cd my-agent
   • 安装 SDK：
     • TypeScript: npm install @anthropic-ai/claude-agent-sdk
     • Python (uv): uv init 然后 uv add claude-agent-sdk
     • Python (pip): 创建虚拟环境后 pip install claude-agent-sdk
   • 设置 API 密钥：创建 .env 文件并添加 ANTHROPIC_API_KEY=your-api-key

2. 创建有错误的代码文件

   • 创建 utils.py 文件，包含故意设计的错误代码

3. 构建修复错误的代理

   • 创建代理脚本（agent.py 或 agent.ts）
   • 使用 query 函数启动代理，配置 allowedTools 和 permissionMode
   • 使用 async for 循环处理代理返回的消息流

4. 运行代理

   • 执行代理脚本并观察代理如何读取、分析和修复代码

5. 自定义代理

   • 添加额外功能（如 WebSearch、Bash）
   • 设置自定义系统提示
   • 调整权限模式以适应不同使用场景

命令 / 配置速查

安装命令：

• TypeScript: npm install @anthropic-ai/claude-agent-sdk
• Python (uv): uv init 然后 uv add claude-agent-sdk
• Python (pip): pip install claude-agent-sdk

环境变量：

• ANTHROPIC_API_KEY: Anthropic API 密钥
• CLAUDE_CODE_USE_BEDROCK=1: 使用 Amazon Bedrock
• CLAUDE_CODE_USE_ANTHROPIC_AWS=1: 使用 Claude Platform on AWS
• CLAUDE_CODE_USE_VERTEX=1: 使用 Google Vertex AI
• CLAUDE_CODE_USE_FOUNDRY=1: 使用 Microsoft Azure

运行命令：

• TypeScript: npx tsx agent.ts
• Python (uv): uv run agent.py
• Python (pip): python agent.py

代理配置选项：

• allowedTools: 允许使用的工具列表（如 ["Read", "Edit", "Glob"]）
• permissionMode: 权限模式（acceptEdits, dontAsk, auto, bypassPermissions, default）
• systemPrompt: 自定义系统提示

初学者易错点

1. 忘记设置 ANTHROPIC_API_KEY 环境变量会导致"API key not found"错误
2. 使用旧版本 Agent SDK 可能导致与 Claude Opus 4.7 不兼容，需升级到 v0.2.111 或更高版本
3. 在 Windows 上激活虚拟环境时可能需要执行 Set-ExecutionPolicy -Scope Process RemoteSigned
4. 权限模式设置不当可能导致代理无法执行必要的操作
5. 未正确安装依赖会导致模块找不到错误

相关词条

• agent-sdk/permissions 控制代理权限和批准流程
• agent-sdk/sessions 构建多轮代理并维护上下文
• agent-sdk/mcp 连接数据库、浏览器和外部系统
• agent-sdk/hosting 将代理部署到 Docker 和云平台
• agent-sdk/hooks 在工具调用前后运行自定义代码
• agent-sdk/streaming-vs-single-mode 流式与单次模式对比