智能体数据科学家

K-Dense Web

对于需要访问更强大功能的用户，K-Dense Web 已经上线。请访问 k-dense.ai 了解更多信息。

面向数据科学的自适应多智能体框架

Agentic Data Scientist 是一个开源框架，采用复杂的多智能体工作流来解决复杂的数据科学任务。它基于 Google 的 Agent Development Kit (ADK) 和 Claude Agent SDK 构建，将规划与执行分离，持续验证工作进展，并根据进度动态调整策略。

特性

• 🤖 自适应多智能体工作流：迭代式规划、执行、验证和反思
• 📋 智能规划：在开始工作前制定全面的分析计划
• 🔄 持续验证：每一步都对照成功标准跟踪进展
• 🎯 自我修正：根据执行过程中的发现审查并调整计划
• 🔌 MCP 集成：通过 Model Context Protocol 服务器访问工具
• 🧠 Claude 科学技能集成：直接在您的工作流中使用高级 Claude 技能
• 📁 文件处理：简单的文件上传和管理
• 🛠️ 可扩展：自定义提示、智能体和工作流
• 📦 易于安装：可通过 pip 和 uvx 安装

快速入门

前置条件

在使用 Agentic Data Scientist 之前，您必须具备以下条件：

1. 已安装 Claude Code CLI

   npm install -g @anthropic-ai/claude-code
   

   或访问 Claude Code 快速入门

2. 配置好所需的 API 密钥（见下文配置部分）：

   • OPENROUTER_API_KEY（用于规划和评审智能体）
   • ANTHROPIC_API_KEY（用于编码智能体）

安装

# 从 PyPI 安装
uv tool install agentic-data-scientist

# 或者使用 uvx（无需安装）
uvx agentic-data-scientist --mode simple "your query here"

配置

API 密钥

您必须配置两个 API 密钥：

1. OpenRouter API 密钥（规划和评审智能体所需）：

   export OPENROUTER_API_KEY="your_key_here"
   

   您可以在 https://openrouter.ai/keys 获取密钥。

2. Anthropic API 密钥（编码智能体所需）：

   export ANTHROPIC_API_KEY="your_key_here"
   

   您可以在 https://console.anthropic.com/ 获取密钥。

或者，您也可以在项目目录下创建一个 .env 文件：

OPENROUTER_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here

网络访问控制（可选）

默认情况下，智能体可以访问网络工具（网页搜索和 URL 获取）。如需禁用网络访问：

export DISABLE_NETWORK_ACCESS=true

这将禁用：

• ADK 智体的 fetch_url 工具
• Claude Code 智体的 WebFetch 和 WebSearch 工具

网络访问默认是启用的。设置为“true”或“1”即可禁用。

基本用法

重要提示：您必须指定 --mode 来选择执行策略。这样可以确保您了解任务的复杂性和 API 费用。

工作目录：默认情况下，文件会保存到当前目录下的 ./agentic_output/ 中，并在完成任务后保留。您可以使用 --temp-dir 参数来指定临时存储目录，任务完成后会自动清理。

协调模式（完整多智能体工作流）

# 复杂分析，包含规划、执行和验证
agentic-data-scientist "进行差异表达分析" --mode orchestrated --files data.csv

# 多个文件，自定义工作目录
agentic-data-scientist "比较数据集" --mode orchestrated -f data1.csv -f data2.csv --working-dir ./my_analysis

# 目录上传（递归）
agentic-data-scientist "分析所有数据" --mode orchestrated --files data_folder/

简单模式（直接编码，无规划）

# 无需规划开销的快速编码任务
agentic-data-scientist "编写一个 Python 脚本来解析 CSV 文件" --mode simple

# 问答
agentic-data-scientist "解释梯度提升的工作原理" --mode simple

# 使用临时目录的快速分析
agentic-data-scientist "快速数据探索" --mode simple --files data.csv --temp-dir

其他选项

# 自定义日志文件位置
agentic-data-scientist "分析数据" --mode orchestrated --files data.csv --log-file ./analysis.log

