agently-request

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.

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.

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.

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.