LearnAgent LearnAgent Agent 学习与落地
返回资料库 AI Agent 基础

AI Agent 零基础入门教程：5步搭建你的第一个 Agent

用户输入 → LLM（带工具）→ 工具调用 → LLM 处理结果 → 输出

整理来源：Claude Agent SDK | Anthropic Building Effective Agents | 整理时间：2026-04-01

第一步：理解你需要什么

在开始之前，先问自己几个问题：

  • 你的任务需要多步骤吗？ 如果单次对话就能完成，不需要 Agent
  • 任务需要使用外部工具吗？ 比如读文件、调 API、执行代码
  • 需要记忆上下文吗？ 跨对话保持记忆

最简单的 Agent 结构：

用户输入 → LLM（带工具）→ 工具调用 → LLM 处理结果 → 输出

第二步：选择你的起点

选项 A：直接使用现成工具（推荐新手）

OpenClaw（零代码，个人使用）

  • 在 Telegram/WhatsApp 上聊天即可控制
  • 内置记忆、工具调用、技能扩展
  • 5分钟完成部署
  • → 参见 OpenClaw 快速入门

Claude Code（开发者，代码场景）

选项 B：用 SDK 自己构建

适合需要定制 Agent 行为的开发者。

第三步：用 Claude Agent SDK 构建（Python 示例）

安装

pip install claude-agent-sdk
export ANTHROPIC_API_KEY=your-api-key

最简单的 Agent

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    # 创建一个可以读文件和执行命令的 Agent
    async for message in query(
        prompt="这个目录里有哪些文件？",
        options=ClaudeAgentOptions(
            allowed_tools=["Bash", "Glob"]  # 授权工具
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

带文件操作的 Agent

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="找出所有的 TODO 注释并生成摘要",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"]  # 只允许读取，不允许修改
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

第四步：理解核心概念

工具（Tools）— Agent 的手和脚

工具名 功能
Read 读取文件内容
Write 创建新文件
Edit 精准修改文件
Bash 执行终端命令
Glob 按模式查找文件
Grep 正则搜索文件内容
WebSearch 搜索网络
WebFetch 抓取网页内容

⚠️ 安全原则：只给 Agent 它实际需要的最小权限

权限（Permissions）— 护栏

# 严格模式：每次操作都需要确认
options = ClaudeAgentOptions(
    permission_mode="default"
)

# 自动模式：分类器检查后自动批准低风险操作
options = ClaudeAgentOptions(
    permission_mode="auto"
)

# 计划模式：只读分析，不执行任何修改
options = ClaudeAgentOptions(
    permission_mode="plan"
)

记忆（Memory）— Agent 的大脑

通过 CLAUDE.md 文件给 Agent 持久化指令：

# 我的项目约定
- 使用 ES modules，不用 CommonJS
- 测试框架：Jest
- 代码风格：2空格缩进

第五步：常见模式和最佳实践

模式一：探索-规划-执行

# 1. 先探索（Plan Mode）
async for msg in query(
    prompt="分析这个代码库的结构",
    options=ClaudeAgentOptions(permission_mode="plan")
):
    print(msg)

# 2. 执行（Normal Mode）
async for msg in query(
    prompt="根据分析，添加单元测试",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"]
    )
):
    print(msg)

模式二：使用子 Agent（Subagents）

# 主 Agent 委托子 Agent 做代码审查
async for msg in query(
    prompt="用子 Agent 检查这段代码的安全漏洞",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Bash"]
    )
):
    print(msg)

模式三：并行任务

# 同时处理多个文件（Shell 脚本）
for file in $(cat files.txt); do
  claude -p "迁移 $file 从旧 API 到新 API" \
    --allowedTools "Edit,Bash(git commit *)" &
done
wait

常见错误和解决方案

问题 原因 解决方法
Agent 在兜圈子 没有明确的成功标准 提供测试命令或验证方式
修改了不该改的文件 权限过于宽松 使用 allowedTools 限制范围
上下文填满 文件太多、对话太长 用子 Agent 隔离探索任务
反复犯同样错误 上下文里堆积了错误示范 清除上下文，重新开始

延伸资源

本系列相关文章

常见问题

AI Agent 零基础入门教程：5步搭建你的第一个 Agent 适合什么读者？

AI Agent 零基础入门教程：5步搭建你的第一个 Agent 适合希望系统掌握 AI Agent 基础 的读者，尤其是需要从概念快速过渡到实践的人。页面包含主题摘要、相关阅读和来源链接，便于形成可执行的学习路径。

阅读 AI Agent 零基础入门教程：5步搭建你的第一个 Agent 需要多久？

当前页面预估阅读时长约 5 分钟。建议先读正文结论，再根据“同专题延伸”继续阅读，通常 20 到 40 分钟可以建立完整主题框架。

如何把 AI Agent 零基础入门教程：5步搭建你的第一个 Agent 的内容用于实际项目？

先按正文中的关键概念完成最小可运行示例，再把示例嵌入你当前项目流程。你可以结合来源链接验证细节，并使用同专题文章补齐部署、协作和评估步骤。