# 详细日志用于调试
agentic-data-scientist "调试问题" --mode simple --files data.csv --verbose

# 保留文件（覆盖默认保留设置）
agentic-data-scientist "生成报告" --mode orchestrated --files data.csv --keep-files

工作原理

Agentic Data Scientist 采用多阶段工作流设计，旨在产出高质量、可靠的结果：

工作流设计 rationale

为什么将规划与执行分开？

• 在开始工作前彻底分析需求，可以减少错误和返工
• 提前明确成功标准，确保满足所有要求
• 计划可以在投入资源实施之前得到验证和优化

为什么采用迭代式改进？

• 多次评审循环能够在问题还容易修复时及早发现
• 计划和实施方案都会在继续推进之前得到验证
• 持续的反馈有助于在每一步提高质量

为什么要在执行过程中进行调整？

• 执行过程中可能会发现新的需求
• 固定的计划无法应对意外的见解或挑战
• 自适应的重新规划能够确保最终交付物符合实际需求

为什么进行持续验证？

• 跟踪成功标准可以客观地衡量进展
• 早期发现问题可以防止浪费精力
• 清晰地了解已完成的工作和剩余的任务

多智能体工作流

┌─────────────────────────────────────────────────────────────┐
│                     用户查询                              │
└─────────────────────┬───────────────────────────────────────┘
                      │
        ┌─────────────▼────────────────┐
        │   计划阶段             │
        │  ┌───────────────────────┐   │
        │  │ 计划制定者            │◄──┤ 迭代式细化
        │  │ “需要完成什么？”      │   │ 直到计划完整
        │  │                        │   │ 并通过验证
        │  └──────────┬────────────┘   │
        │             │                │
        │  ┌──────────▼────────────┐   │
        │  │ 计划审核者          │   │
        │  │ “这个计划完整吗？”    │───┤
        │  └──────────┬────────────┘   │
        │             │                │
        │  ┌──────────▼────────────┐   │
        │  │ 计划解析者          │   │
        │  │ 将其结构化为         │   │
        │  │ 可执行的阶段         │   │
        │  └──────────┬────────────┘   │
        └─────────────┼────────────────┘
                      │
        ┌─────────────▼────────────────┐
        │   执行阶段              │
        │   （每个阶段重复进行）    │
        │                              │
        │  ┌───────────────────────┐   │
        │  │ 编码智能体          │   │
        │  │ 实施该阶段          │   │ 阶段逐个
        │  │ （使用 Claude Code）  │   │ 实现，并持续验证
        │  └──────────┬────────────┘   │
        │             │                │
        │  ┌──────────▼────────────┐   │
        │  │ 审核智能体          │◄──┤ 循环迭代，直至
        │  │ “这项工作是否正确完成？”│   │ 实现得到批准
        │  └──────────┬────────────┘   │
        │             │                │
        │  ┌──────────▼────────────┐   │
        │  │ 标准检查者          │   │
        │  │ “我们已经完成了什么？”│   │
        │  │                        │   │
        │  └──────────┬────────────┘   │
        │             │                │
        │  ┌──────────▼────────────┐   │
        │  │ 阶段反思者          │   │
        │  │ “接下来我们应该做什么？”调整计划   │   │
        │  └──────────┬────────────┘   │
        └─────────────┼────────────────┘
                      │
        ┌─────────────▼────────────────┐
        │   总结阶段              │
        │  ┌───────────────────────┐   │
        │  │ 总结智能体          │   │
        │  │ 创建全面的           │   │
        │  │ 最终报告            │   │
        │  └───────────────────────┘   │
        └──────────────────────────────┘

智能体角色

工作流中的每个智能体都有特定的责任：

