Agently Docs

Agently documentation for building AI applications with stable outputs, observable actions, and durable workflows.

View the Project on GitHub AgentEra/Agently

Agently 4.1.3 Release Notes

语言：English · 中文

Agently 4.1.3 是 4.1.2 运行时基础正式连成 AI 应用运行时的一版。

这一版的重点不是再列一组新增 API，而是让一次 Agent turn 可以把模型推理、 Actions、远程 Skills、MCP 工具、Dynamic Task DAG、运行过程流、结构化输出和 companion coding-agent 指引放进同一条工程路径里。

4.1.2 建立了运行时基础能力。4.1.3 把这些基础能力连接成默认应用路径，使 Agently 可以支撑真实 AI 服务，而不只是 prompt demo。

核心结果

Agently 现在可以作为生产级 AI 服务后端的执行基座：

业务输入
  -> Agent
  -> 候选 Actions / Skills / Dynamic Task
  -> 模型参与规划和执行
  -> ActionRuntime / ExecutionEnvironment / TriggerFlow
  -> 流式过程事件
  -> 结构化业务输出

真实 AI 服务需要的不只是文本生成。它们需要稳定的输出契约、可观测的工具调用、 外部系统边界、可恢复的执行过程，以及让开发者和 coding agent 都能遵循的当前 推荐路径。

Agent 成为默认运行时入口

agent.start() 现在是一次候选能力感知 Agent turn 的默认用户层入口。调用方仍然 拿到业务结果；当显式声明了候选能力时，Agent 可以路由到普通模型响应、Actions、 Skills Executor 或 Dynamic Task。

result = (
    agent
    .use_actions([lookup_customer, fetch_contract, notify_owner])
    .use_skills(
        [{"source": "anthropics/skills", "subpath": "skills/docx"}],
        mode="model_decision",
    )
    .use_dynamic_task(mode="auto", max_tasks=8)
    .input({"customer_id": "C-1024", "ticket": "payment failure"})
    .output({
        "summary": (str, "business summary", True),
        "risk_level": (str, "low / medium / high", True),
        "next_actions": ([str], "recommended actions", True),
    })
    .start()
)

业务价值：应用代码只需要描述一次业务任务可用的能力，运行时负责选择和执行合适 路径，而不是把服务写成手工 prompt 拼接。

Execution Object 和过程流

需要丰富阶段反馈的服务，可以把同一个 Agent turn 创建为 execution object。它的 核心价值不只是日志和诊断，而是在任务仍在运行时，把任何阶段的具体运行信息暴露给 调用方、前端 UI 或下游服务。

execution = (
    agent
    .use_dynamic_task(mode="submitted", plan=graph, handlers=handlers)
    .input({"ticket": "T-42"})
    .create_execution()
)

async for item in execution.get_async_generator(type="instant"):
    send_to_ui(item.path, item.value)

data = await execution.async_get_data()
meta = await execution.async_get_meta()

业务价值：前端不再只能显示黑盒 loading。它可以展示路由决策、调研发现、图就绪、 任务开始、Action 调用、工具结果、字段增量、approval 或 blocked 状态、中间产物和 最终结构化输出。日志和诊断是同一条过程流的重要次级消费者。

Skills 成为运行时能力

agent.use_skills(...) 现在是推荐的 Agent 级 Skills 声明入口。它的默认模式是 model_decision：由 planner 判断是否使用、以及使用哪些已声明 Skills。业务代码 声明候选 source；Skills Executor 负责轻量发现、规划选择、按需 materialize、 能力挂接、诊断和执行。

agent.use_skills(
    [
        {"source": "GarethManning/education-agent-skills"},
        {"source": "anthropics/skills", "subpath": "skills/docx"},
        {"source": "anthropics/skills", "subpath": "skills/pptx"},
        {"source": "anthropics/skills", "subpath": "skills/xlsx"},
    ],
    mode="model_decision",
)

execution = await agent.async_run_skills_task(
    "Create a four-week B1 business English course package.",
    effort="normal",
    output={
        "course_plan": (dict, "course goals, weekly structure, and lesson sequence", True),
        "teacher_guide": (str, "teacher-facing guide summary", True),
        "student_handout_plan": (str, "student material plan", True),
        "progress_tracker": ([str], "progress tracking columns and checkpoints", True),
    },
)

业务价值：Skills 不再是业务代码里内联的 prompt 片段，而是可复用的运行时能力。 团队可以指向公开或私有 Skill 仓库，保留本地目录作为开发方式，并让运行时只安装 当前任务真正需要的资源。

MCP 和脚本能力走运行时边界

包含 MCP、shell 或脚本声明的 Skills 由 Skills Executor 解释，再通过已有 ActionRuntime 和 ExecutionEnvironment 边界挂接。Skill 不会变成第二套工具系统。

agent.use_skills(
    [{"source": "owner/skills-with-mcp", "trust_level": "remote"}],
    mode="required",
    auto_allow=False,
)

如果被选中的 Skill 声明了 HTTP MCP，执行时会自动挂接。如果声明的是 stdio、 npx、本地命令 MCP、shell 或脚本执行，运行时需要显式审批或 auto_allow=True：

agent.use_skills(
    [{"source": "owner/skills-with-local-mcp", "auto_allow": True}],
    mode="required",
)

