claude_agent_sdk 功能简介

1. 概述

Claude Agent SDK是Anthropic 官方推出 的 AI agent开发库，支持Python/TypeScript双语言，可快速构建能够调用工具、skill、hook等能力的生产级 AI 智能体，复用 Claude Code 的核心工具、智能体循环与上下文管理能力，开箱即用无需从零实现工具逻辑

核心特性

环境要求：Python 3.10+

2.如何安装

环境要求：Python 3.10+

认证要求：Anthropic API Key（或支持第三方平台：Amazon Bedrock、Google Vertex AI 、Microsoft Azure）

2.1 项目初始化

bash 复制代码

# 1. 创建项目目录
mkdir my-agent && cd my-agent

# 2. 安装 SDK（二选一）
# 方法一：pip（兼容所有环境）
python3 -m venv .venv
source .venv/bin/activate
pip3 install claude-agent-sdk

# 方法二：uv（更快的包管理器，自动管理虚拟环境）
uv init && uv add claude-agent-sdk

2.2 配置 API Key

1.从 Claude Console 获取 API Key

2.在项目根目录创建 .env 文件：

ini 复制代码

# 基础配置（Anthropic 官方 API）
ANTHROPIC_API_KEY=your-api-key

# 第三方平台配置（可选）
# Amazon Bedrock：启用后使用 AWS 凭证
# CLAUDE_CODE_USE_BEDROCK=1
# Google Vertex AI：启用后使用 GCP 凭证
# CLAUDE_CODE_USE_VERTEX=1
# Microsoft Azure：启用后使用 Azure 凭证
# CLAUDE_CODE_USE_FOUNDRY=1

2.3 官方入门示例：自动检测并修复代码 Bug

步骤 1：创建带 Bug 的测试文件

在项目目录下创建 utils.py，包含两个已知 Bug：

python 复制代码

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)  # 空列表时触发除零错误

def get_user_name(user):
    return user["name"].upper()  # user 为 None 时触发类型错误

步骤 2：编写智能体代码 `agent.py`

python 复制代码

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    AssistantMessage,
    ResultMessage
)

async def main():
    # 智能体循环：流式输出执行过程
    async for message in query(
        # 任务指令：让智能体自动排查并修复 Bug
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # 允许使用的工具
            permission_mode="acceptEdits",  # 自动批准文件编辑
            system_prompt="You are a senior Python developer. Follow PEP 8 style guidelines.",  # 自定义角色
        ),
    ):
        # 格式化输出执行过程
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(f"🤔 智能体思考：{block.text}")
                elif hasattr(block, "name"):
                    print(f"🔧 执行工具：{block.name}")
        elif isinstance(message, ResultMessage):
            print(f"✅ 任务完成：{message.subtype}")

if __name__ == "__main__":
    asyncio.run(main())

步骤 3：运行智能体

复制代码

python3 agent.py

执行结果

智能体将自动完成以下操作：

调用 Read 工具读取 utils.py 内容
分析代码并识别两个崩溃 Bug
调用 Edit 工具修改文件，添加错误处理
输出执行结果

修复后的 utils.py：

python 复制代码

def calculate_average(numbers):
    if not numbers:  # 处理空列表场景
        return 0.0
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)

def get_user_name(user):
    if user is None or "name" not in user:  # 处理 None 和缺少字段场景
        return "Unknown User"
    return user["name"].upper()

3.核心功能模块

3.1 内置工具集

文件操作工具（Read/Edit/Glob/Grep）

功能说明：用于读取、修改、检索文件，是代码自动化的核心工具。

示例代码：

python 复制代码

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="""
        1. 查找项目中所有 .py 文件
        2. 读取 utils.py 内容
        3. 为所有函数添加类型注解
        4. 保存修改后的文件
        """,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob", "Grep"],
            permission_mode="acceptEdits",
            cwd_override="./my-agent"  # 限制工作目录
        ),
    ):
        # 输出执行日志
        if hasattr(message, "content"):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)

asyncio.run(main())

工具说明：

工具名	功能	适用场景
Read	读取文件内容	代码分析、文档解析
Edit	修改文件内容	代码修复、自动生成
Glob	按规则匹配文件路径	批量文件处理
Grep	按关键词检索文件内容	代码片段查找、问题定位
Bash	终端执行工具	执行系统终端命令，支持自动化测试、依赖安装等操作。
WebSearch/WebFetch	网络工具	支持网络搜索和网页内容提取，用于获取外部信息
AskUserQuestion	人机交互工具	在执行过程中向用户发起提问，获取关键输入后继续执行

