Alfredo

一个基于Python的框架，用于构建具有全面工具执行和自主任务完成能力的AI代理。

Alfredo 提供了一个基于LangGraph的代理框架，它结合了规划、执行和验证，形成一个统一的代理框架。考虑到可扩展性，它支持自定义工具、MCP集成，并且附带了一些专门预建的代理。

主要特性

• 🤖 自主代理 - 自动任务分解的计划-验证-重新计划循环
• 🔧 11个内置工具 - 文件操作、命令、发现、代码分析、视觉和工作流控制
• 👁️ 视觉能力 - 使用多模态模型分析图像
• 🔗 MCP集成 - 连接到任何模型上下文协议服务器
• 🎯 模型无关 - 支持OpenAI、Anthropic或任何LangChain支持的LLM
• 📊 执行跟踪 - 对代理行为有详细的可见性
• 🛠️ 自定义系统提示 - 使用AlfredoTool微调节点行为
• 📦 预建代理 - 探索代理和反思代理，随时可用

安装

注意： Alfredo 尚未在PyPI上提供。请从GitHub直接安装，使用uv：

# 克隆仓库
git clone https://github.com/biocypher/alfredo.git
cd alfredo

# 安装依赖
uv sync

# 或者将它作为依赖添加到你的项目中
uv add git+https://github.com/biocypher/alfredo.git

快速开始

from alfredo import Agent

# 创建一个代理
agent = Agent(
    cwd=".",
    model_name="gpt-4.1-mini",  # 或 "anthropic/claude-3-5-sonnet-20241022"
    verbose=True
)

# 运行任务 - 代理将进行计划、执行和验证
agent.run("创建一个使用蒙特卡洛方法计算π值近似的Python脚本")

# 查看执行跟踪
agent.display_trace()

# 访问结果
print(agent.results["final_answer"])

具备视觉能力的代理

Alfredo代理可以使用视觉模型分析图像，使代理能够验证自己的视觉输出：

from alfredo import Agent

# 创建一个具备视觉能力的代理
agent = Agent(
    cwd=".",
    model_name="gpt-4.1-mini",       # 规划和推理的主要模型
    vision_model="gpt-4.1-mini",     # 图像分析的视觉模型
    parse_reasoning=True
)

# 代理创建可视化并通过查看图像来验证它
agent.run("""
创建一个使用蒙特卡洛方法计算π值近似的Python脚本。
同时创建结果的可视化并将其保存为PNG文件。
通过分析图像确保绘图正确。
如果缺少某些包，请使用uv初始化一个虚拟环境，然后添加缺失的包。
""")

# 查看执行跟踪以观察视觉工具的实际操作
agent.display_trace()

发生的过程：

1. 代理编写蒙特卡洛模拟代码
2. 代理运行代码并生成图表
3. 代理使用analyze_image验证可视化是否正确
4. 如果发现问题，代理会迭代

视觉用例：

• 📸 屏幕截图分析用于UI测试
• 📊 图表和图形验证
• 📝 OCR和文档处理
• 🎨 图像描述和字幕
• ✅ 视觉质量保证

架构

Alfredo 使用一个 LangGraph状态图，包含以下节点：

START → 规划器 → 代理 ⇄ 工具 → 验证器
                   ↑              ↓
                   └── 重新规划 ←──┘

• 规划器：创建实施计划
• 代理：执行ReAct风格的推理和工具调用
• 工具：执行工具调用
• 验证器：检查任务是否完成
• 重新规划：如果验证失败，生成改进的计划

可以禁用规划，直接从代理节点开始执行。

阅读更多：代理架构 →

可用工具

Alfredo 包含11个内置工具，按类别组织：

类别	工具
文件操作	read_file, write_to_file, replace_in_file
发现	list_files, search_files
代码分析	list_code_definition_names
命令	execute_command
视觉	analyze_image
工作流	ask_followup_question, attempt_completion

阅读更多：工具文档 →

