Claude Agent SDK 实战：把 Claude Code 同款运行时装进你的应用（hooks + 进程内 MCP + 权限）

Python 与 TypeScript 都支持，这里以 Python 为例：

pip install claude-agent-sdk

# 设置 API Key（Anthropic 控制台获取）
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxx

# 最简启动：跑一句话任务
from claude_agent_sdk import ClaudeAgent

agent = ClaudeAgent()
result = agent.run("列出当前目录下的 .py 文件并说明各自作用")

传统 MCP 要起一个独立进程；in-process MCP 让你在同一进程里直接定义工具，启动更快、调试更方便：

from claude_agent_sdk import ClaudeAgent, tool

@tool("query_db", "按 SQL 查询内部数据库")
def query_db(sql: str) -> str:
    # 你的真实查询逻辑
    return db.execute(sql)

agent = ClaudeAgent(tools=[query_db])
# Agent 现在能直接调用 query_db，无需额外进程

Hooks 能在 Agent 循环的特定点触发你的函数，比如每次调用工具前先记录或拦截：

from claude_agent_sdk import ClaudeAgent, hook

@hook("PreToolUse")
def guard(tool_name, input):
    if tool_name == "Bash" and "rm -rf" in input.get("command", ""):
        return {"decision": "block", "reason": "禁止危险删除命令"}
    return {"decision": "allow"}

agent = ClaudeAgent(hooks=[guard])

默认权限可能过宽。生产环境用 allowlist 白名单化：

agent = ClaudeAgent(
  permission_allowlist={
    "Bash": ["ls *", "cat *", "python *"],   # 只允许这几类
    "Read": ["src/**", "docs/**"],            # 只能读这些目录
    "Write": ["tmp/**"],                       # 只能写临时区
  }
)

from fastapi import FastAPI
from claude_agent_sdk import ClaudeAgent

app = FastAPI()
agent = ClaudeAgent(hooks=[guard], permission_allowlist=ALLOW)

@app.post("/agent")
async def run(req: dict):
    result = agent.run(req["prompt"])
    return {"output": result.text}

复杂任务让主 Agent 派发子 Agent，各自独立上下文，互不污染：

result = agent.run(
  "重构 src/ 下所有模块，先让子 Agent 逐个分析依赖，再汇总改",
  subagents=["analyzer", "refactor"],
)

1. 权限 allowlist 已白名单化（无 Bash: *）
2. 危险工具（删/发/付）已用 hooks 拦截或要求人审批
3. 所有工具调用有审计日志（PostToolUse 记一笔）
4. 子 Agent 上下文隔离，不共享敏感状态
5. API Key 走环境变量，不进代码仓库