AgentEra/Agently · 上手攻略

• 仓库：AgentEra/Agently
• 链接：https://github.com/AgentEra/Agently
• 分类：ai / agent / framework
• 作者：spark
• 更新：2026-07-28

是什么

Agently（pip install agently）是一个 Python GenAI 应用开发框架，主打"让模型输出稳定可控、让 AI 服务像后端服务一样可观测、可恢复"。它的核心抽象是 AgentExecution：把一次推理涉及的 prompt、策略、Actions、Skill 绑定、process 流、TaskContext 证据、结果视图统一收口，因此换模型、换 provider、改 schema，都不会把业务代码搞乱。

框架当前版本是 4.1.4.4（PyPI 上 agently），要求 Python ≥ 3.10。它的关键能力可以一句话总结：统一的请求/运行时契约 + 结构化输出兜底 + 事件驱动工作流。

主要特性：

• 结构化输出是框架层保证，不只是 provider 特性：.output(...) schema、required-field 抽取、parser 反馈、重试、ensure_keys / ensure_all_keys、验证处理器，全在框架里。
• 模型无关：不同 provider 走同一套 prompt slot / response parsing / Action Runtime，迁移不用改业务代码。
• Streaming 暴露结构：instant 模式让消费方在模型还在流式输出时就能拿到结构化字段（用于 UI 更新、SSE 路由、workflow 信号）。
• Action 可观测、模型可移植：本地函数、内置 Action、MCP servers、shell / Python / Node / SQLite / TaskWorkspace helper、自定义 executor，全部走统一的 Action Runtime，输出结构化记录。
• SkillLibrary + 不可变指引：技能版本化管理，AgentExecution 拥有精确版本绑定，TaskContext 拥有披露控制，避免"隐性提示注入"。
• Execution Resource 有生命周期：MCP 进程、浏览器 session、shell/Python/Node 运行时、SQLite handle、沙箱统一管理。
• Dynamic Task 把模型生成的 DAG 变成可验证任务图：Agently.create_dynamic_task(...)。
• TriggerFlow 工作流：事件驱动、fan-out、runtime streams、pause/resume、save/load、子流、close snapshots；结构化输出可以"边流边喂"给 workflow。
• FastAPI / Settings / Prompt 文件 / DevTools 观测：偏项目工程化的辅助。

许可证 Apache-2.0。

解决什么问题

当你从"模型 demo"走到"业务里跑的 AI 服务"时，会撞到几面墙：

1. 结构化输出漂移：模型有时返回 JSON、有时返回 prose；provider 的 JSON schema 还不一样。
2. 模型一换业务代码重写：从 OpenAI 换到 DeepSeek、从 Anthropic 换到本地 vLLM，prompt slot、tool calling 语义、流式协议都不同。
3. Action 难以观察、难以回放：agent 调了什么工具、返回了什么、为什么失败，没有统一日志。
4. Workflow 是图，不是信号：用 LangGraph 那种纯 DAG 模型，结构化流式输出很难驱动"边流边决策"。
5. 多 agent 不是产品本身：很多场景只是想在请求 / Action / 信号上做组合，而不是把"agent 对话"作为唯一边界。

Agently 的设计取舍是：把"请求契约 + 结构化输出 + Action + Workflow"做成统一基座，多 agent、router、reflection、evaluator/reviser 等常用模式都是这层之上的可组合模式。

快速安装

# Python >= 3.10
pip install -U agently agently-devtools

# 可选：本地观测 DevTools
agently-devtools start

agently-devtools 与 agently 4.1.4.x 配套，推荐版本 >=0.1.10,<0.2.0（按 PyPI 当前推荐范围）。生产环境建议锁版本，例如：

pip install 'agently==4.1.4.4' 'agently-devtools>=0.1.10,<0.2.0'

核心用法

下面示例的 API 形态参考 4.1.4.x 文档。具体参数名以 Requests Overview 与 Model Setup 为准。

1. 启动 Agently 并配置模型

from agently import Agently

Agently.set_settings(
    "OpenAICompatible",
    {
        "base_url": "https://api.openai.com/v1",   # 或 vLLM / DeepSeek / Ollama / Moonshot 等
        "api_key":  "sk-...",                       # 也可走环境变量
        "model":    "gpt-4o-mini",
    },
)

agent = Agently.create_agent()

切换 provider 时只改 set_settings(...)，下游业务代码不动——这是 Agently 最被强调的一点。

2. 链式调用 + 结构化输出

from pydantic import BaseModel, Field

class PlanItem(BaseModel):
    step: int
    action: str = Field(description="本步要执行的动作")
    detail: str = Field(description="动作细节")

class Plan(BaseModel):
    items: list[PlanItem]

result = (
    agent
    .input("为一个 1500 字的博客文章列一份三段式的写作大纲")
    .output(Plan)
)

