KodeAgent
用轻量 Python 核心构建可规划、调用工具或执行代码的 AI 代理。
- Star 数
- ★ 40
- 最近更新
- 1 个月前
- License
- Apache-2.0
- 主语言
- Python
- FA 评分
- 43/100 · 缺口较多
30 秒速览
- 可在哪里用
- 通用 · 跨平台OpenAI API · Claude API
- 开始前需要
- 典型场景
- 需要在现有 Python 服务中加入网页检索与页面读取能力的开发者，可用 ReActAgent 配合 search_web 和 read_webpage 完成多步研究任务。
- 主要局限
- 项目明确说明仍在积极演进，部分行为可能变化，能力也有限。
这个 Agent 能做什么，适合哪些场景？
KodeAgent 是一个无框架、轻量化的 Python AI 代理引擎，定位为嵌入更大系统的推理核心，而不是完整平台。它提供 ReActAgent、CodeActAgent 和 FunctionCallingAgent，并以 LiteLLM 连接 Gemini、GPT、Claude 与 Ollama 等模型或提供商。代理以异步流式方式通过 agent.run(task) 返回过程更新，完成后可从 agent.task.result 取得结果。CodeActAgent 可在本机 host 或 E2B 沙箱中执行模型生成的 Python 代码；CSVAnalysisAgent 则可从 URL 或路径加载 CSV 并执行自动分析。默认任务之间不保留记忆，但可使用 recurrent_mode 传入上一任务上下文，或注入兼容 OpenAI 格式的聊天历史。
开发者创建 ReActAgent、CodeActAgent 或 FunctionCallingAgent，传入 model_name、同步 Python tools 及迭代上限，然后通过 async for response in agent.run(task) 消费流式响应。ReActAgent 可直接调用如 search_web、read_webpage、calculator 等工具；CodeActAgent 会为任务创建计划，在循环中让模型生成 Thought 与 Python Code，执行工具调用并把观察结果回传给 Planner。CodeActAgent 可在 run_env='host' 的应用主机执行代码，或在 run_env='e2b' 的 E2B 沙箱执行，并可将沙箱生成文件下载至已有的 work_dir。内置工具还包括下载文件、提取 Markdown、搜索 arXiv/Wikipedia、生成图像及音频或 YouTube 转录；用户也可把自己的同步 Python 函数作为 tools 传入。可选的 tracing_type='langfuse' 或 'langsmith' 将运行追踪交给相应服务，默认使用无操作追踪器。
- 需要在现有 Python 服务中加入网页检索与页面读取能力的开发者，可用 ReActAgent 配合 search_web 和 read_webpage 完成多步研究任务。
- 需要让模型编写并运行 Python 来组合多个工具的工程团队，可用 CodeActAgent，并在受控需求下选择 E2B 沙箱执行。
- 使用支持原生函数调用的小语言模型、需要处理短暂失败重试与错误检测的开发者，可采用 FunctionCallingAgent。
- 需要从本地路径或 URL 载入 CSV 并让代理自动探索数据的分析人员，可使用 CSVAnalysisAgent。
- 需要将会话状态存入外部数据库、之后恢复上下文的应用开发者，可向 agent.run 注入 OpenAI 兼容 chat_history。
如何安装或部署这个 Agent？
运行 pip install -U kodeagent。运行环境需为 Python 3.10、3.11、3.12 或 3.13。为所选模型提供商设置对应环境变量，例如 Gemini 使用 GOOGLE_API_KEY，OpenAI 使用 OPENAI_API_KEY，Anthropic 使用 ANTHROPIC_API_KEY；使用 E2B 时还需 E2B_API_KEY。如从源码运行，可执行 git clone https://github.com/barun-saha/kodeagent.git，创建并激活虚拟环境后执行 pip install -r requirements.txt。
如何使用这个 Agent？
先导入 ReActAgent 与所需工具，创建例如 ReActAgent(name='Web agent', model_name='gemini/gemini-2.5-flash-lite', tools=[search_web, read_webpage], max_iterations=5) 的实例。随后执行 async for response in agent.run('What are the festivals in Paris? How they differ from Kolkata?'):，并用 print_response(response, only_final=True) 输出最终响应。要执行生成代码，改用 CodeActAgent，并显式指定 run_env、允许的 allowed_imports 以及需要时的 pip_packages。若启用 E2B，可指定一个已存在的 work_dir 作为本地文件交换目录。
这个 Agent 有哪些优点和局限？
- 同一库直接提供 ReAct、CodeAct 和原生函数调用三种代理模式，调用接口围绕 Python 类与 agent.run 保持一致。
- 基于 LiteLLM，可在不改动核心逻辑的情况下切换 Gemini、GPT、Claude 或 Ollama 等模型与提供商。
- CodeActAgent 支持本机与 E2B 两种代码执行环境，并可把 E2B 产生的文件同步到本地工作目录。
- 支持手动注入 OpenAI 兼容聊天历史，便于由外部存储系统负责跨会话状态。
- 项目明确说明仍在积极演进，部分行为可能变化，能力也有限。
- 默认跨任务无记忆；没有自动化的长期持久记忆管理或内置持久化层。
- CodeActAgent 会执行模型生成的代码；项目要求在受限、非生产环境中审查和测试生成代码。
- E2B 执行需要 E2B_API_KEY；LangSmith 不默认安装，使用时需额外安装并配置凭据。
- 自定义工具只能是同步 Python 函数，异步工具不受支持。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|
| KodeAgent 当前 | 43 · 缺口较多 | ★ 40 | 1 个月前 | Python | OpenAI API · Claude API |
| CaveAgent | 62 · 存在缺口 | ★ 202 | 8 天前 | Python | OpenAI API · Claude API |
| 从零构建 AI 智能体 | 28 · 缺口较多 | ★ 4.8k | 2 个月前 | JavaScript | — |
| Langroid 多智能体框架 | 70 · 存在缺口 | ★ 4.1k | 7 天前 | Python | Claude Code · OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：CodeActAgent 支持 host 和 e2b 两种执行环境，host 模式直接在本地执行 LLM 生成的代码，存在权限提升风险，但提供了 allowed_imports 和 pip_packages 限制，属于部分最小权限措施。用户确认机制缺失，没有发现任何人工审批或确认步骤。数据流透明度有限，README 描述了工具和追踪，但未详细说明数据如何流转。敏感数据处理方面，API 密钥通过环境变量管理，但未说明加密或保护措施。依赖安全方面，有 Snyk 徽章和依赖版本固定，但未提供漏洞报告详情。外部影响方面，工具如 download_file 和 generate_image 可能产生外部副作用，但未提供沙箱或限制。回滚机制缺失。来源归属方面，README 致谢了多个项目，但未提供详细的代码来源追踪。扣分原因：缺少用户确认、回滚机制，数据流和敏感数据处理不透明，依赖安全证据不足。
证据显示：README 和代码示例在多个地方保持一致，如工具列表和用法，但未提供完整的 API 文档。依赖可用性方面，requirements.txt 固定了版本，但 arxiv 依赖被禁用，可能影响功能。失败消息方面，README 提到 Observer 检测循环和停滞，但未提供具体的错误处理示例。扣分原因：依赖可用性因 arxiv 问题而降低，失败消息证据不足。
证据显示：README 提供了多种使用场景，如 ReAct、CodeAct、FunctionCalling 和任务特定代理，并提供了 Colab 笔记本。能力边界方面，明确说明了不支持持久化记忆和异步工具。触发精度方面，工具是显式传入的，但未说明触发条件。环境适配方面，支持多种 Python 版本和操作系统，但未提供详细的部署指南。扣分原因：触发精度证据不足，环境适配缺少详细说明。
证据显示：README 结构清晰，包含快速开始、工具、内存管理、代码执行、可观测性等章节。安装说明详细，包括 pip 和源码安装。命名稳定性方面，版本号存在，但未提供变更日志。示例和 FAQ 方面，提供了多个示例，但缺少 FAQ。已知限制方面，README 明确列出了不适用场景。许可证为 Apache-2.0，完整。版本控制方面，有 GitHub Actions 发布流程，但未提供变更日志。维护责任方面，作者信息在 pyproject.toml 中，但未明确维护计划。扣分原因：缺少变更日志和 FAQ，维护责任不明确。
证据显示：输出可用性方面，提供了 print_response 函数和流式输出，但未提供结构化输出格式。边际价值方面，提供了多种代理类型和工具，但与其他框架相比优势不明显。成本效益方面，依赖较少，但未提供性能基准。扣分原因：输出格式和性能基准证据不足。
证据显示：README 中的声明部分有代码示例支持，但未提供独立的验证。跨来源佐证方面，有 PyPI 和文档链接，但未提供第三方验证。事实与推断分离方面，README 区分了功能和限制，但未明确标注哪些是推断。扣分原因：验证证据不足，跨来源佐证有限。
- 源码中未见：执行前用户确认开启或自行加上执行前确认；先在沙箱或测试环境跑通，确认行为后再接入真实数据。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- CodeActAgent 的 host 模式直接在本地执行 LLM 生成的代码，存在安全风险，应限制在隔离环境中使用。
- 缺少用户确认机制，代理可能执行未经用户批准的操作。
- 依赖 arxiv 被禁用，可能影响相关功能。
- 未提供回滚机制，错误操作可能难以恢复。