aws-samples/sample-text2sql-deep-agent-evalulation

# 使用 LangSmith 和 AWS 评估 Deep Agents 这是一个使用 LangChain DeepAgents 和 Amazon Bedrock 构建的 Text-to-SQL 深度智能体（Deep Agent），并使用 LangSmith 提供了全面的评估模式。 本代码库附属于博客文章《使用 LangSmith 和 AWS 评估 Deep Agents》，并展示了用于测试智能体 AI 系统的五种评估模式。 ## 前置条件 在开始之前，请确保您具备以下条件： - 已安装 **Python 3.9 或更高版本** - 已启用 Amazon Bedrock 访问权限（Claude Sonnet 模型）的 **AWS 账户** - 已使用有效凭证配置好的 **AWS CLI**（`aws configure`） - **LangSmith 账户** — 请在 [smith.langchain.com](https://smith.langchain.com) 注册并生成 API 密钥 - 用于克隆代码库的 **Git** ## 设置 ### 1. 克隆并安装依赖 ``` git clone cd langsmith-deep-agents-eval python -m venv .venv source .venv/bin/activate pip install -e . ``` ### 2. 配置环境变量 复制示例环境文件并填写您的值： ``` cp .env.example .env ``` 使用您的 LangSmith API 密钥编辑 `.env`： ``` AWS_REGION=us-east-1 LANGCHAIN_TRACING_V2=true LANGSMITH_ENDPOINT=https://api.smith.langchain.com LANGCHAIN_API_KEY= LANGCHAIN_PROJECT=text2sql-deepagent-bedrock ``` ### 安全的密钥管理 `.env` 文件仅用于**本地开发**，并已通过 `.gitignore` 排除在版本控制之外。对于生产环境部署： - **AWS Secrets Manager**：将 API 密钥作为 secret 存储，并使用 `boto3` 以编程方式检索它们。 - **AWS Systems Manager Parameter Store**：将密钥作为 SecureString 参数存储。 - **切勿**将 API 密钥、凭证或 `.env` 文件提交到版本控制系统中。 ### 3. 验证您的设置 运行单个测试以确认所有配置均已就绪： ``` pytest tests/evals/test_text_to_sql_evals.py::test_simple_query_calls_correct_tool -v ``` 您应该会看到测试通过，并在输出中看到一个追踪 URL。访问您的 [LangSmith 仪表板](https://smith.langchain.com) 以确认追踪已被记录。 ## 运行评估 运行所有五种评估模式： ``` pytest tests/evals/ -v ``` 展示的五种模式如下： 1. **LLM-as-judge** — LLM 根据评分标准对复杂的分析性答案进行评分 2. **单步评估** — 验证智能体的首个决策是否正确 3. **完整轨迹评估** — 检查工具使用顺序及最终答案 4. **多轮评估** — 测试依赖于先前上下文的后续问题 5. **环境/状态检查** — 验证 SQL 安全性和智能体行为 ## 成本注意事项 本项目使用计费服务： - **Amazon Bedrock** 根据输入/输出 token 按每次 API 调用收费。每次测试都会调用智能体（多次 LLM 调用），外加一次 LLM 评估器调用。 - **LangSmith** 根据您的套餐对追踪存储和评估运行收取费用。 运行完整的评估套件将会产生这两项服务的费用。请在 [AWS 账单控制台](https://console.aws.amazon.com/billing/) 和 [LangSmith 使用页面](https://smith.langchain.com) 中监控您的使用情况。 ## 清理资源 为避免在使用完毕后产生持续费用： 1. **Amazon Bedrock**：当您的代码停止运行时，API 调用即会停止。不会创建任何持久性资源。请在您的 [AWS 账单控制台](https://console.aws.amazon.com/billing/) 中进行监控，以确认没有意外费用。 2. **LangSmith 项目**：在 LangSmith UI 中归档或删除 `text2sql-deepagent-bedrock` 项目（依次进入 Tracing Projects → 选择项目 → Settings → Delete）。 3. **在线评估器**：如果您配置了在线评估器，请在 LangSmith UI 中禁用或删除它们，以停止自动评估运行。 4. **环境变量**：如果不再需要，请移除或轮换您的 LangSmith API 密钥。 ## 安全：Text-to-SQL 智能体的纵深防御 Text-to-SQL 智能体可以执行任意 SQL，因此仅靠提示级别的指令是不够的。本项目应用了以下几种确定性控制措施： - **只读数据库连接** — SQLite 数据库以只读模式（`?mode=ro`）打开，因此无论智能体生成什么内容，`INSERT`、`UPDATE`、`DELETE` 和 `DROP` 语句都会在数据库驱动程序级别失败。 - **隔离的智能体工作区** — 智能体的 `FilesystemBackend` 将数据写入 `.agent_workspace/` 而不是项目根目录，从而限制了智能体在遭受提示词注入攻击时的影响范围。 - **评估中的 SQL 安全断言** — 评估套件会检查执行的查询中是否出现 DML 语句（参见 `test_complex_query_uses_planning_and_safe_sql`）。 - **在线安全评估器** — `sql-safety-check` 在线评估器（参见 `online_evaluators_setup.py`）会检查每一条生产环境追踪记录中是否存在危险的 SQL 关键字。 当您将此模式应用于需要写访问权限的生产环境数据库（例如 PostgreSQL、MySQL）时，请考虑使用只读数据库副本或仅具有 `SELECT` 权限的数据库用户。 ## 项目结构 ``` ├── agent.py # CLI entrypoint for the text-to-SQL agent ├── chinook.db # SQLite Chinook sample database ├── skills/ # Deep agent skills (query writing, schema exploration) ├── tests/evals/ │ ├── conftest.py # Pytest fixtures (agent, model, database) │ └── test_text_to_sql_evals.py # Five evaluation patterns ├── .env.example # Environment variable template └── pyproject.toml # Project dependencies ``` ## 安全 有关更多信息，请参见 [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications)。 ## 许可证 本库采用 MIT-0 许可证授权。请参阅 LICENSE 文件。

标签：AI评估测试, Amazon Bedrock, DLL 劫持, LangChain, Text-to-SQL, 人工智能, 大语言模型, 用户模式Hook绕过, 轻量级, 逆向工具