3.2 精细化权限控制

功能说明：通过权限模式和工具白名单，控制智能体的操作范围和执行权限，保障安全性。

allowed_tools 内置工具名
permission_mode
- acceptEdits 自动批准文件编辑和常见文件系统命令
- dontAsk 拒绝所有未在 allowed_tools 中声明的操作
- default 需要通过 canUseTool 回调处理审批
- bypassPermissions 无权限检查，直接执行所有工具

3.3 生命周期钩子

功能说明：在智能体执行的关键节点注入自定义逻辑，实现日志记录、权限校验、结果处理等扩展功能。

支持的钩子类型：

PreToolUse：工具执行前拦截
PostToolUse：工具执行后回调
SessionStart：会话开始时执行
SessionEnd：会话结束时执行
StopHook：任务停止时执行

示例代码：

python 复制代码

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    PreToolUseHook,
    PostToolUseHook
)

# 工具执行前钩子：日志记录 + 危险命令拦截
def pre_tool_use(tool_name, tool_args):
    print(f"[钩子] 准备执行工具：{tool_name}，参数：{tool_args}")
    # 拦截危险的 Bash 命令
    if tool_name == "Bash" and "rm -rf" in tool_args.get("command", ""):
        raise PermissionError("禁止执行危险命令：rm -rf")
    return True  # 返回 True 允许执行，False 拦截

# 工具执行后钩子：结果上报
def post_tool_use(tool_name, result):
    print(f"[钩子] 工具执行完成：{tool_name}，结果：{result[:100]}...")

async def main():
    async for message in query(
        prompt="执行 `ls -l` 查看目录内容",
        options=ClaudeAgentOptions(
            allowed_tools=["Bash"],
            permission_mode="acceptEdits",
            hooks=[
                PreToolUseHook(pre_tool_use),
                PostToolUseHook(post_tool_use)
            ]
        ),
    ):
        if hasattr(message, "content"):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)

asyncio.run(main())

3.4 子代理（Subagents）

功能说明：将复杂任务拆分为多个子任务，由专门的子代理执行，实现多角色协作，提升任务执行效率和准确性。

示例代码：

ini 复制代码

import asyncio
from claude_agent_sdk import (
    ClaudeAgent,
    ClaudeAgentOptions
)

async def main():
    # 初始化主代理
    main_agent = ClaudeAgent(
        api_key="your-api-key",
        model="claude-3-7-sonnet-latest"
    )

    # 创建子代理 1：代码审查专家
    code_reviewer = main_agent.create_subagent(
        name="CodeReviewer",
        description="专业代码审查专家，负责检查语法错误、性能问题和安全漏洞",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            permission_mode="acceptEdits",
            system_prompt="严格遵循 PEP 8 规范和 Python 安全开发标准"
        )
    )

    # 创建子代理 2：文档生成专家
    doc_generator = main_agent.create_subagent(
        name="DocGenerator",
        description="技术文档生成专家，负责生成清晰、规范的 API 文档和使用手册",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit"],
            permission_mode="acceptEdits",
            system_prompt="文档需包含功能说明、参数列表、示例代码和注意事项"
        )
    )

    # 主代理拆分任务并委派
    print("=== 主代理：开始执行复杂任务 ===")
    # 子代理 1 执行代码审查
    review_result = await code_reviewer.query(
        prompt="审查项目中所有 .py 文件，输出问题清单"
    )
    print("=== 代码审查结果 ===")
    print(review_result.result)

    # 子代理 2 生成文档
    doc_result = await doc_generator.query(
        prompt="根据项目代码和审查结果，生成完整的 README.md 文档"
    )
    print("=== 文档生成完成 ===")

    # 主代理汇总结果
    final_report = await main_agent.query(
        prompt=f"汇总以下结果，生成最终交付报告：\n1. 代码审查结果：{review_result.result}\n2. 文档生成状态：完成"
    )
    print("=== 最终报告 ===")
    print(final_report.result)

asyncio.run(main())

3.5 MCP 外部集成

功能说明：基于 MCP（Model Context Protocol）协议，对接外部系统（数据库、浏览器、第三方 API），扩展智能体的能力边界。

示例：对接数据库（MySQL）

ini 复制代码

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions
)
from claude_agent_sdk.mcp import DatabaseMCP