• 计划制定者：“需要完成什么？”——创建包含清晰阶段和成功标准的综合分析计划。
• 计划审核者：“这个计划完整吗？”——在执行开始前验证计划是否满足所有需求。
• 计划解析者：将自然语言计划转换为结构化的可执行阶段，并设定可追踪的成功标准。
• 阶段协调员：管理执行周期——按顺序运行各个阶段，验证进展并根据需要调整。
• 编码智能体：执行实际的实现工作（由 Claude Code SDK 提供支持，可访问 380 多种科学技能）。
• 审核智能体：“这项工作是否正确完成？”——在继续下一步之前验证实施是否符合要求。
• 标准检查者：“我们已经完成了什么？”——客观地跟踪每个阶段后的进展与成功标准的对比情况。
• 阶段反思者：“接下来我们应该做什么？”——分析进展，并根据已学到的内容调整剩余阶段。
• 总结智能体：将所有工作整合成一份全面且可发表的报告。

架构

┌──────────────────────────────────────────────────────────────┐
│                    命令行界面                             │
├──────────────────────────────────────────────────────────────┤
│          智能体数据科学家核心                         │
│        （会话与事件管理）                          │
├──────────────────────────────────────────────────────────────┤
│               ADK 多智能体工作流                       │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ 计划循环（计划制定者 → 审核者 → 解析者）         │  │
│  └────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ 阶段协调员                                     │  |
│  │   ├─> 实施循环（编码 → 审核）            │  │
│  │   ├─> 标准检查者                                 │  │
│  │   └─> 阶段反思者                                  │  │
│  └────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ 总结智能体                                          │  │
│  └────────────────────────────────────────────────────────┘  │
├──────────────────────────────────────────────────────────────┤
│                     工具层                               │
│  • 内置工具：只读文件操作、网页抓取             │
│  • Claude 科学技能：120 多种技能                     │
└──────────────────────────────────────────────────────────────┘

配置

环境变量

创建一个 .env 文件：

# 必需：API 密钥
ANTHROPIC_API_KEY=your_key_here
GOOGLE_API_KEY=your_key_here

# 可选：模型配置
DEFAULT_MODEL=google/gemini-2.5-pro
CODING_MODEL=claude-sonnet-4-5-20250929

工具与技能

内置工具（用于计划/审核智能体）：

• 文件操作：仅限于工作目录内的只读文件访问
  • read_file, read_media_file, list_directory, directory_tree, search_files, get_file_info
• 网络操作：通过 HTTP 获取网络内容
  • fetch_url

Claude 科学技能（用于编码智能体）：

• 120 多种科学技能 自动从 claude-scientific-skills 加载
  • 科学数据库：UniProt、PubChem、PDB、KEGG、PubMed 等
  • 科学软件包：BioPython、RDKit、PyDESeq2、scanpy 等
  • 在编码智能体启动时自动克隆至 .claude/skills/

所有工具均被沙盒化到工作目录中以确保安全。

文档

• 入门指南 —— 了解工作流如何逐步运作
• API 参考 —— 完整的 API 文档
• 工具配置 —— 配置工具和技能
• 扩展 —— 自定义提示词、智能体和工作流

示例

协调模式用例

复杂数据分析

# 多文件差异表达分析
agentic-data-scientist "执行处理组与对照组的DEG分析" \
  --mode orchestrated \
  --files treatment_data.csv \
  --files control_data.csv

多步骤工作流

# 包含可视化的完整分析流程
agentic-data-scientist "分析客户流失、创建预测模型并生成报告" \
  --mode orchestrated \
  --files customers.csv \
  --working-dir ./churn_analysis

目录处理

# 处理整个数据集目录
agentic-data-scientist "分析所有CSV文件并生成汇总统计信息" \
  --mode orchestrated \
  --files ./raw_data/

简单模式用例

快速脚本

# 生成实用脚本
agentic-data-scientist "编写一个Python脚本，按共同列合并CSV文件" \
  --mode simple

代码解释

# 技术性问题
agentic-data-scientist "解释随机森林和梯度提升的区别" \
  --mode simple

快速原型

# 使用临时工作空间进行快速分析
agentic-data-scientist "根据这些数据创建一个基本散点图" \
  --mode simple \
  --files data.csv \
  --temp-dir

