# Agent 起步项目

Python 3.11 或更新版本，仅使用标准库，无需 pip 安装依赖。
将 agent_lab.py 保存到一个新建的 agent-lab 文件夹。在终端进入该文件夹。

Windows PowerShell:
    py -3 --version
    py -3 -m venv .venv
    .\.venv\Scripts\python.exe agent_lab.py --self-test

macOS / Linux:
    python3 --version
    python3 -m venv .venv
    .venv/bin/python agent_lab.py --self-test

如果找不到 Python，先从 https://www.python.org/downloads/ 安装。
Linux 若缺少 venv，按发行版说明安装对应 python3-venv 包后重试。
无需激活虚拟环境；下方 python 请替换为上面的环境内解释器路径。

## 逐步运行
    python agent_lab.py --step plan
    python agent_lab.py --step tool
    python agent_lab.py --step agent

plan：固定假数据通过 title/owner/due_date 校验，输出小林的待办。
tool：本地 get_task 返回 ok: true 和任务信息。
agent：第一轮模拟工具请求，第二轮读取工具结果并结束；日志 ID 应相同。
默认 offline 不访问网络、不使用密钥，不根据 --text 推理。
看到 fixture: true 说明输出来自假数据，不能作为真实模型效果评测。

## 失败演练（预期退出码 1，ok: false）
    python agent_lab.py --step plan --simulate schema-error
    python agent_lab.py --step plan --simulate timeout
    python agent_lab.py --step agent --simulate unknown-tool
    python agent_lab.py --step agent --max-turns 1

依次观察 schema_error、simulated_timeout、turn_limit、turn_limit。
未知工具会返回 is_error 的关联结果，重复失败最多三轮即退出。
工具本地错误类型、参数非法、记录缺失以及调用关联由 --self-test 覆盖。

## 接入真实模型（会消耗你自己的 API 额度）
先在 Claude Console 创建 API 密钥，并选择账号实际可用的模型 ID。
脚本直连官方 Messages HTTP API，不依赖 SDK。网页不会读取或保存你的密钥。

Windows PowerShell，避免密钥进入命令历史：
    $credential = Read-Host 'API key' -AsSecureString
    $env:ANTHROPIC_API_KEY = [System.Net.NetworkCredential]::new('', $credential).Password
    $env:ANTHROPIC_MODEL = Read-Host 'Model ID'
    .\.venv\Scripts\python.exe agent_lab.py --mode live --step plan
    .\.venv\Scripts\python.exe agent_lab.py --mode live --step agent --max-turns 3
    Remove-Item Env:ANTHROPIC_API_KEY

macOS / Linux（bash）：
    read -r -s -p 'API key: ' ANTHROPIC_API_KEY; echo
    export ANTHROPIC_API_KEY
    read -r -p 'Model ID: ' ANTHROPIC_MODEL
    export ANTHROPIC_MODEL
    .venv/bin/python agent_lab.py --mode live --step plan
    .venv/bin/python agent_lab.py --mode live --step agent --max-turns 3
    unset ANTHROPIC_API_KEY

plan 用提示词请求 JSON，再由本地代码校验；没有开启服务端结构化输出保证。
真实模型不一定返回合格 JSON，失败就退出，不自动重试或伪造离线成功。
记录缺少具体日期时输出 null。若需要服务端 schema 约束，可再学习结构化输出接口。
每轮最多 512 输出 token，最多五轮，每次网络操作超时 20 秒，无自动重试。
这些是演示限制，不是精确金额上限或生产级整体截止时间；计费以服务商为准。
HTTP 401/403 检查权限，429 检查额度/速率，网络失败检查连通性。
脚本仅有只读查询工具，不执行模型提供的代码、文件路径或系统命令。

## 阅读源码的顺序
1. validate_plan：JSON 解析成功后，继续检查字段、类型、日期。
2. execute_tool：工具注册白名单与输入校验。
3. live_response：配置、HTTP 请求、停止原因、用量。
4. run_agent：保留 assistant 内容，以 tool_use_id 关联 user 的 tool_result。
5. self_test：增加自己的边界输入，先让测试失败再修正。

## 进一步练习
把离线任务换成三条，验证空列表被拒绝；给工具增加权限检查。
对比正常、缺失信息、矛盾记录三类真实输入，保存脱敏结果。
扩展写操作前先实现预览与人工确认，不要直接修改任务。
源文件和 README 可以提交；.venv/、.env、__pycache__/ 应加入 .gitignore。

官方资料：
https://platform.claude.com/docs/en/api/messages/create
https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
https://docs.python.org/3/library/venv.html