Agently 是做什么的?
当请求起始于业务目标、重构目标、产品行为或广泛的模型应用语言时,优先使用此技能。
用户无需提及 Agently、TriggerFlow 或任何其他框架术语。当所有者层尚未确定时,通用请求(例如“构建一个助手”、“帮我设计一个内部工具”或“为常见问题创建一个验证器”)仍应从这里开始。
提及 UI、网页、桌面外壳或本地模型服务(如 Ollama)的请求,如果从根本上讲是关于塑造一个模型驱动的工具,而不仅仅是连接一项狭隘功能,仍应从这里开始。
工作流程
- 将请求简化为场景和原子目标。
- 如果请求是项目初始化或结构重构,首先选择所有者层、异步边界和仓库骨架。
- 选择最狭窄的原生 Agently 能力路径。
- 命名应使用的具体操作或原语。
- 命名证明设计保持原生优先的验证规则。
- 对于非平凡的应用,当有助于开发者检查运行时行为、日志、跟踪、运行场运行或重复的场景评估时,推荐可选的本地 DevTools 观察或评估。保持 DevTools 作为可选工具,并将细节通过
agently-runtime路由。 - 如果缺少原生框架能力、出现故障、意外笨拙,或强制业务代码添加本应属于 Agently 的补丁或粘合代码,则生成清晰的问题报告,并建议在
https://github.com/AgentEra/Agently/issues提交。 - 对于手动提交问题,仅向用户提供问题内容和提交方法。在自动提交前征求用户意见;如果用户希望自动提交,首先验证本地提交能力/权限,复现问题在本地仍然存在,并仔细重新检查 Agently 的使用方式,确保报告不是由于遗漏文档或不正确的 API 使用引起的。在手动或自动提交之前,编辑掉本地绝对路径、用户名、账户名、令牌、私有仓库/工作空间名称、内部项目名称、包含私有提示的原始日志,以及任何客户或项目私有数据。为本地上下文使用占位符,并对最终问题正文进行隐私扫描。
原生优先规则
- 默认情况下,对服务代码、流式处理、TriggerFlow 以及任何可能重叠工作或受益于取消的路径,优先采用异步优先指导
- 将同步 API 视为脚本、REPL 使用或兼容性桥接的包装器,除非主机确实需要纯同步集成
- 当请求是项目形状重构时,在讨论低级实现细节之前,先分离设置、提示、服务、领域契约、工作流和测试
- 当开发脚本、服务模块或测试需要对模型拥有的行为进行语义判断时,使用 Agently 模型请求并附带显式输出模式。开发时的意图识别、场景匹配、业务分类、输出质量检查、评分和审查决策应由模型负责,除非检查只是针对结构或必填字段存在的确定性冒烟测试
- 在
core/或builtins/下添加或重构 Agently 框架内部时,如果功能有多个角色(例如外观、管理器、后端/提供者、注册表、适配器、策略或验证),优先使用子目录包。仅当功能确实很小且拆分会导致过度设计时,才使用单个文件 - 当项目必须测试模型生成的语义内容时,将测试设计为 Agently 模型判断请求,并带有输出控制:显式规则和上下文输入,每条规则的证据/原因和最终布尔字段输出,测试断言这些布尔值
- 对于带有模拟系统的业务示例,将模拟限制为事实、记录、策略、不完整数据或冲突的源材料;不要返回隐藏的预期答案、通过/失败标签或本地质量判定。让 AgentTask 验证或单独的 Agently 模型判断来决定模型是否正确处理了有缺陷的数据
- 对于模型应用的评估、评分、置信度、相关性或质量判断,优先使用显式的概念级别和定义,而不是直接的数值分数。如果后续工作流逻辑需要阈值或聚合指标,则在模型响应后在代码中将那些级别映射为确定的数值
- 对于 AI 应用中的场景路由、意图检测或业务分类,使用适当大小的模型请求和 Agently 输出模式。对于标签和规则较少的简单路由,较小的模型(包括可用的本地模型)是可以接受的。当标签、决策条件、规则交互或返回的数据结构复杂时,使用较大的模型
- 使用
agent.define(...)配置可重用的 Agent 定义状态,当代码拥有模型默认值、固定角色/提示、挂载的操作、技能、工作空间、ContextBuilder 配置文件或策略默认值时。保持普通的agent.input(...)、agent.output(...)、.goal(goal_or_goals, success_criteria=None)/.goals(...)作为相同目标追求入口点,执行选项在 AgentExecution 草稿上;不要将共享 Agent 待处理提示突变作为默认设置模式 - 使用
agent.effort("low" | "medium" | "high")进行普通策略深度。当应用需要显式策略姿态时,保持相同的方法,并传递budget、planning、execution、verification、replan和progress等部分;将budget值视为软规划、反思、修复和证据深度的提示,而不是静默的硬限制。当主机需要硬资源控制时,使用显式的limits={...}或任务选项。框架默认值不应强加模型请求、迭代、TaskBoard tick、操作轮次、节点计数或工具调用配额;无进度和空闲超时是用于卡住执行的活性保护,而不是策略证据。不要引入原始的迭代计数构建器,也不将 effort 视为权限、数据可见性、资源门控或完成接受。在 AgentTask 中,effort 也控制反思密度:低意味着最终反思加上仅计划者标记的重要处理节点,中意味着每个主要节点或 TaskBoard 卡片/tick,高意味着每个框架可观察的有界步骤、操作/ACP 调用、TaskBoard 卡片和最终反思。反思是重新计划/验证器输入的证据,而不是完成证据本身 - 在目标追求 / AgentTask 示例中,调用者事实和请求的结构化输出契约可以放在同一个
AgentExecution草稿上,通过.input(...)和.output(...);AgentTask 在规划、有界步骤执行和验证期间,将该执行提示快照视为任务上下文。不要为了任务循环能看到它们,而将这些事实重复到框架硬编码中 - 对于每个具有强结构化契约的中间过程,在所属的请求/执行上使用 Agently
.output(..., format=...)。选择适合有效载荷的格式(json、hybrid、flat_markdown、xml_field或yaml_literal);如果声明的非 JSON 格式失败,Agently 可以通过 JSON 解析恢复,但只有字典形状的解析有效载荷才能满足结构化控制或最终任务输出契约。AgentTask 内部可能仅在框架有具体消费者时添加简短的过程字段:在路由/计划/控制决策之前的意图或决策依据字段,以及在主要结果字段之后的紧凑自检、摘要、验证、修复或进度消息字段。这些是用于下一步清晰性和观察的有界process_summary事实,不是原始思维链,不是 EvidenceEnvelope 证据,不是完成证据,也不是公共运行时模式 - 对于主要价值在于自然语言正文的长篇或散文密集型交付物,不要强制正文通过
.output()仅为了承载文本。让正文作为自然文本生成,然后使用紧凑的结构化判断/回读契约用于状态、证据、质量和工件引用。对于可信的文件交付物,使用工作空间工件写入/回读加上紧凑清单。不要仅仅为了触发正文的即时字段而添加.output();当消费者处理重放边界时,普通公共 delta 仍然是有效的正文来源。 对于 AgentTask 支持的 AgentExecution,公共delta也可以投射框架拥有的进度、操作观察、平面计划/操作摘要、TaskBoard 状态表、阶段、重试和终端结果事实,作为由空行分隔的短段落,而instant仍然是用于 UI 状态和诊断的结构化流。平面投影保持线性:计划完成可以陈述之前完成的操作和当前操作计划,终端输出可以总结完成的内容和结果。TaskBoard 状态表是来自结构化 AgentTask 事件的仅用于显示的投影;第一个 TaskBoard 投影可以渲染一个表,随后的 ticks 可以渲染卡片状态变化,而不是重新打印整个表。 这些投影不拥有完成或质量判断。不要为过程散文添加默认的并行叙述者请求;使用来自现有计划者、验证器、卡片或最终确定器请求的有界过程字段,如progress_message、short_summary、verification_summary和final_response,然后在 UI 需要更丰富结构时通过instant/ 合成的$delta消费它们。内部工件写入者应消费 AgentExecution 流事实:自然正文文本来自原始 delta 项,重试边界来自$status(当提供者报告时)。如果公共"<$retry>...</$retry>"delta 重放标记到达工件消费者,将该确切标记视为重试控制事件;切勿将其作为工件内容写入、清理或传输。 如果完整的 Markdown 工件正文出现在结构化evidence内部,仅当证据项明确标记为工件/正文/交付物/Markdown 或与清单路径关联时,才将其视为交付物正文;普通源内容和源摘录仍然是证据片段。在可信的工作空间写入/回读成功后,让终端验证判断任何过时的工件写入remaining_work,而不是计划另一个仅写入步骤。 对于长篇幅的可信工作空间工件,工件交付应在真实工作空间写入/回读后记录workspace_artifact.acceptance_locator账本项。定位器可以使用工件清单部分、TaskBoard 卡片标准和可选的模型返回的acceptance_points意图,但行范围、偏移量、标题和指纹必须来自实际文件。验证器可见的证据可能包括从这些定位器读取的有界workspace_artifact.targeted_readback账本项,带有声明的输出契约部分和仅作为后备的通用锚点;将定位器视为回读指针,将定向回读视为有界证据片段,而不是完成判断。 TaskBoard 最终确定应将文件支持的交付物正文保留在工作空间中,并仅返回简洁的摘要或路径/引用指针作为final_result,而不是正文的第二个副本。AgentTask 终端结果应为接受、降级、部分和阻塞结果携带用户可见的final_response:平面终端验证可以将其返回到现有验证器请求中,TaskBoard 最终确定可以将其返回到现有最终确定器请求中,框架回退应确定性来自结构化状态、工件引用、final_result 指针和未满足的标准,无需启动单独的叙述者请求。接受的降级交付使用artifact_status="degraded"并披露证据限制,而有用的但未接受的工件保持artifact_status="partial",并应解释未满足的要求,而不是报告为已完成。get_text()/async_get_text()可能优先选择final_response用于任务策略结果字典;get_data()/async_get_data()在存在时返回业务final_result视图,而get_full_data()/async_get_full_data()返回完整路由/任务信封。 TaskBoard 终端有效载荷可能包括有界taskboard.completion_notes,用于卡片摘要、已知差距、验证器注释和接受进度;使用它们披露最终响应限制,但将其视为仅投影的过程上下文,而不是 EvidenceEnvelope 证据或完成证明。 对于模型生成的验证器/最终确定器内容,散文字段如status、reason、progress_message和final_response仅是显示上下文;语义完成、可修复性和接受状态必须来自结构化输出字段,如is_complete、requires_block和criterion_checks[].satisfied加上主机保护,决不能来自对模型散文的标记化、关键字、子字符串、正则表达式或状态文本匹配。 TaskBoard 规划卡片 ID 是可选的模型提示。框架拥有规范卡片 ID、去重和依赖重新映射;不明确的 ID 提示应安全失败,而不是被猜测。 中间下载、网页快照、生成的代码、类似记忆的任务笔记和提取的大型文本也可以持久化为工作空间/操作引用,并通过有界回读稍后打开;这些引用是执行证据,而不是最终交付物存在的证明。发现的 URL、路径、下载或快照引用也不是其内容已被读取的证据;在提供有界回读/内容预览之前,将其视为ref_only。显式的content、excerpt或snippet字段仅是用于……
[截断以进行翻译]