MCP集成

Alfredo 支持两种MCP集成模式：

CodeAct模式

从MCP服务器生成可导入的Python模块，允许代理像普通函数一样使用工具，而不是通过ReAct循环：

from alfredo import Agent

# 配置远程MCP服务器（支持本地和远程）
agent = Agent(
    cwd="./workspace",
    model_name="gpt-4.1-mini",
    codeact_mcp_functions={
        "biocontext": {
            "url": "https://mcp.biocontext.ai/mcp/",  # 远程或本地服务器
        }
    },
    verbose=True
)

# 代理现在可以在脚本中导入和使用MCP工具：
agent.run("编写一个获取基因ENSG00000141510的互作蛋白并保存到interactors.txt的脚本")

# 代理生成的代码类似：
# from biocontext_mcp import bc_get_protein_interactors
# result = bc_get_protein_interactors(gene_id="ENSG00000141510")

特性：

• ✅ 支持远程服务器（例如，https://mcp.biocontext.ai/mcp/）
• ✅ 支持本地服务器（例如，http://localhost:8000）
• ✅ 自动生成类型化的Python包装模块
• ✅ 支持SSE和JSON-RPC 2.0协议
• ✅ 带自动重试的会话管理
• ✅ 基于脚本的工具链

ReAct模式

直接通过LangChain的工具调用来使用MCP工具：

from alfredo import Agent
from alfredo.integrations.mcp import load_combined_tools_sync

# 配置MCP服务器
server_configs = {
    "biocontext": {
        "transport": "streamable_http",
        "url": "https://mcp.biocontext.ai/mcp/",
    }
}

# 加载Alfredo + MCP工具
tools = load_combined_tools_sync(cwd=".", mcp_server_configs=server_configs)

# 创建带有组合工具集的代理
agent = Agent(cwd=".", tools=tools)
agent.run("获取人类TP53的互作蛋白并将结果保存到tp53_interactors.txt文件中")

阅读更多：MCP集成 →

自定义系统提示

使用AlfredoTool向任何工具添加特定于节点的指令：

from alfredo.tools.alfredo_tool import AlfredoTool

# 添加仅出现在特定节点的指令
tool = AlfredoTool.from_alfredo(
    tool_id="write_todo_list",
    cwd=".",
    system_instructions={
        "planner": "在制定计划后，创建一个初始检查清单以跟踪进度",
    }
)

# 指令动态注入到节点系统提示中
agent = Agent(cwd=".", tools=[tool])

阅读更多：AlfredoTool & 系统提示 →

预建代理

探索代理

探索目录并生成综合的markdown报告，智能地读取文件和数据分析：

from alfredo.prebuilt import ExplorationAgent

agent = ExplorationAgent(
    cwd="./my_project",
    context_prompt="数据属于癌症细胞系的转录组学研究"
)
report = agent.explore()

反思代理

使用网络搜索进行迭代自我批评和修订的研究代理：

from alfredo.prebuilt import ReflexionAgent

agent = ReflexionAgent(model_name="gpt-4.1-mini", max_iterations=2)
answer = agent.research("创建一份关于TP53在癌症细胞系中的角色的详细报告，并将结果保存到tp53_roles.md文件中")
agent.display_trace()

阅读更多：预建代理 →

文档

• 代理架构 - 深入了解LangGraph框架
• 工具 - 完整的工具参考和创建自定义工具
• MCP集成 - 使用模型上下文协议服务器
• AlfredoTool - 按节点定制系统提示
• 预建代理 - 探索代理和反思代理

开发

# 安装依赖
make install

# 运行测试
uv run pytest

# 运行带有覆盖率的测试
uv run pytest --cov=src

# 代码检查和类型检查
uv run ruff check src
uv run mypy src

许可证

根据MIT许可证发布。

致谢

工具系统设计灵感来自Cline - 一个用于VSCode的AI编码代理。

---

仓库由fpgmaas/cookiecutter-uv初始化。