agently-request

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agently Request

Use this Skill when the work can be owned by one ModelRequest family. Use

agently-triggerflow

when a later semantic step needs a tool result, system lookup, approval, artifact readback, or host computation produced after the first request, or when branching, concurrency, retry, or pause/resume must stay visible in the application lifecycle.

For multi-round Prompt collaboration, start each substantive round with current items (status first) and a timestamped, versioned change-log table. Use Multi-Round Collaboration to preserve pending decisions, modifications and abandonment.

当某项工作可由一个 ModelRequest 族负责时，使用此 Skill。若后续语义步骤需要工具结果、系统查询、审批、artifact 回读、首次请求后产生的 Host 计算结果，或者分支、并发、重试、暂停/恢复过程需要在应用生命周期中保持可见，则使用

agently-triggerflow

。

对于多轮 Prompt 协作，每个实质性轮次都应以当前条目（状态优先）以及带时间戳和版本号的变更日志表开始。使用多轮协作保留待定决策、修改和放弃事项。

Read by Need

按需阅读

Independent model roles, image modes/direct output, audio task input, say or embed: model-capabilities.md; development API, check installed support.
Independent TTS/STT, Agent audio binding, continuous audio bytes, or output blocks: audio.md. AudioModelRequest is a separate plugin capability, not the text Prompt pipeline.
Provider, endpoint, environment, settings namespace, or connectivity: model-setup.md.
Request responsibility, effect tuning, input/output sufficiency or redundancy, collaborative review, Prompt config/references, reusable contracts or inheritance: prompt-management.md.
Structured output, Pydantic, ensure/validation, streaming formats, or direct long-output delivery: output-control.md.
Reusing one request result as text/data/meta or consuming its streams: model-request-result.md.
Session continuity and durable memory: session-memory.md.
Embeddings, rerank models, RecordStore, ContextSource, retrieval, and grounded citations: knowledge-base.md.
Cross-source progressive disclosure and real-world Skills: context-and-skills.md.

独立模型角色、图像模式/直接输出、音频任务输入、say 或 embed： model-capabilities.md；开发 API，并检查当前安装是否支持。
独立 TTS/STT、Agent 音频绑定、连续音频字节或输出块： audio.md。AudioModelRequest 是一项独立的插件能力，不属于文本 Prompt 流水线。
Provider、endpoint、环境、设置命名空间或连通性： model-setup.md。
请求职责、效果调优、输入/输出的充分性或冗余、协作评审、Prompt 配置/引用、可复用契约或继承机制： prompt-management.md。
结构化输出、Pydantic、ensure/验证、流式格式或直接交付长输出： output-control.md。
将单个请求结果作为文本/数据/元数据复用，或消费其流： model-request-result.md。
会话连续性和持久记忆： session-memory.md。
Embeddings、rerank 模型、RecordStore、ContextSource、检索和有事实依据的引用： knowledge-base.md。
跨来源渐进式披露和实际场景中的 Skills： context-and-skills.md。

Request Contract

请求契约

Use collaborative review when request contracts can clarify model duties, improve execution effects, or reveal missing/redundant data; an explicit "Prompt review" request is unnecessary. Start complex reviews with a flow overview highlighting model nodes and Host handoffs, then group related Prompt tables for comparison. Up to three logical nodes may share a reply; tightly coupled larger groups are allowed. Prioritize developer understanding, not fixed counts or one-node approval turns. Preserve confirmation of consequential changes and distinguish design findings from measured effects. See
```
references/prompt-management.md
```
; use
```
agently-design
```
for cross-node flow/ownership analysis, not for unrelated mechanical work.
After measured schema/ensure/length failures, consider a shallower model-facing projection or coherent request splits with Host reconstruction and unchanged final validation. See
```
references/output-control.md
```
.
Keep a one-off fluent request readable as one chain:
```
.input(...)
```
,
```
.info(...)
```
,
```
.instruct(...)
```
,
```
.output(...)
```
, then its result call. Split only for actual reuse, independently owned configuration, or dynamic composition.
Do not promote literals or behavior from a single observed instance into normative prompt instructions. Derive a general invariant and test contrasting cases; use illustrative examples only to explain an already stated rule, and keep their total rendered content smaller than the non-example normative prompt.
Put runtime facts in
```
input
```
, authoritative evidence/API/schema material in
```
info
```
, behavior and transformation rules in
```
instruct
```
, and the exact downstream-consumed shape in
```
output
```
.
Define each consumed field's type, meaning, requiredness, enum/format/range, nullability, and cross-field constraints where applicable.
Give the model every non-sensitive satisfiable validator rule before the first attempt. Deterministic validation remains authoritative; retry feedback repairs a declared contract and must not become blind rule discovery.
Use ModelRequest structured output for prose-derived intent, routing, relevance, grading, and acceptance. Host code owns schema/type checks, authorization, arithmetic, offered-key membership, and side effects.
Combine semantic fields in one ordered response only when they share the same request-time evidence snapshot and later fields need no post-dispatch fact. Streaming cannot inject a tool or host result into an in-flight request.
Validate schema, offered keys, authorization, and deterministic constraints before a real call or side effect.