工作目录示例

# 默认行为（./agentic_output/，保留文件）
agentic-data-scientist "分析数据" --mode orchestrated --files data.csv

# 临时目录（自动清理）
agentic-data-scientist "快速测试" --mode simple --files data.csv --temp-dir

# 自定义位置
agentic-data-scientist "项目分析" --mode orchestrated --files data.csv --working-dir ./my_project

# 自定义位置并明确清理
agentic-data-scientist "临时分析" --mode simple --files data.csv --working-dir ./temp --keep-files=false

开发

设置

# 克隆仓库
git clone https://github.com/K-Dense-AI/agentic-data-scientist.git
cd agentic-data-scientist

# 使用uv安装开发依赖
uv sync --extra dev

# 运行测试
uv run pytest tests/

# 格式化代码
uv run ruff format .

# 静态检查
uv run ruff check --fix .

项目结构

agentic-data-scientist/
├── src/agentic_data_scientist/
│   ├── core/           # 核心API和会话管理
│   ├── agents/         # 代理实现
│   │   ├── adk/        # ADK多代理工作流
│   │   │   ├── agent.py              # 代理工厂
│   │   │   ├── stage_orchestrator.py # 分阶段执行
│   │   │   ├── implementation_loop.py# 编码+评审循环
│   │   │   ├── loop_detection.py     # 循环检测代理
│   │   │   └契review_confirmation.py# 评审决策逻辑
│   │   └契claude_code/# Claude Code集成
│   ├── prompts/        # 提示模板
│   │   ├── base/       # 代理角色提示
│   │   └契domain/     # 领域特定提示
│   ├── tools/          # 内置工具（文件操作、网页抓取）
│   └契cli/            # CLI接口
├── tests/              # 测试套件
└契docs/               # 文档

要求

• Python 3.12+
• Node.js（用于Claude Code）
• Anthropic和OpenRouter的API密钥

贡献

欢迎贡献！详情请参阅CONTRIBUTING.md。

# 分支并克隆后：
uv sync --extra dev
# 进行修改，添加测试
uv run pytest tests/ -v
# 提交PR

发布流程

对于维护者：

1. 创建并推送标签：

   ./scripts/release.sh 0.2.0
   

2. 创建GitHub发布：

   • 访问https://github.com/K-Dense-AI/agentic-data-scientist/releases/new?tag=v0.2.0
   • 点击“生成发布说明”以自动生成变更日志
   • 发布版本
   • 软件包会自动发布到PyPI

一次性PyPI设置： 在PyPI上配置可信发布，关联仓库K-Dense-AI/agentic-data-scientist和工作流pypi-publish.yml。

使用规范化的提交信息（feat:、fix:、docs:等）以生成清晰的变更日志。

技术注释

上下文窗口管理

该框架实施了激进的事件压缩策略，以在长时间运行的分析过程中管理上下文窗口的使用：

事件压缩策略

• 自动压缩：当事件数量超过阈值时（默认为40个），事件会自动压缩
• LLM驱动的摘要：旧事件会在被移除前由LLM总结，以保留关键上下文
• 激进截断：大型文本内容（超过10KB）会被截断，以防止令牌溢出
• 直接事件队列操作：通过直接赋值给session.events来确保更改生效

防止令牌溢出

系统采用了多层保护机制：

• 基于回调的压缩：在每个代理回合结束后自动触发
• 手动压缩：在关键编排点（例如实现循环之后）触发
• 硬性限制修剪：如果事件数量超过最大值，则作为紧急回退措施丢弃旧事件
• 大文本截断：防止单个事件占用过多令牌

这些机制协同工作，即使在复杂的多阶段分析中，也能将总上下文保持在100万令牌以内。

支持

• GitHub Issues：报告错误或请求功能
• 加入我们的Slack社区：K-Dense社区
• 文档：完整文档

致谢

基于以下技术构建：

• Google Agent Development Kit (ADK)
• Claude Agent SDK
• Model Context Protocol
• Claude Scientific Skills

