§02 三步装好环境，跑通第一条查询

我第一次装 Agent SDK 是 2026 年 3 月。那会儿我以为又要配一堆环境。结果 10 分钟就跑通了第一个 Agent。这章把当时的装法原样走一遍。

02.1 你需要什么

• Node.js 18+，或 Python 3.10+。
• 一个 Anthropic API Key（从 Console 申请）。
• 预计 10 分钟。

我实测装这个比装大多数 CLI 工具都快。因为不用装 Claude Code 本体。

02.2 我们最终要看到什么

目标：写一段代码，让 Claude 列出当前目录的文件。

你会看到它自己调用工具，最后打印出文件清单。这就是"自动驾驶"的第一脚油门。

02.3 第一步：装包

# TypeScript 项目
npm install @anthropic-ai/claude-agent-sdk

# Python 项目
pip install claude-agent-sdk

预期结果：终端显示安装完成，没有报红。

02.4 第二步：配 API Key

# 在终端里导出（临时生效）
export ANTHROPIC_API_KEY=你的key

# 或者在项目根目录建 .env 文件，写入下面这行
# ANTHROPIC_API_KEY=你的key

预期结果：环境变量已设置。后面代码会自动读它。

注意：.env 可能被系统环境变量覆盖。

文档里专门提了这条坑：当系统已经设了 ANTHROPIC_API_KEY，dotenv.config() 默认不会覆盖。你要用 dotenv.config({ override: true })，否则 SDK 会连到你没想到的端点。

02.5 第三步：跑第一条查询

# agent.py —— 第一个会动的 Agent
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    # 这行是关键：只给读文件相关的工具，最安全
    async for message in query(
        prompt="这个目录里有哪些文件？",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)  # 打印最终答案

asyncio.run(main())

预期结果：终端列出当前目录的文件名。整个过程你没碰过文件操作。

标叔的经验：第一次跑，别追求完美 prompt。

我带新人时总说：先让它动起来，看输出，再改 prompt。很多人卡在"写一句完美的指令"，结果一行都没跑。这里 allowed_tools 只放了 Bash 和 Glob，就是给它最小权限先试水。

装好了，也跑通了。下一章，让 Agent 干点真活——自己修 bug。