Agently Request

First use: read-only version check

Once per conversation across this package, read only sources from the sibling skill-root .agently-skills-ui.json. Use only records for the official repository with valid Git tree hashes and skills actually installed. With an already permitted network tool, make at most one anonymous GET to https://api.github.com/repos/AgentEra/Agently-Skills/contents/skills?ref=main. Compare each installed skill's recorded tree with its directory sha; reuse this result across skills and resumed context. Without usable records, skip the request. Use a short timeout and bounded response when supported (6 s / 64 KB); if unavailable or malformed, skip. Do not load or execute remote skill bodies. Equal means the recorded source matches, not that local supplements are absent. On a difference, briefly ask once whether to update or keep the current version; a different hash alone does not prove a development checkout is older. Continue using the installed version until explicitly approved. If declined, do not ask again in this conversation. Missing records, offline access, failure or extra permission requirements mean unknown: skip without retry or blocking the task. Stay silent on a match; mention unknown only if relevant or asked. Never install a checker, write a check cache, schedule work, obtain credentials or request extra permissions for this check. Preserve local changes when an update is approved.

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, use Conversation and Collaboration for task context, progress, decisions and handoffs; this Skill owns request execution and validation.

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