For VLM requests, prefer

.image(question=..., file=...|url=...|files=[...]|urls=[...])

(the model-capabilities development API also accepts a positional file, optional question and mode, and appends repeated groups). Use

.attachment(...)

only when the caller owns provider-style mixed content or exact content ordering.

当请求契约可以澄清模型职责、改善执行效果或暴露缺失/冗余数据时，使用协作评审；无须显式提出“Prompt review”请求。复杂评审应先从流程概览开始，突出模型节点与 Host 交接，然后对相关 Prompt 表进行分组比较。最多可让三个逻辑节点共享一次回复；对于紧密耦合的情况，也允许更大的分组。应优先确保开发者能够理解，而不是遵循固定数量或单节点审批轮次。对于影响重大的变更，保留确认环节，并将设计发现与实测效果区分开来。参见
```
references/prompt-management.md
```
；跨节点流/所有权分析应使用
```
agently-design
```
，不要将其用于无关的机械性工作。
在实测发现 schema/ensure/length 失败后，应考虑使用更浅的模型侧投影，或进行内聚的请求拆分并由 Host 重建，同时保持最终验证不变。参见
```
references/output-control.md
```
。
保持一次性且流畅的请求以单条链的形式易于阅读：
```
.input(...)
```
、
```
.info(...)
```
、
```
.instruct(...)
```
、
```
.output(...)
```
，随后调用其结果。仅在实际复用、配置具有独立归属或需要动态组合时拆分。
不要将单个观察实例中的字面量或行为提升为规范性 Prompt 指令。应推导出通用不变量并使用对照案例进行测试；示例仅用于解释已经陈述的规则，且全部示例渲染后的内容总量应小于不含示例的规范性 Prompt。
将运行时事实放入
```
input
```
，将权威证据/API/schema 资料放入
```
info
```
，将行为和转换规则放入
```
instruct
```
，并将下游消费所需的确切结构放入
```
output
```
。
为每个被消费的字段定义类型、含义、必填性、枚举/格式/范围、可空性，并在适用时定义跨字段约束。
在首次尝试前，向模型提供所有非敏感且可满足的验证器规则。确定性验证仍具有权威性；重试反馈用于修复已声明的契约，不得演变为盲目的规则发现过程。
对于从自然语言推导的意图、路由、相关性、评分和验收，使用 ModelRequest 结构化输出。schema/类型检查、授权、算术运算、候选键成员校验和副作用均由 Host 代码负责。
只有当语义字段共享同一请求时证据快照，且后续字段不依赖派发后产生的事实时，才应将它们合并到一个有序响应中。流式处理无法将工具或 Host 结果注入正在进行的请求。
在执行真实调用或产生副作用前，验证 schema、候选键、授权和确定性约束。

对于 VLM 请求，优先使用

.image(question=..., file=...|url=...|files=[...]|urls=[...])

（model-capabilities 中的开发 API 还接受作为位置参数的文件、可选的 question 和 mode，并支持重复分组）。仅当调用方负责 provider 风格的混合内容或精确的内容顺序时，才使用

.attachment(...)

。

Results, Context, and Memory

结果、上下文和记忆

In 4.1.4.8,
```
.auto_continue()
```
is a conditional output-delivery setting;
```
.ensure_long_output()
```
remains its compatibility alias. Neither selects an Execution mode.
```
LongContent
```
declarations select proactive long-form production. Read output-control.md for plain-text and structured-string support, completion evidence and limits.
Direct ModelRequest calls return
```
ModelRequestResult
```
; Agent quick chains return
```
AgentExecutionResult
```
. Reuse the same result facade for text, parsed data, metadata, and streams instead of issuing the request again.
When no consumer needs progress, await the final getter directly. Treat
```
instant
```
fields as provisional UI or cancelable/idempotent preparation and reconcile them against the final validated result.
Session memory is not workflow state.
```
SessionMemory
```
owns extraction and compression policy;
```
RecordStore
```
owns durable records and retrieval; TriggerFlow execution state owns workflow progression.
Keep raw retrieval records cold. Give the model bounded task-relevant facts and one host-issued key per candidate, then validate and reconstruct canonical identities in host code.
For retrieval-backed answers, offer trusted
```
ref_id
```
values, require
```
[[ref:<ref_id>]]
```
, and resolve approved source cards/links host-side.

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

Avoid

避免

Handwritten provider HTTP, prompt templating, JSON repair, or retry loops before checking Agently settings and output contracts.
Moving a one-use schema or prompt step away from its request chain only to shorten the visible code.
Re-requesting the model separately for text, data, and metadata.
Treating retrieval hits, memory records, provisional stream fields, or model prose as deterministic proof of authorization or side effects.
Turning entity literals, one-time input or environment state, a historical incident, test fixture, or expected answer from one observed instance into a prompt branch, or letting illustrative examples create behavior that the normative contract never states.

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