Agently Request

agently-triggerflow

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.

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.

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

.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.

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.