print(result.model_dump())

.output(Plan) 把 Pydantic schema 翻译成 schema-as-prompt 指令，结合 ensure_keys / ensure_all_keys 与 parser 反馈重试，把"少字段 / 字段类型错 / 多了杂项"这些常见问题挡在框架层。

3. Streaming 结构化输出

async for chunk in agent.input("解释 RaBitQ").output_as_stream(dict):
    # chunk 里已经能拿到结构化字段（instant mode）
    print(chunk)

这种"边流边拿结构"的体验对前端 SSE、UI 实时更新、workflow 输入都很关键。

4. Action Runtime + MCP

from agently import Agently
from agently.actions import ActionRuntime

@ActionRuntime.register("search_docs")
def search_docs(query: str, top_k: int = 5):
    """本地检索"""
    return [{"title": q, "score": 0.9 - i*0.05} for i, q in enumerate([query]*top_k)]

agent = Agently.create_agent()
agent.register_action("search_docs", search_docs)

resp = agent.input("在知识库查 'VectorChord'").output({"answer": str, "sources": list})

MCP server 同样接入 Action Runtime，shell / Python / Node / SQLite 等执行环境由 Execution Resource 提供生命周期管理。

5. TriggerFlow 事件驱动工作流

from agently.triggerflow import TriggerFlow

flow = TriggerFlow()

@flow.on("user_input")
async def handle(evt, ctx):
    plan = await agent.input(evt["text"]).output({"steps": list})
    return plan

@flow.on("step_done")
async def next_step(evt, ctx):
    # 用结构化输出驱动下一步
    ...

# 支持 pause / resume / save / load / 子流 / 快照

事件驱动 + 快照能力让长流程 AI 服务具备"服务级"的可恢复性。

6. FastAPI 暴露

官方提供 FastAPI helpers（docs/en/services/fastapi.md），把 agent 直接挂到 HTTP 路由上，配合 SSE 输出流式结构化结果，适合做企业内部 AI 后端。

典型适用场景

• 企业内部 AI 服务后端：合同抽取、报表分析、工单分类、运营自动化。需要稳定结构化输出 + 可观测 + 可恢复。
• RAG / 知识工具：检索作为 Action 注册进 Runtime，模型只负责规划与综合。
• 多步 Agent 工作流：审批、反思、修订（reflection / reviser / evaluator）、Router。
• 需要多 provider 兜底：高峰期 OpenAI，平时本地 vLLM，Agently 让切换无感。
• 面向 Coding Agent 的项目骨架：仓库自带 Agently-Skills 系列 skill，让 Codex / Claude Code 等 coding agent 直接遵循官方约定生成代码。

不太适合：

• 一两行 prompt 的小脚本：直接用 OpenAI SDK 更轻。
• 以"agent 对话"作为唯一产品形态：CrewAI / AutoGen 更对位。
• 强图模型、低代码可视化编排：LangGraph / LangChain 的图形化生态更成熟。

坑与注意

1. 学习曲线比 LangChain 陡：Agently 不是"工具集成超市"，而是统一契约 + 生命周期管理。刚入手先读 Requests Overview / Action Runtime / TriggerFlow Overview 三篇。
2. 结构化输出不等于"模型自己保证 JSON"：必须配合 output(Schema) + ensure_keys + parser 反馈重试链路一起用，否则弱模型仍可能漂移。
3. Streaming + 结构化是 instant mode：要前端配合按字段增量更新；传统 SSE 只发 token 的体验就不够用了。
4. Action 一定要可幂等 / 可重试：Action Runtime 会被 workflow 自动重放，副作用要可恢复。
5. 版本节奏快：4.1.4 → 4.1.4.4 期间有 ensure_keys、snapshot 策略等行为变化，升级前一定读 Release Notes（docs/en/development/release-notes-*.md）。
6. 多 agent 不是默认边界：官方明确把"多 agent"作为可构建模式，不要把它当作产品唯一形态硬套。
7. 小项目慎用：如果只是一个 chat completion 包装，Agently 的结构化输出 + Action + TriggerFlow 三件套反而是负担。
8. 中文文档同步：仓库有 README_CN.md，但 API 细节仍以英文 docs 为准。

与同类对比

简单的判断标准：

• 想要"少即是多、统一契约、长期可维护" → Agently。
• 想要"工具 / 集成 / 文档生态最厚" → LangChain / LangGraph。
• 想要"多 agent 对话即产品" → CrewAI / AutoGen。
• 只是几个 prompt → 直接 SDK。

一句话推荐结论

Agently 适合把 GenAI 应用做成"工程化后端服务"的团队：结构化输出、Action 可观测、TriggerFlow 可恢复这三件事在框架层都打通了——但如果你只是想快速拼一个 chat demo，直接 SDK 会更省事。