async def main():
    # 初始化数据库 MCP 服务
    db_mcp = DatabaseMCP(
        connection_string="mysql+pymysql://user:password@localhost:3306/mydb"
    )

    async for message in query(
        prompt="""
        1. 连接 MySQL 数据库 mydb
        2. 查询 user 表中所有用户数据
        3. 统计用户数量并生成分析报告
        4. 保存报告为 user_analysis.md
        """,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "MCP"],
            permission_mode="acceptEdits",
            mcp_servers=[db_mcp]  # 注册 MCP 服务
        ),
    ):
        if hasattr(message, "content"):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)

asyncio.run(main())

3.6 持久化会话管理

功能说明：支持会话状态持久化，可恢复历史会话、跨会话共享上下文，适用于长周期任务和多轮交互。

核心参数：

参数名	类型	默认值	功能说明
session_id	str	自动生成	会话唯一 ID，用于恢复会话
persist_session	bool	TRUE	是否持久化会话
working_dir	str	项目根目录	会话工作目录

示例代码：

python 复制代码

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions
)

async def main():
    # 第一轮会话：初始化项目
    print("=== 第一轮会话：初始化项目 ===")
    async for message in query(
        prompt="创建一个 Python 项目结构，包含 src、tests、docs 目录",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"],
            permission_mode="acceptEdits",
            session_id="project_init_session",  # 自定义会话 ID
            persist_session=True  # 持久化会话
        ),
    ):
        if hasattr(message, "content"):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)

    # 第二轮会话：恢复历史会话并继续
    print("\n=== 第二轮会话：恢复并扩展项目 ===")
    async for message in query(
        prompt="在 src 目录下创建核心模块 core.py，实现一个简单的计算器功能",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
            session_id="project_init_session",  # 恢复之前的会话
            persist_session=True
        ),
    ):
        if hasattr(message, "content"):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)

asyncio.run(main())

5.Claude Code 兼容特性

5.1 Skills 自定义能力

功能说明 ：通过 Markdown 文件定义自定义技能，存放于 .claude/skills/ 目录，智能体可自动加载，无需编写代码即可扩展能力。

步骤 1：定义 Skill 文件

创建 .claude/skills/python_code_optimize.md：

yaml 复制代码

---
name: Python代码优化专家
description: 专业的Python代码优化工具，负责性能优化、语法简化、规范对齐
---
# 技能规则
1. 优化方向：
   - 性能：减少循环嵌套、使用高效数据结构
   - 可读性：简化复杂逻辑、添加清晰注释
   - 规范：对齐 PEP 8 标准
2. 输出要求：
   - 先列出优化点及原因
   - 再提供优化后的完整代码
   - 禁止删除核心功能逻辑

步骤 2：加载并使用 Skill

ini 复制代码

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="使用 Python 代码优化专家技能，优化 utils.py 文件",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
            skills=["python_code_optimize"],  # 加载自定义技能
            setting_sources=["user", "project"]  # 自动读取 .claude/skills 目录
        ),
    ):
        if hasattr(message, "content"):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)

asyncio.run(main())

5.2 Slash Commands 快捷指令

功能说明 ：自定义高频操作的快捷指令，存放于 .claude/commands/ 目录，通过 /指令名 快速触发，提升开发效率。

步骤 1：定义快捷指令

创建 .claude/commands/init_pytest.md：

yaml 复制代码

---
name: init_pytest
description: 一键初始化 pytest 单元测试环境
---
# 指令逻辑
1. 安装 pytest 依赖
2. 在 tests 目录下创建 test_*.py 测试文件模板
3. 生成 pytest.ini 配置文件
4. 输出测试执行命令

步骤 2：执行快捷指令

python 复制代码

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="/init_pytest",  # 执行快捷指令
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"],
            permission_mode="acceptEdits",
            setting_sources=["user", "project"]  # 自动读取 .claude/commands 目录
        ),
    ):
        if hasattr(message, "content"):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)

asyncio.run(main())

5.3 Memory 项目记忆

功能说明 ：通过 CLAUDE.md 文件固化项目上下文（规范、结构、配置），智能体在所有会话中自动遵循项目规则。

步骤 1：创建 CLAUDE.md 文件

在项目根目录创建 CLAUDE.md：

markdown 复制代码

# 项目记忆：Python 工具库项目
## 项目规范
- 代码风格：严格遵循 PEP 8
- 类型注解：所有函数必须添加类型注解
- 测试要求：核心功能覆盖率 ≥ 80%
- 文档要求：所有模块和函数必须有 docstring

## 项目结构
- src/：核心代码目录
- tests/：单元测试目录
- docs/：文档目录
- requirements.txt：依赖清单

