agently-request

Agently 请求

如果工作可由一个 ModelRequest 系列负责，请使用此 Skill。如果后续语义步骤需要使用首次请求之后生成的工具结果、系统查询、审批、制品回读或宿主计算，或者需要在应用生命周期中清晰呈现分支、并发、重试或暂停／恢复，请使用 agently-triggerflow。

对于多轮 Prompt 协作，每个实质性轮次都应先列出当前事项（状态置前），再提供带时间戳和版本号的变更日志表。使用 多轮协作 来保留待定决策、修改和放弃事项。

按需阅读

• 独立模型角色、图像模式／直接输出、音频任务输入、say 或嵌入： model-capabilities.md；开发 API，检查已安装的支持情况。
• 独立 TTS／STT、Agent 音频绑定、连续音频字节或输出块： audio.md。AudioModelRequest 是独立的插件能力，不属于文本 Prompt 流程。
• 提供商、端点、环境、设置命名空间或连接性： model-setup.md。
• 请求职责、效果调优、输入／输出充分性或冗余、协作审查、Prompt 配置／引用、可复用契约或继承： prompt-management.md。
• 结构化输出、Pydantic、ensure／验证、流式格式或长输出的直接交付： output-control.md。
• 将同一请求结果复用为文本／数据／元信息，或使用其流： model-request-result.md。
• 会话连续性和持久化记忆： session-memory.md。
• 嵌入、重排模型、RecordStore、ContextSource、检索和有依据的引用： knowledge-base.md。
• 跨来源渐进式披露和真实世界中的 Skills： context-and-skills.md。

请求契约

• 当请求契约有助于明确模型职责、改善执行效果，或发现缺失／冗余数据时，应采用协作式审查；无需显式提出“提示词审查”请求。复杂审查应先概述流程，突出模型节点和 Host 交接，再按主题对提示词表格分组比较。最多三个逻辑节点可共用一条回复；紧密耦合的更大分组也可以。优先考虑开发者的理解，而非固定数量或逐节点审批。保留对重大变更的确认，并区分设计发现与实测效果。参见 references/prompt-management.md；跨节点流程／所有权分析应使用 agently-design，不要用于无关的机械性工作。
• 在实测到 schema／确保／长度错误后，可考虑采用更浅层、面向模型的投影，或合理拆分请求并由 Host 重建，同时保持最终验证不变。参见 references/output-control.md。
• 一次性流式请求应保持为一个易读的链：.input(...)、.info(...)、.instruct(...)、.output(...)，然后调用其结果。只有在确有复用、配置由不同主体独立管理，或需要动态组合时才拆分。
• 不要将单个观测实例中的字面内容或行为提升为规范性提示词指令。应推导出一般不变量并测试对照案例；示例仅用于解释已陈述的规则，且示例渲染后的总内容应少于规范性提示词中的非示例内容。
• 将运行时事实放在 input 中，将权威证据／API／schema 材料放在 info 中，将行为和转换规则放在 instruct 中，并在 output 中定义下游实际消费的准确结构。
• 对每个被消费的字段，在适用时定义其类型、含义、是否必需、枚举／格式／范围、是否可为 null，以及跨字段约束。
• 首次尝试前，向模型提供所有非敏感且可满足的验证规则。确定性验证仍具有权威性；重试反馈用于修复已声明的契约，不应变成盲目发现规则的手段。
• 对从文本得出的意图、路由、相关性、评分和验收，使用 ModelRequest 结构化输出。Host 代码负责 schema／类型检查、授权、算术运算、所提供键的成员关系以及副作用。
• 只有当语义字段共享同一请求时证据快照，且后续字段不需要分发后事实时，才将其合并为一个有序响应。流式传输无法将工具或 Host 结果注入正在进行的请求。
• 在进行真实调用或产生副作用之前，验证 schema、所提供的键、授权和确定性约束。

对于 VLM 请求，优先使用 .image(question=..., file=...|url=...|files=[...]|urls=[...]) （模型能力开发 API 也接受位置参数形式的文件、可选的问题和模式，并会追加重复的组）。仅当调用方负责提供程序风格的混合内容或精确内容顺序时，才使用 .attachment(...)。

结果、上下文与记忆

• 在 4.1.4.8 中，.auto_continue() 是一种有条件的输出交付设置； .ensure_long_output() 仍是其兼容性别名。两者都不会选择执行模式。LongContent 声明用于选择主动生成长篇内容。有关纯文本和结构化字符串支持、完成证据及限制，请参阅 output-control.md。
• 直接调用 ModelRequest 会返回 ModelRequestResult；Agent 快速链会返回 AgentExecutionResult。复用同一个结果门面获取文本、解析后的数据、元数据和流，而不是再次发起请求。
• 如果没有使用者需要进度信息，直接等待最终 getter。将 instant 字段视为临时 UI 内容或可取消、幂等的准备结果，并根据最终验证结果进行校准。
• 会话记忆不等于工作流状态。SessionMemory 负责抽取和压缩策略；RecordStore 负责持久化记录和检索；TriggerFlow 执行状态负责工作流推进。
• 保持原始检索记录处于冷数据状态。提供给模型有界且与任务相关的事实，并为每个候选项提供一个由主机签发的键，然后在主机代码中验证并重建规范身份。
• 对于基于检索的回答，提供可信的 ref_id 值，要求使用 [[ref:<ref_id>]]，并在主机端解析已批准的来源卡片／链接。

避免

• 在检查 Agently 设置和输出契约之前，手写提供方 HTTP、提示词模板、JSON 修复或重试循环。
• 只为缩短可见代码，就将仅使用一次的架构或提示词步骤移出其请求链。
• 分别为文本、数据和元数据再次请求模型。
• 将检索命中、记忆记录、临时流字段或模型生成的文本视为授权或副作用的确定性证明。
• 将实体字面值、一次性输入或环境状态、历史事件、测试夹具，或单个观测实例中的预期答案转化为提示词分支；也不要让说明性示例产生规范契约中从未规定的行为。