当 MCP 服务是应用自己拥有的能力，而不是 Skill 自己声明的能力时，仍然可以直接注册：

await agent.use_mcp({
    "mcpServers": {
        "market_data": {
            "command": "npx",
            "args": ["-y", "octagon-mcp"],
        }
    }
})

应用自有的 HTTP MCP 服务也可以直接使用：

await agent.use_mcp(
    "https://example.com/mcp",
    headers={"Authorization": "Bearer ..."},
)

业务价值：外部工具、本地命令和 MCP 服务都成为可观测、受策略控制的运行时能力。 高风险本地执行需要显式审批或 auto_allow=True；缺失的安全纯计算能力可以合成为 sandboxed Python action；业务系统能力如果没有真实 Action 或 connector，则会 fail closed。

Effort-aware Skills Planning

Skills 执行现在支持运行时 effort 等级和自定义 effort strategy handler。

execution = await agent.async_run_skills_task(
    "Prepare release readiness evidence and decide go/no-go.",
    skills=["release-readiness-reviewer"],
    mode="required",
    effort="normal",
    output={
        "decision": (str, "go / no-go", True),
        "blocking_risks": ([str], "release blocking risks", True),
        "required_followups": ([str], "follow-up actions", True),
    },
)

Effort 语义：

团队也可以注册自己的策略：

Agently.skills_executor.register_effort_strategy("audit_plus", handler)

execution = await agent.async_run_skills_task(
    "Run a regulated readiness review.",
    effort="audit_plus",
)

业务价值：团队可以显式权衡延迟、成本和可靠性。同一个 Skill 可以用于日常快速任务、 重要业务决策，或组织自定义的高保证流程。

Dynamic Task 和 TriggerFlow 成为执行骨架

复杂的模型生成 DAG 或应用提交 DAG 仍然由 Dynamic Task 承载。4.1.3 让 Agent execution 可以路由到 Dynamic Task，并把结构化字段增量保留在稳定路径下。

execution = (
    agent
    .use_dynamic_task(mode="auto", max_tasks=8)
    .input("Research this company and produce an investment memo.")
    .output({
        "thesis": (str, "investment thesis", True),
        "risks": ([str], "major risks", True),
        "evidence": ([str], "supporting evidence", True),
    })
    .create_execution()
)

async for item in execution.get_async_generator(type="instant"):
    if item.delta:
        print(item.path, item.delta)

业务价值：复杂任务可以在同一运行时中分解、流式展示、检查和恢复，而不是塞进一次 prompt，或重写成另一套工作流引擎。

max_tasks 是规划护栏，不是“让模型无限长时执行直到自认为质量达标”的开关。 不设置 max_tasks 时，Agently 不额外施加任务数量上限（除非 planner settings 里有 配置）；planner 仍然生成有限 DAG，校验和重试限制仍然生效，执行会在该 DAG 完成或 失败时结束。

Model Pool 和阶段路由

Agently 4.1.3 支持三层模型解析：

业务 model key
  -> model_pool 里的具体 model name
  -> key_pool_strategy 里的 key id
  -> key_pool 里的 API key

这把 ollama-qwen2.5、deepseek-v4 这类模型别名和具体 provider model name、 API key 解耦。

agent.set_settings("model_pool", {
    "ollama-qwen2.5": "qwen2.5:7b",
    "deepseek-v4": "deepseek-chat",
})
agent.set_settings("key_pool", {
    "local": "ollama",
    "deepseek-main": "${ENV.DEEPSEEK_API_KEY}",
    "deepseek-backup": "${ENV.DEEPSEEK_BACKUP_API_KEY}",
})
agent.set_settings("key_pool_strategy", {
    "qwen2.5:7b": {"mode": "fixed", "pool": ["local"]},
    "deepseek-chat": {"mode": "round_robin", "pool": ["deepseek-main", "deepseek-backup"]},
})

普通 Agent turn 可以用 activate_model(...) 切换当前模型：

result = (
    agent
    .activate_model("ollama-qwen2.5")
    .input("Summarize this incident.")
    .output({"summary": (str, "incident summary", True)})
    .start()
)

单次调用仍然可以用 create_request(model_key=...) 覆盖当前 Agent 模型：

response = agent.create_request(model_key="deepseek-v4").input("Draft the customer reply.").start()

Skills 规划和执行阶段使用同一层 model key，而不是硬编码 provider model name：

agent.set_settings("skills.runtime.stage_model_keys", {
    "planner": "deepseek-v4",
    "research": "deepseek-v4",
    "executor": "ollama-qwen2.5",
    "verifier": "deepseek-v4",
    "finalizer": "deepseek-v4",
})

API key 切换是在请求时根据 key_pool_strategy 自动选择：fixed、random、 round_robin 或 least_used。4.1.3 不会在 provider 返回鉴权、额度或费用类错误后 自动换另一个 key 重试；这类失败会暴露给应用，由业务系统决定该操作是否适合更换凭据 重试。

业务价值：服务可以把不同阶段路由给便宜、快速或更强的模型，而不需要改业务代码。 规划、调研、执行、校验、反思和最终生成都能使用适合该阶段的模型。

推荐服务类型

4.1.3 特别适合：

核心变化是 Agently 现在提供了一套统一运行时心智：

声明能力
用模型规划
通过已有运行时边界执行
流式展示过程
返回结构化业务结果

兼容性信息