## 禁止操作
- 禁止删除 src/ 和 tests/ 目录
- 禁止使用 print 语句，使用 logging 模块

步骤 2：加载项目记忆

python 复制代码

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="创建一个新的工具函数，计算两个数的乘积",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit"],
            permission_mode="acceptEdits",
            setting_sources=["user", "project"]  # 自动加载 CLAUDE.md
        ),
    ):
        if hasattr(message, "content"):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)

asyncio.run(main())

5.4 Plugins 插件扩展

功能说明：通过程序化方式接入自定义插件，扩展智能体的工具、钩子、MCP 服务等能力，兼容 Claude Code 插件生态。

示例代码：

ini 复制代码

import asyncio
from claude_agent_sdk import (
    ClaudeAgent,
    ClaudeAgentOptions,
    BasePlugin
)

# 定义自定义插件：代码格式化插件
class CodeFormatPlugin(BasePlugin):
    name = "CodeFormatPlugin"
    description = "代码格式化插件，使用 black 格式化 Python 代码"

    def __init__(self, agent):
        super().__init__(agent)
        # 注册自定义工具
        self.register_tool(
            name="FormatCode",
            description="使用 black 格式化 Python 代码",
            callback=self.format_code
        )

    async def format_code(self, file_path):
        # 执行格式化命令
        result = await self.agent.tools.bash.execute(
            command=f"black {file_path}",
            cwd=self.agent.options.working_dir
        )
        return f"代码格式化完成：{result.stdout}"

async def main():
    # 初始化代理并注册插件
    agent = ClaudeAgent(
        api_key="your-api-key",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"],
            permission_mode="acceptEdits"
        )
    )
    agent.plugins.register(CodeFormatPlugin)  # 注册插件

    # 使用插件功能
    async for message in agent.query(
        prompt="格式化 utils.py 文件，确保符合 PEP 8 规范",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "FormatCode"],  # 使用插件工具
            permission_mode="acceptEdits"
        )
    ):
        if hasattr(message, "content"):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)

asyncio.run(main())

6.高级配置

6.1 ClaudeAgentOptions 完整配置示例

ClaudeAgentOptions 是 Claude Agent SDK 的核心配置类 / 构造器，所有智能体的行为、权限、工具、环境、会话、回调等全局规则，都通过它统一设置

ini 复制代码

from claude_agent_sdk import ClaudeAgentOptions, PreToolUseHook, PostToolUseHook

# 完整配置示例
FULL_OPTIONS = ClaudeAgentOptions(
    # 1. 工具与权限
    allowed_tools=["Read", "Edit", "Bash", "Glob", "WebSearch", "MCP"],
    permission_mode="acceptEdits",
    cwd_override="./my-agent",  # 强制工作目录

    # 2. 执行流程控制
    max_steps=50,  # 最大工具执行步数（防无限循环）
    max_tokens=8192,  # 最大上下文令牌数
    timeout=600,  # 任务超时时间（秒）
    auto_continue=True,  # 自动继续多步任务

    # 3. 环境与变量
    working_dir="./my-agent",
    env_vars={
        "PYTHONPATH": "./src",
        "DEBUG": "true"
    },

    # 4. 会话管理
    session_id="my-custom-session",
    persist_session=True,

    # 5. 钩子配置
    hooks=[
        PreToolUseHook(lambda tool_name, args: print(f"执行工具：{tool_name}")),
        PostToolUseHook(lambda tool_name, result: print(f"工具结果：{result}"))
    ],

    # 6. 模型与认证
    model="claude-3-7-sonnet-latest",
    api_key="your-api-key",
    api_url="https://api.anthropic.com/v1",

    # 7. 高级扩展
    skills=["python_code_optimize", "doc_generator"],
    system_prompt="你是专业的 Python 开发工程师，专注于自动化工具开发",
    mcp_servers=[],  # 注册 MCP 服务
    setting_sources=["user", "project"]  # 加载自定义配置
)

6.2 流式 vs 非流式模式

6.2.1 流式模式（默认）

适用于实时输出执行过程，如交互式工具、日志监控：

python 复制代码

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="分析项目代码并生成报告",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            permission_mode="acceptEdits"
        ),
    ):
        # 实时输出
        if hasattr(message, "content"):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)

asyncio.run(main())

6.2.2 非流式模式

适用于后台任务、批量处理，一次性获取结果：

