Agently AI 应用运行时
用统一请求、动作与事件流构建可验证的 AI 服务后端。
按维度查看评分与理由
证据显示框架提供细粒度的权限控制，如工作区访问模式（snapshot）、执行资源生命周期管理（grant/ensure/materialize/execute/release/close），以及超时和清理失败诊断，表明最小权限原则得到较好处理。但用户确认机制仅在文档中提及（如人工审核），未在代码中明确体现，故扣分。数据流透明度方面，action_logs、artifact_refs 和诊断信息提供了可观测性，但未全面覆盖所有数据流。敏感数据处理未明确说明，如 API 密钥管理仅通过环境变量引用，未提供加密存储。依赖安全方面，依赖版本有范围限制，但未提供漏洞扫描或安全审计证据。外部影响方面，框架支持 shell、python 等执行，但文档强调需显式启用和策略控制，故给2分。回滚机制在 TriggerFlow 的持久化和快照中有所体现，但未明确提供回滚操作。来源归属方面，作者信息在 pyproject.toml 中列出，但未提供贡献者指南或详细归属。
自一致性方面，README 与代码示例一致，版本号在 README 和 pyproject.toml 中略有差异（4.1.4.5 vs 4.1.4.6），但整体一致。依赖可用性方面，依赖列表明确，且使用版本范围，但未提供锁定文件。失败消息方面，测试覆盖了超时、释放失败等场景，并提供了诊断代码，表明失败处理较好。
受众和场景明确，针对产品工程师、平台团队等，并提供了多种场景示例。能力边界方面，文档区分了框架与直接 SDK 调用的适用场景，但未明确列出所有内置能力。触发精度方面，TriggerFlow 支持事件、条件分支等，但未详细说明触发条件。环境适配方面，支持多种模型提供商和本地 Ollama，但未提供容器化或部署指南。
信息架构清晰，文档结构完整，有快速开始、核心能力、架构等。安装说明简单，但未提供虚拟环境或依赖管理建议。命名稳定性方面，API 名称在版本间有变化（如 tool_func 到 action_func），但文档说明了兼容性。示例和 FAQ 丰富，但未提供 FAQ 部分。已知限制未明确列出。许可证为 Apache-2.0，完整。版本变更日志存在，但未提供 CHANGELOG 文件。维护责任方面，作者信息明确，但未提供贡献指南。
输出可用性方面，提供结构化输出、流式输出等，但未提供输出格式的详细文档。边际价值方面，框架提供了模型切换、结构化输出等独特功能，但与其他框架的对比未量化。成本效益方面，未提供性能基准或资源消耗数据。
声明可追溯性方面，README 中的功能声明有对应的文档链接和示例，但未提供测试覆盖率。跨来源佐证方面，仅依赖单一仓库，未提供外部验证。事实与推断分离方面，文档区分了功能描述和设计意图，但未明确标注。
- 版本号不一致：README 显示 4.1.4.5，而 pyproject.toml 显示 4.1.4.6，可能造成混淆。
- 敏感数据处理未明确：API 密钥仅通过环境变量引用，未提供加密存储或安全建议。
- 依赖安全未提供漏洞扫描或审计证据，建议使用锁定文件。
- 用户确认机制仅在文档中提及，未在代码中明确实现，需谨慎依赖。
- 已知限制未列出，可能隐藏潜在问题。
这个 Agent 能做什么，适合哪些场景？
Agently 是一个 Python AI 应用运行时框架，当前版本为 4.1.4.5，面向需要稳定输出、可观察执行和可恢复流程的服务端应用。其 AgentExecution 将单次运行的提示、策略、Actions、Skill 绑定、过程流、TaskContext 与结果视图组织在一起，并通过 ModelRequest 处理提示槽、模型调用和响应解析。框架提供 .output(...) 架构、必填字段提取、解析反馈、重试和验证，以及可在流式过程中消费结构化字段的 instant 模式。Action Runtime 可调用本地函数、MCP 服务器及 Python、Shell、Node、SQLite 等能力；TriggerFlow 则提供事件驱动的分支、并发、暂停/恢复、持久化与关闭快照。它还提供 FastAPIHelper，用于以 POST、SSE 和 WebSocket 暴露请求、Agent 和 TriggerFlow 执行。
应用先用 Agently.set_settings(...) 或 Agently.load_settings("yaml_file", "settings.yaml", auto_load_env=True) 配置模型，再以 Agently.create_agent() 创建 Agent。调用方通过 .role(...)、.info(...)、.instruct(...)、.input(...) 和 .output(...) 组装请求，以 .get_result() 获取 AgentExecutionResult，并读取 get_data()、get_full_data()、get_text() 或 get_meta()。需要渐进式界面或下游处理时，可遍历 result.get_generator(type="instant") 接收字段路径、增量和值；最终数据在校验完成后由 get_data() 提供。模型可通过 @agent.action_func 和 agent.use_actions(...) 调用本地函数，也可使用 agent.use_mcp(...)、enable_python()、enable_shell(...)、enable_workspace(...)、enable_nodejs() 或 enable_sqlite(...) 扩展执行能力，并从 action_logs 和 artifact_refs 读取执行记录与产物。对于多步骤流程，TriggerFlow.create_execution()、async_start(...)、async_emit(...) 和 async_close() 执行并产出关闭快照；Dynamic Task 通过 Agently.create_dynamic_task(...) 验证并运行 DAG 数据。
- 负责内部客服后端的产品工程师，需要在 DeepSeek 或其他 OpenAI 兼容端点之间切换，同时让下游代码继续读取固定的结构化字段。
- 构建 SSE 或 WebSocket 界面的服务团队，希望在模型输出尚未结束时，依据 instant 事件逐步展示定义、列表项或其他结构化字段。
- 需要让模型计算、检索或操作受控运行时能力的 Python 开发者，可将本地函数、MCP 服务或 Shell/Python/SQLite 能力注册为 Actions，并保留 action_logs。
- 处理工单、人工审批或 Webhook 的运营系统团队，需要用 TriggerFlow 编排分支、fan-out、外部事件、暂停恢复和可保存的执行状态。
- 将模型生成的计划作为数据提交的应用开发者，需要先由 TaskDAG 验证有向无环图，再执行 Dynamic Task，而不是直接生成新的流程定义。
这个 Agent 有哪些优点和局限？
- 将不同模型提供方的设置、提示槽、响应解析、动作执行和结果读取统一到同一请求/运行时契约，支持 OpenAI 兼容端点和 Anthropic 原生 API。
- 结构化输出不仅依赖提供方特性：.output(...)、ensure_keys、ensure_all_keys、解析反馈、重试和验证处理器共同约束结果。
- instant 结构化流可在最终响应前产生字段级事件，适合 SSE、界面更新和工作流信号。
- Action Runtime 记录结构化动作日志和产物引用，并可结合 MCP 与受生命周期管理的执行资源。
- TriggerFlow 提供事件、并发 fan-out、暂停/恢复、save/load 和 close snapshot，适合长流程服务。
- 框架要求 Python >=3.10，且真实模型调用需要配置模型端点和相应 API 密钥或本地 Ollama。
- 文档明确建议：只有一两个简单提示时应更接近直接 SDK 调用；引入 AgentExecution、Actions 和 TriggerFlow 会增加工程结构。
- instant 更新被定义为暂定结果；在执行不可逆副作用或业务决策前仍须等待最终校验完成。
- 复杂服务还需自行配置宿主协程上限、TriggerFlow 并发、模型速率/并发限制和阻塞代码线程池。
- 旧 tool_func/use_tools/use_mcp/use_sandbox API 仍是兼容层，但新代码应迁移到 Actions API，存在维护迁移成本。
如何安装或部署这个 Agent？
运行环境要求 Python >=3.10。安装：pip install -U agently。配置一个 OpenAI 兼容模型端点时，需提供端点、模型名和 API 密钥，例如：Agently.set_settings("OpenAICompatible", {"base_url": "https://api.deepseek.com/v1", "model": "deepseek-chat", "api_key": "${ENV.DEEPSEEK_API_KEY}", "model_type": "chat", "request_options": {"temperature": 0.2}})。本地 Ollama 的示例先执行 ollama pull qwen2.5:7b，再将 base_url 设为 http://127.0.0.1:11434/v1、model 设为 qwen2.5:7b、api_key 设为 ollama。
如何使用这个 Agent？
最小调用：from agently import Agently；配置模型后执行 agent = Agently.create_agent()，然后链式调用 agent.input("Introduce Python in one sentence.").output({"intro": (str, "one sentence", True)}).get_result()，最后用 result.get_data() 读取结构化结果。若使用文件配置，可调用 Agently.load_settings("yaml_file", "settings.yaml", auto_load_env=True)；YAML 中可在 plugins.ModelRequester.OpenAICompatible 下设置 base_url、api_key 和 model。需要服务暴露时使用 FastAPIHelper；需要可恢复流程时创建 TriggerFlow 执行，完成后显式调用 async_close() 获取关闭快照。
这个 Agent 与同类方案有什么区别？
与 LangChain 相比，Agently 更强调统一的请求契约、输出解析、验证和 Action Runtime，而非广泛集成优先。与 LangGraph 相比，TriggerFlow 以事件/信号驱动为核心，并可把结构化流事件、动作结果和外部事件纳入同一流程。与 CrewAI 或 AutoGen 相比，它将多智能体协作视为可由请求、Actions、Session 与 TriggerFlow 组合出的模式，而非默认根模型。对于仅有少量简单提示的产品，仓库建议直接使用提供方 SDK。