许可证

MIT许可证 - 详情请参阅LICENSE。

版权所有 © 2025 K-Dense Inc. (k-dense.ai)

星标历史

Agentic Data Scientist 快速上手指南

Agentic Data Scientist 是一个基于多智能体工作流的开源框架，专为解决复杂的数据科学任务而设计。它利用 Google ADK 和 Claude Agent SDK，将规划与执行分离，并通过持续的验证和自我修正机制确保结果质量。

环境准备

在开始使用前，请确保您的系统满足以下要求：

1. Python 环境：支持 Python 3.12+。
2. Claude Code CLI：必须安装此工具以支持编码智能体。

   npm install -g @anthropic-ai/claude-code
   

   注：如网络受限，请自行配置 npm 镜像源（如 npm config set registry https://registry.npmmirror.com）。
3. API Keys：需准备以下两个密钥：
   • OpenRouter API Key：用于规划（Planning）和审查（Review）智能体。获取地址：https://openrouter.ai/keys
   • Anthropic API Key：用于编码（Coding）智能体。获取地址：https://console.anthropic.com/

安装步骤

推荐使用 uv 工具进行安装，既快速又方便管理依赖。

方式一：全局安装（推荐）

uv tool install agentic-data-scientist

方式二：免安装运行 如果不希望全局安装，可直接使用 uvx 运行：

uvx agentic-data-scientist --mode simple "your query here"

基本使用

1. 配置环境变量

在使用前，您需要配置 API 密钥。可以通过导出环境变量或创建 .env 文件实现。

方法 A：临时导出（当前终端会话有效）

export OPENROUTER_API_KEY="your_openrouter_key_here"
export ANTHROPIC_API_KEY="your_anthropic_key_here"

方法 B：创建 .env 文件（项目目录内） 在项目根目录下创建 .env 文件并填入：

OPENROUTER_API_KEY=your_openrouter_key_here
ANTHROPIC_API_KEY=your_anthropic_key_here

(可选) 禁用网络访问：如果希望禁止智能体访问互联网（如网页搜索），可设置：

export DISABLE_NETWORK_ACCESS=true

2. 运行示例

该工具提供两种主要模式：Orchestrated（完整多智能体工作流，含规划与验证）和 Simple（直接编码，无规划开销）。必须指定 --mode 参数。

场景一：简单任务（Simple Mode）

适用于快速脚本编写、概念解释或简单的数据分析，无需复杂的规划过程。

# 示例：编写一个解析 CSV 的 Python 脚本
agentic-data-scientist "Write a Python script to parse CSV files" --mode simple

# 示例：快速数据探索（使用临时目录，结束后自动清理）
agentic-data-scientist "Quick data exploration" --mode simple --files data.csv --temp-dir

场景二：复杂分析（Orchestrated Mode）

适用于需要严谨规划、分步执行和持续验证的复杂数据科学任务（如差异表达分析）。

# 示例：对单个文件进行复杂的差异表达分析
agentic-data-scientist "Perform differential expression analysis" --mode orchestrated --files data.csv

# 示例：对比多个数据集，并指定输出目录
agentic-data-scientist "Compare datasets" --mode orchestrated -f data1.csv -f data2.csv --working-dir ./my_analysis

# 示例：递归分析整个文件夹
agentic-data-scientist "Analyze all data" --mode orchestrated --files data_folder/

常用附加选项

• --files 或 -f: 指定输入文件。
• --working-dir: 指定工作目录（默认保存在 ./agentic_output/）。
• --temp-dir: 使用临时目录，任务完成后自动清理文件。
• --verbose: 开启详细日志，便于调试。
• --log-file: 指定日志文件保存路径。

# 示例：带详细日志的分析任务
agentic-data-scientist "Debug issue" --mode simple --files data.csv --verbose

提示：默认情况下，生成的文件会保留在 ./agentic_output/ 目录中。如果您希望任务结束后自动清理文件，请添加 --temp-dir 参数。