ini 复制代码

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    # 非流式模式：收集所有结果后输出
    messages = []
    async for message in query(
        prompt="生成项目依赖清单 requirements.txt",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"],
            permission_mode="acceptEdits"
        ),
    ):
        messages.append(message)

    # 处理最终结果
    for msg in messages:
        if hasattr(msg, "result"):
            print("最终结果：", msg.result)

asyncio.run(main())

7.异常处理与故障排查

7.1 常见异常捕获

python 复制代码

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.exceptions import (
    APIKeyError,
    RateLimitError,
    NetworkError,
    PermissionError,
    ToolNotFoundError,
    SessionNotFoundError
)

async def main():
    try:
        async for message in query(
            prompt="执行危险命令",
            options=ClaudeAgentOptions(
                allowed_tools=["Bash"],
                permission_mode="acceptEdits"
            ),
        ):
            if hasattr(message, "content"):
                for block in message.content:
                    if hasattr(block, "text"):
                        print(block.text)
    except APIKeyError:
        print("错误：API Key 无效或未配置")
    except RateLimitError:
        print("错误：请求速率超限，请稍后重试")
    except NetworkError:
        print("错误：网络异常，请检查连接或代理")
    except PermissionError:
        print("错误：权限不足，禁止执行该操作")
    except ToolNotFoundError:
        print("错误：指定的工具不存在")
    except SessionNotFoundError:
        print("错误：会话不存在，无法恢复")
    except Exception as e:
        print(f"未知错误：{str(e)}")

asyncio.run(main())

7.2 官方故障排查指南

API Key 未找到：
1. 检查 .env 文件是否存在且 API Key 配置正确
2. 确认环境变量已加载（可通过 print(os.getenv("ANTHROPIC_API_KEY")) 验证）
工具调用失败：
1. 确认 allowed_tools 中已声明该工具
2. 检查权限模式是否允许该操作（如 dontAsk 模式会拒绝未声明工具）
会话恢复失败：
1. 确认 session_id 正确
2. 检查会话持久化路径是否正确
网络超时：
1. 增大 timeout 参数
2. 配置代理（通过 api_url 或环境变量）
第三方平台认证失败：
1. 确认已启用对应的环境变量（如 CLAUDE_CODE_USE_BEDROCK=1）
2. 检查云服务商凭证配置正确

8. 最佳实践

8.1 安全最佳实践

最小权限原则 ：仅授予智能体完成任务必需的工具（如无需修改文件时使用 Read 而非 Edit）
工作目录限制 ：通过 cwd_override 限制智能体操作范围，避免访问敏感目录
危险命令拦截 ：使用 PreToolUse 钩子拦截 rm -rf、sudo 等危险命令
审批流程 ：生产环境建议使用 default 权限模式，添加人工审批环节

8.2 性能优化建议

限制上下文长度 ：通过 max_tokens 控制上下文大小，避免性能下降
合理设置步数 ：根据任务复杂度调整 max_steps，防止无限循环
复用会话：长周期任务使用持久化会话，避免重复初始化
工具组合使用：复杂任务拆分为多个简单工具调用，提升执行效率

8.3 开发流程建议

需求拆解：将复杂任务拆分为多个子任务，分别由子代理执行
迭代测试：先在沙箱环境测试智能体行为，再部署到生产环境
日志监控：通过钩子记录工具执行过程，便于问题排查
版本控制：对智能体生成的代码进行版本控制，避免误操作

claude_agent_sdk 功能简介

1. 概述

核心特性

2.如何安装

2.1 项目初始化

2.2 配置 API Key

2.3 官方入门示例：自动检测并修复代码 Bug

步骤 1：创建带 Bug 的测试文件

步骤 2：编写智能体代码 agent.py

步骤 3：运行智能体

执行结果

3.核心功能模块

3.1 内置工具集

3.2 精细化权限控制

3.3 生命周期钩子

3.4 子代理（Subagents）

3.5 MCP 外部集成

3.6 持久化会话管理

5.Claude Code 兼容特性

5.1 Skills 自定义能力

5.2 Slash Commands 快捷指令

5.3 Memory 项目记忆

5.4 Plugins 插件扩展

6.高级配置

6.1 ClaudeAgentOptions 完整配置示例

6.2 流式 vs 非流式模式

6.2.1 流式模式（默认）

6.2.2 非流式模式

7.异常处理与故障排查

7.1 常见异常捕获

7.2 官方故障排查指南

8. 最佳实践

8.1 安全最佳实践

8.2 性能优化建议

8.3 开发流程建议

步骤 2：编写智能体代码 `agent.py`