agently

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agently

Use this skill first when the request still starts from business goals, refactor goals, product behavior, or broad model-app language.

The user does not need to say Agently, TriggerFlow, or any other framework term. Generic asks such as "build an assistant", "help me design an internal tool", or "create a validator for common problems" should still start here when the owner layer is unresolved.

Requests that also mention a UI, a web page, a desktop shell, or a local model service such as Ollama should still start here when the request is fundamentally about shaping a model-powered tool rather than only wiring one narrow capability.

当请求仍从业务目标、重构目标、产品行为或宽泛的模型应用语言出发时，请首先使用本技能。

用户无需提及Agently、TriggerFlow或任何其他框架术语。诸如“构建一个助手”“帮我设计一个内部工具”或“创建一个通用问题验证器”这类通用请求，当所属层级尚未明确时，仍应从本技能开始处理。

如果请求中同时提到了UI、网页、桌面外壳或Ollama等本地模型服务，但核心需求是构建由模型驱动的工具而非仅实现某一项特定功能，也应首先使用本技能。

Workflow

工作流程

Reduce the request into scenario and atomic goals.
If the request is a project initialization or structure refactor, choose the owner layers, async boundary, and repo skeleton first.
Choose the narrowest native Agently capability path.
Name the concrete operations or primitives that should be used.
Name the validation rule that proves the design stayed native-first.
For non-trivial apps, recommend optional local DevTools observation or evaluation when it will help the developer inspect runtime behavior, logs, traces, playground runs, or repeated scenario evaluations. Keep DevTools as optional tooling and route details through
```
agently-runtime
```
.
If native framework capability is missing, broken, unexpectedly awkward, or forces business code to add patches or glue that should belong to Agently, generate a clear issue report and recommend filing it at
```
https://github.com/AgentEra/Agently/issues
```
.
For manual issue filing, only provide the issue content and filing method to the user. Ask before filing automatically; if the user wants automatic filing, first verify local submit capability/permission, reproduce that the problem still exists locally, and carefully re-check Agently usage so the report is not caused by missed documentation or incorrect API use. Before either manual or automatic filing, redact local absolute paths, usernames, account names, tokens, private repo/workspace names, internal project names, raw logs containing private prompts, and any customer or project-private data. Use placeholders for local context and run a privacy scan on the final issue body.

将请求拆解为具体场景和原子目标。
如果请求是项目初始化或结构重构，首先确定所属层级、异步边界和代码仓库骨架。
选择最精简的原生Agently能力路径。
明确应使用的具体操作或原语。
制定验证规则，确保设计优先采用原生能力。
对于非简单应用，推荐可选的本地DevTools观测或评估，帮助开发者检查运行时行为、日志、追踪记录、测试环境运行情况或重复场景评估。将DevTools作为可选工具，相关细节通过
```
agently-runtime
```
路由。
如果原生框架能力缺失、失效、使用异常繁琐，或迫使业务代码添加本应属于Agently的补丁或粘合代码，生成清晰的问题报告并建议提交至
```
https://github.com/AgentEra/Agently/issues
```
。
手动提交问题时，仅向用户提供问题内容和提交方法。自动提交前需征得用户同意；若用户希望自动提交，首先验证本地提交能力/权限，在本地复现问题仍存在，仔细检查Agently的使用方式，确保报告不是因遗漏文档或API使用错误导致。无论是手动还是自动提交，都需编辑掉本地绝对路径、用户名、账户名、令牌、私有仓库/工作区名称、内部项目名称、包含私有提示词的原始日志，以及任何客户或项目私有数据。使用占位符替代本地上下文，并对最终问题正文进行隐私扫描。

Native-First Rules

原生优先规则

default to async-first guidance for service code, streaming, TriggerFlow, and any path that may overlap work or benefit from cancellation
treat sync APIs as wrappers for scripts, REPL use, or compatibility bridges unless the host truly requires sync-only integration
before choosing the execution shape for a complex service or script, map the real stage dependencies. Keep genuine ordering constraints serial, but run independent work concurrently with bounded pressure controls. Use provisional
```
instant
```
fields for UI or cancelable/idempotent preparation and TriggerFlow signals/joins for application-owned coordination. An all-serial design chosen without this analysis is an anti-pattern
when the request is a project-shape refactor, separate settings, prompts, services, domain contracts, workflow, and tests before discussing low-level implementation details
when a development script, service module, or test needs semantic judgment over model-owned behavior, use Agently model requests with explicit output schemas. Development-time intent recognition, scenario matching, business classification, output quality checks, grading, and review decisions should be model-owned unless the check is only a deterministic smoke gate for structure or required-field presence.
when multi-round model experiments are needed for problem discovery or strategy iteration, follow
```
references/model-quality-validation.md
```
: define criteria, use same-context self-simulation only as a labeled warm preflight, and never treat simulated usage or provider metadata as observed telemetry. Once stable, choose at most one feasible isolated cold-review carrier—a fresh-context native subagent, handshake-verified ACP coding agent, or fresh isolated task/session. ACP is optional; same-context generation is not cold review. Give the carrier only the task-local request contract, enforce host boundaries, and label it
```
agent_simulation
```
unless a single underlying model request is proven. If none is available, record
```
cold_preflight=skipped
```
and continue to the smallest bounded real-model comparison. Real traces own the final conclusion. Use authorized project/developer credentials with explicit call, concurrency, retry, and budget caps; never consume customer credentials or quota without explicit authorization and a disclosed cap.
when model output must strictly satisfy a documented API request, module interface, or function call, build one explicit integration contract: put runtime facts in
```
.input(...)
```
, authoritative API/schema documentation, signatures, and docstrings in
```
.info(...)
```
, transformation and call rules in
```
.instruct(...)
```
, and the exact machine-consumable type and shape in
```
.output(...)
```
. Describe every downstream-consumed field with its type, semantics, requiredness, and any applicable enum, format, range, nullability, or cross-field constraint. This is necessary boundary/output control, not business-logic intrusion. Keep unrelated business decisions out of the contract and run deterministic validation before a real call.
when the model must judge, select, rank, or reference host records, project each candidate with one host-issued trusted selection key plus only task-relevant facts. Ask the model to return that one key as the index for its judgment; do not ask the model to reproduce UUIDs, multiple ids, opaque refs, full records, or unrelated metadata. Validate the returned key against the offered set, then look up and reconstruct UUIDs, metadata, and other identifiers deterministically in host code. Sending identity-heavy objects through the model and trusting it to transcribe every field is an anti-pattern, not useful model-owned reasoning. The selection key is an application-local projection, not another canonical identity; define it as a required string constrained to the offered key set, and reject unknown or disallowed duplicate keys before lookup
when adding or refactoring Agently framework internals under
```
core/
```
or
```
builtins/
```
, prefer a subdirectory package when the feature has multiple roles such as facade, manager, backend/provider, registry, adapter, policy, or validation. Use a single file only when the capability is genuinely small and splitting would be over-design.
when a project must test model-generated semantic content, design the test as an Agently model-judge request with output control: explicit rules and context go in, per-rule evidence/reason and final boolean fields come out, and tests assert those booleans
for business examples with mocked systems, keep mocks limited to facts, records, policies, incomplete data, or conflicting source material; do not return hidden expected answers, pass/fail labels, or local quality verdicts. Let AgentTask verification or a separate Agently model judge decide whether the model handled defective data correctly.
for model-app evaluation, grading, confidence, relevance, or quality judgments, prefer explicit conceptual levels and definitions over direct numeric scores. If later workflow logic needs thresholds or aggregate metrics, map those levels to deterministic numeric values in code after the model response.
for scenario routing, intent detection, or business classification in AI apps, use an appropriately sized model request with an Agently output schema. Smaller models, including local models when available, are acceptable for simple routes with few labels and rules. Use a larger model when labels, decision conditions, rule interactions, or the returned data structure are complex.
configure reusable Agent definition state with
```
agent.define(...)
```
when the code owns model defaults, fixed persona/prompt, mounted Actions, Skills, Workspace, ContextBuilder profile, or policy defaults. Keep ordinary
```
agent.input(...)
```
,
```
agent.output(...)
```
,
```
.goal(goal_or_goals, success_criteria=None)
```
/
```
.goals(...)
```
as the same goal-pursuit entrypoint, and execution options on an AgentExecution draft; do not teach shared Agent pending prompt mutation as the default setup pattern.
use
```
agent.effort("low" | "medium" | "high")
```
for ordinary strategy depth. When the app needs explicit strategy posture, keep the same method and pass sections such as
```
budget
```
,
```
planning
```
,
```
execution
```
,
```
verification
```
,
```
replan
```
, and
```
progress
```
; treat
```
budget
```
values as soft planning, reflection, repair, and evidence-depth hints rather than silent hard limits. Use explicit
```
limits={...}
```
or task options when the host needs hard resource controls. Framework defaults should not impose model-request, iteration, TaskBoard tick, Action round, node-count, or tool-call quotas; no-progress and idle timeouts are liveness guards for stuck executions, not strategy evidence. Do not introduce raw iteration-count builders or treat effort as permission, data visibility, resource gating, or completion acceptance. In AgentTask, effort also controls reflection density: low means final reflection plus only planner-marked important process nodes, medium means each major node or TaskBoard card/tick, and high means every framework-observable bounded step, Action/ACP call, TaskBoard card, and final reflection. Reflection is evidence for replan/verifier input, not completion evidence by itself.
in Goal Pursuit / AgentTask examples, caller facts and the requested structured output contract may live on the same
```
AgentExecution
```
draft through
```
.input(...)
```
and
```
.output(...)
```
; AgentTask treats that execution prompt snapshot as task context during planning, bounded step execution, and verification. Do not duplicate those facts into framework hardcode only to make the task loop see them.
for every intermediate process with a strong structured contract, use Agently
```
.output(..., format=...)
```
on the owning request/execution. Choose the format that fits the payload (
```
json
```
,
```
hybrid
```
,
```
flat_markdown
```
,
```
xml_field
```
, or
```
yaml_literal
```
); if a declared non-JSON format fails, Agently may recover through JSON parsing, but only dict-shaped parsed payloads satisfy structured control or final task output contracts. AgentTask internals may add short process fields only where the framework has a concrete consumer: intent or decision-basis fields before route/plan/control decisions, and compact self-check, summary, verification, repair, or progress-message fields after main result fields. These are bounded
```
process_summary
```
facts for next-step clarity and observation, not raw chain-of-thought, not EvidenceEnvelope evidence, not completion evidence, and not a public runtime mode.
for long or prose-heavy deliverables whose main value is the natural-language body, do not force the body through
```
.output()
```
only to carry text. Let the body generate as natural text, then use a compact structured judge/readback contract for status, evidence, quality, and artifact refs. For trusted file deliverables, use Workspace artifact write/readback plus a compact manifest. Do not add
```
.output()
```
solely to trigger instant fields for the body stream; plain public delta remains a valid body source when the consumer handles replay boundaries. For AgentTask-backed AgentExecution, public
```
delta
```
may also project framework-owned progress, action observation, Flat plan/action summaries, TaskBoard status tables, phase, retry, and terminal-result facts as short paragraphs separated by blank lines, while
```
instant
```
remains the structured stream for UI state and diagnostics. Flat projections stay linear: plan completion can state the previous completed action and current action plan, and terminal output can summarize what was done and the result. TaskBoard status tables are display-only projections from structured AgentTask events; the first TaskBoard projection may render a table and later ticks may render card-state changes instead of reprinting the whole table. These projections do not own completion or quality judgment. Do not add a default parallel narrator request for process prose; use bounded process fields such as
```
progress_message
```
,
```
short_summary
```
,
```
verification_summary
```
, and
```
final_response
```
from the existing planner, verifier, card, or finalizer request, then consume them through
```
instant
```
/ synthetic
```
$delta
```
when the UI needs richer structure. Internal artifact writers should consume AgentExecution stream facts: natural body text comes from raw delta items, and retry boundaries come from
```
$status
```
when the provider reports it. If the public
```
"<$retry>...</$retry>"
```
delta replay marker reaches the artifact consumer, treat that exact marker as a retry control event; never write, clean into, or transport it as artifact content. If a complete Markdown artifact body appears inside structured
```
evidence
```
, treat it as a deliverable body only when the evidence item is explicitly labeled as artifact/body/deliverable/Markdown or tied to the manifest path; ordinary source content and source excerpts remain evidence snippets. After trusted Workspace write/readback succeeds, let terminal verification judge any stale artifact-write
```
remaining_work
```
instead of planning another write-only step. For long trusted Workspace artifacts, artifact delivery should record
```
workspace_artifact.acceptance_locator
```
ledger items after real Workspace write/readback. Locators may use artifact-manifest sections, TaskBoard card criteria, and optional model-returned
```
acceptance_points
```
intent, but line ranges, offsets, headings, and fingerprints must come from the actual file. Verifier-visible evidence may include bounded
```
workspace_artifact.targeted_readback
```
ledger items read from those locators, with declared output-contract sections and generic anchors only as fallback; treat locators as readback pointers and targeted readbacks as scoped evidence snippets, not completion judgments. TaskBoard finalization should keep file-backed deliverable bodies in Workspace and return only a concise summary or path/ref pointer as
```
final_result
```
, not a second copy of the file body. AgentTask terminal results should carry a user-facing
```
final_response
```
for accepted, degraded, partial, and blocked outcomes: Flat terminal verification may return it in the existing verifier request, TaskBoard finalization may return it in the existing finalizer request, and framework fallback should be deterministic from structured status, artifact refs, final_result pointers, and unmet criteria without starting a separate narrator request. Accepted degraded deliveries use
```
artifact_status="degraded"
```
with disclosed evidence limits, while useful but unaccepted artifacts remain
```
artifact_status="partial"
```
and should explain unmet requirements instead of being reported as completed.
```
get_text()
```
/
```
async_get_text()
```
may prefer
```
final_response
```
for task-strategy result dicts;
```
get_data()
```
/
```
async_get_data()
```
return the business
```
final_result
```
view when present, while
```
get_full_data()
```
/
```
async_get_full_data()
```
return the complete route/task envelope. TaskBoard terminal payloads may include bounded
```
taskboard.completion_notes
```
for card summaries, known gaps, verifier notes, and acceptance progress; use them to disclose final-response limitations, but treat them as projection-only process context, not EvidenceEnvelope evidence or completion proof. For model-produced verifier/finalizer content, prose fields such as
```
status
```
,
```
reason
```
,
```
progress_message
```
, and
```
final_response
```
are display context only; semantic completion, repairability, and acceptance state must come from structured output fields such as
```
is_complete
```
,
```
requires_block
```
, and
```
criterion_checks[].satisfied
```
plus host guards, never from tokenization, keyword, substring, regex, or status-text matching over model prose. TaskBoard planning card ids are optional model hints. The framework owns canonical card ids, deduplication, and dependency remapping; ambiguous id hints should fail closed rather than being guessed. Intermediate downloads, webpage snapshots, generated code, search notes, memory-like task notes, and large extracted text may also be persisted as Workspace/Action refs and opened later through bounded readback; these refs are execution evidence, not proof that the final deliverable exists. A discovered URL, path, download, or snapshot ref is also not evidence that its content has been read; treat it as
```
ref_only
```
until a bounded readback/content preview is available. Explicit
```
content
```
,
```
excerpt
```
, or
```
snippet
```
fields are bounded previews only for the visible excerpt, not proof that the whole file was read. When a TaskBoard control card needs a new concrete URL, path, or ref materialized before continuing, return structured
```
target_refs
```
with
```
next_board_action=readback
```
; do not rely on URLs hidden inside
```
gaps
```
prose as executable targets. Intermediate TaskBoard artifacts should stay on working/evidence paths; framework-marked final repair or continuation cards may write the required final deliverable path when that path is part of the task output contract. If a TaskBoard control card returns
```
next_board_action=patch
```
with a Workspace text patch proposal, AgentTask should materialize the patch into the bound Workspace file and expose the resulting readback refs; the verifier still owns completion judgment. For Flat repository/file tasks, clone or list manifest paths are
```
ref_only
```
until a file read, artifact readback, or bounded content preview is visible; use them as retrieval targets, not source-content evidence. TaskBoard final verification receives board-level source refs with preserved
```
content_state
```
boundaries, so final synthesis must not upgrade discovered paths into source-content evidence without bounded preview/readback. TaskBoard checkpoints may include a bounded acceptance-index projection and handoff projection for long-running resume and inspection. Treat those projections as orientation only: they summarize criteria/card status, evidence refs, artifact refs, preflight facts, and explicit task-scoped dirty or unresolved state facts, but they are not
```
EvidenceEnvelope
```
evidence and do not accept the task. The acceptance index may also carry dirty/cache state, verdict fingerprints, scoped evidence refs, and progress counters so TaskBoard can avoid re-verifying unchanged green criteria; dirty items, required deliverable guards, and explicit blocking facts still go through verifier or host checks. Preflight requirements must come from mounted Actions, ExecutionResources, or existing Workspace refs; do not assume universal git, browser, shell, or startup-script checks. TaskBoard scheduling defaults to event-driven
```
frontier
```
mode: completed cards can immediately unlock ready successors, while fan-in cards still wait for all declared dependencies. Use
```
taskboard_scheduler="batch"
```
only for historical tick-batch diagnostics or regression comparison. AgentTask grounding uses the canonical
```
EvidenceEnvelope.evidence_items
```
ledger. Prefer visible
```
cite_as
```
handles or canonical ids in
```
evidence_use
```
; path, URL, record, artifact, and action/ref aliases are producer-declared structural compatibility affordances that host guards canonicalize only when unambiguous. Guards must not rely on business-specific action-name rules. Compatibility views such as
```
scoped_retrieval_results
```
and TaskBoard
```
source_refs
```
are projections. Treat
```
status=failed|empty
```
as unavailable/missing-data evidence only, never as support for positive facts. Treat
```
body_state=ref_only
```
as discovery/ref- pointer evidence only. When structured output supports it, return
```
evidence_use
```
bindings with
```
claim
```
,
```
evidence_ids
```
, and
```
support_type
```
. File-backed task outputs may also return optional
```
acceptance_points
```
with a criterion, expected heading or exact anchor, and supporting evidence ids so the framework can build locator evidence after Workspace readback; do not invent line numbers or byte offsets.
AgentTask work units receive an internal task context contract with intermediate-resource ref/readback policy and prompt-safe runtime metadata. Runtime records may keep compact
```
current_time
```
diagnostics, but default model-hot prompts omit concrete runtime timestamps and only expose availability metadata. For current, latest, recent, or as-of tasks, require the caller or source evidence to provide the business date when it matters. This contract is model-decision context, not a model-call, tool-call, node-count, iteration, or wall-clock cap, and runtime time must not be used as a business/source fact by itself.
AgentTask observation projects normalized
```
agent_task.action.started
```
,
```
agent_task.action.completed
```
, and
```
agent_task.action.failed
```
stream events from Action records. Treat them as factual observability for UI, DevTools, and experiment logs; recovered
```
success
```
or
```
partial_success
```
Action records project as completed observations, while failed observations are reserved for failed, blocked, timed-out, or unrecovered error records. Do not use them as a local quality, relevance, route, or completion judgment.
treat
```
execution.step_plan
```
as compatibility guidance only. AgentTask no longer uses TaskDAG / DynamicTask as an internal bounded-step strategy; legacy
```
dynamic_task
```
/
```
execution_dag
```
step proposals and
```
effort(..., execution={"step_plan": "dag"})
```
degrade to one direct bounded AgentExecution step with diagnostics. Use TaskDAG / DynamicTask separately when the application or visual automation surface owns the submitted graph.
treat
```
AgentExecution.strategy("auto"|"direct"|"flat"|"taskboard")
```
as the top-level route/execution selector.
```
direct
```
forces the ordinary model_request route with ActionLoop and does not create AgentTask; do not use
```
.effort("direct")
```
for route control.
```
auto
```
keeps ordinary prompt/action runs direct unless structural task signals such as goals, success criteria, task options, or Skill selectors enter AgentTask. Once AgentTask is selected, task
```
execution="auto"
```
uses one AgentTask-owned task-shape model request that allows free natural language analysis and then returns a thin structured
```
execution_hint
```
; do not route with keywords, regex, or local scorecards, and do not treat the hint as completion evidence. Use
```
execution="flat"
```
/
```
.strategy("flat")
```
to force the linear loop and
```
execution="taskboard"
```
/
```
.strategy("taskboard")
```
only when the host explicitly wants TaskBoard. Nested AgentExecution instances inherit the parent strategy context unless the child explicitly overrides it.
treat Blocks as the internal lowering bridge from AgentTask
```
ExecutionPlan
```
/
```
PlanBlock
```
instances to TriggerFlow-backed
```
ExecutionBlockGraph
```
, not as a public task lifecycle. Validated TaskDAG nodes use this carrier only through explicit
```
compile_blocks(...)
```
/
```
async_run_blocks(...)
```
; ordinary
```
TaskDAGExecutor.async_run(...)
```
compiles directly to TriggerFlow. PlanBlock selection is evidence of need, not permission; ExecutionBlocks cannot accept task completion. Blocks registries fail closed on unknown block kinds, invalid runtime bindings, invalid signal contracts, denied capabilities, or pending capabilities without an
```
approval_wait
```
.
```
skill_activation
```
loads selected Skill guidance/resources and records skill-context evidence, while side-effect evidence must come from downstream ActionRuntime, Workspace, approval, or other concrete execution blocks.
consume Agent quick prompt results through
```
AgentExecutionResult
```
:
```
execution = agent.input(...).output(...)
```
, then
```
result = execution.get_result()
```
and
```
result.get_data()
```
/
```
await result.async_get_data()
```
, or use execution facade methods such as
```
execution.get_prompt_text()
```
,
```
execution.get_data_object()
```
,
```
execution.get_key_result(...)
```
,
```
execution.wait_keys(...)
```
,
```
execution.get_async_generator(type="specific")
```
,
```
execution.streaming_print()
```
, and
```
await execution.async_get_meta()
```
when the app needs prompt inspection, object/key readers, streams, or process facts. For task-strategy route internals such as
```
status
```
,
```
artifact_status
```
,
```
taskboard
```
, or diagnostics, use
```
result.get_full_data()
```
/
```
await result.async_get_full_data()
```
. Direct low-level ModelRequest calls return ModelRequestResult; do not use the retired ModelResponseResult name. Ordinary
```
agent.input(...).start()
```
expressions create a fresh one-run execution each time and remain valid in loops. Explicit completed
```
AgentExecution
```
objects are immutable run records; do not reconfigure or rerun the same object, and create a new execution for the next request.
when the host owns a developer loop and needs one bounded Agent step, choose
```
agent.create_execution(lineage=..., limits=...)
```
plus explicit
```
execution.async_record_workspace(...)
```
observation/checkpoint writes before building the next ContextPackage; do not introduce task-step mode as a public category or make Workspace depend on AgentExecution semantics
when the model should own a single business task's plan, bounded execution, evidence recording, verification, and replan loop, choose
```
agent.create_task(...)
```
before hand-writing a TriggerFlow loop; it returns a task-strategy
```
AgentExecution
```
draft, not a separate public AgentTask handle. Use
```
agent.create_task_loop(...)
```
only when the code needs to be explicit that the long-task loop strategy is selected; it still returns an AgentExecution draft and should be consumed through the same result/stream/meta facade. Keep the first-slice boundary to one Agent owner, one task, 2-5 iterations, and bounded steps that use only explicitly enabled Actions or Skills; treat completion as model verification plus conservative host evidence guards, read task refs through the execution result/meta, and use a second model judge for model-owned semantic content instead of accepting structural counters alone
when an application needs to add optional operator context while a task-strategy AgentExecution is already running, use
```
await execution.async_add_guidance(...)
```
or
```
execution.add_guidance(...)
```
. Treat guidance as non-blocking context: AgentTask records it to Workspace
```
workspace_refs["guidance"]
```
, exposes
```
guidance_items
```
/
```
guidance_refs
```
, and applies it at the next Flat or TaskBoard safe boundary. It must not be used as completion evidence, must not be injected into non-task route prompts, and must not replace
```
pause_for(...)
```
/
```
continue_with(...)
```
when the workflow requires a blocking external answer.
when AgentTask completion depends on a particular capability, express it as framework contract rather than prompt force: expose capabilities through planner metadata, use structured
```
step_scope
```
for bounded action steps, and use
```
capability_evidence_requirements
```
for completion evidence. For side effects such as workspace writes/readbacks, require
```
action_succeeded
```
evidence for the host Actions instead of accepting model claims. Preserve prior action evidence in Workspace context packs before bulky execution metadata so later Skills or Action steps can use the actual evidence, not only a summary saying evidence was collected.
when a checkpointed AgentTask must resume after a crash, use
```
agent.resume(task_id)
```
or
```
await agent.async_resume(task_id)
```
and consume the returned task-strategy
```
AgentExecution
```
through
```
.start()
```
/
```
.async_start()
```
, result, stream, and meta surfaces. Treat
```
resume_task(...)
```
as a compatibility alias only; do not teach
```
AgentTask.async_resume(...)
```
,
```
task.async_run()
```
, or a bare AgentTask handle as the recommended public lifecycle
for feature or release acceptance, use coverage-first reasoning: start from the target contract in roadmap/spec/issues/docs/compatibility/example rules, map each requirement to evidence from examples, deterministic tests, protocol tests, docs/spec, compatibility metadata, companion validation, or explicit deferral, and only then conclude whether the feature is complete
for release acceptance that touches or claims a Foundation-layer capability, add a Foundation example effect gate after pyright/pytest: treat Foundation as framework substrate such as ModelRequest/ModelRequestResult, TriggerFlow, Dynamic Task/TaskDAG, ActionRuntime, ExecutionResource, Workspace/ContextBuilder, RuntimeEvent/EventCenter, and provider protocols, not application-level AgentExecution or Skills use cases by themselves; identify the affected Foundation capability, run the corresponding core example under
```
examples/
```
against the release candidate, use real DeepSeek or local Ollama when model-owned behavior is involved, and fail closed if the example effect is missing, broken, or only proven by tests
for public API or compatibility-line releases, run the public typing allowlist gate.
```
compatibility/public-typing-allowlist.json
```
is an exception ledger for documented
```
Any
```
boundaries with owner, reason, narrowing plan, and expiry; it is not a public-method allowlist, so new public methods must be fully typed unless they add a reviewed exception.
route complex arithmetic, long-number computation, weighting, aggregation, or statistical work through executable code or tools; use the model to produce or review the calculation plan, not to be the calculator.
when application development reveals a framework gap, first identify whether the missing responsibility belongs to Agently's public API, runtime behavior, documentation, Skills guidance, examples, or architecture boundary. Produce a concise issue report with scenario, expected behavior, actual behavior, current workaround, architectural responsibility, and minimal reproduction or affected docs/examples; recommend filing it in the Agently repository. The scenario must be clear enough to explain what kind of model-application development problem was being solved. If business details are confidential, omit or anonymize them, but still describe the application category, workflow shape, decision point, and framework responsibility needed for maintainers to understand the issue.
treat automatic issue submission as an explicit user-approved action. Before submitting, confirm the local environment has the needed GitHub capability and permission, reproduce the issue locally, and audit the relevant Agently docs, examples, Skills guidance, and API usage to rule out a reading omission or improper framework use. Submit only a sanitized issue body: no local absolute paths, usernames, account names, tokens, private repository or workspace names, internal project names, raw private logs, or customer/project-private prompts. Prefer placeholders such as
```
<workspace>
```
,
```
<repo>
```
,
```
<task-file>
```
, and
```
outputs/debug/<turn-id>.jsonl
```
.

对于服务代码、流式传输、TriggerFlow以及任何可能存在工作重叠或受益于取消机制的路径，默认提供异步优先的指导
将同步API视为脚本、REPL使用或兼容性桥接的包装器，除非宿主确实要求仅同步集成
在为复杂服务或脚本选择执行形态前，梳理实际阶段依赖关系。保留真实的顺序约束为串行执行，但对独立工作采用带压力控制的并发执行。为UI或可取消/幂等的准备工作使用临时
```
instant
```
字段，为应用自有协调逻辑使用TriggerFlow信号/连接。未经此分析就选择全串行设计是反模式
当请求是项目形态重构时，先分离设置、提示词、服务、领域契约、工作流和测试，再讨论底层实现细节
当开发脚本、服务模块或测试需要对模型自有行为进行语义判断时，使用带有明确输出Schema的Agently模型请求。开发时的意图识别、场景匹配、业务分类、输出质量检查、评分和审核决策应由模型负责，除非检查仅针对结构或必填字段存在性的确定性冒烟测试
当需要多轮模型实验进行问题发现或策略迭代时，遵循
```
references/model-quality-validation.md
```
：定义评估标准，仅将同上下文自模拟作为带标签的预热预检，绝不将模拟使用或提供商元数据视为观测遥测数据。稳定后，最多选择一个可行的独立冷评审载体——全新上下文的原生子Agent、握手验证的ACP编码Agent或全新的独立任务/会话。ACP为可选；同上下文生成不属于冷评审。仅向载体提供任务本地请求契约，强制宿主边界，并标记为
```
agent_simulation
```
，除非已证明是单一底层模型请求。若无可选载体，记录
```
cold_preflight=skipped
```
并继续进行最小范围的真实模型对比。真实追踪记录拥有最终结论。使用授权的项目/开发者凭据，并明确调用、并发、重试和预算上限；未经明确授权和披露上限，绝不使用客户凭据或配额
当模型输出必须严格满足已文档化的API请求、模块接口或函数调用时，构建一个明确的集成契约：将运行时事实放入
```
.input(...)
```
，权威的API/Schema文档、签名和文档字符串放入
```
.info(...)
```
，转换和调用规则放入
```
.instruct(...)
```
，精确的机器可消费类型和形态放入
```
.output(...)
```
。描述每个下游消费字段的类型、语义、必填性，以及任何适用的枚举、格式、范围、可空性或跨字段约束。这是必要的边界/输出控制，而非业务逻辑入侵。将无关的业务决策排除在契约之外，并在真实调用前进行确定性验证
当模型必须判断、选择、排序或引用宿主记录时，为每个候选对象投影一个宿主颁发的可信选择键，仅附带任务相关事实。要求模型返回该键作为判断的索引；不要让模型重现UUID、多个ID、不透明引用、完整记录或无关元数据。在宿主代码中验证返回的键是否在提供的集合中，然后确定性地查找并重建UUID、元数据和其他标识符。将包含大量身份信息的对象通过模型传输并信任其转录每个字段是反模式，而非有用的模型自有推理。选择键是应用本地的投影，而非另一个标准身份；将其定义为必填字符串，约束为提供的键集合，并在查找前拒绝未知或不允许的重复键
在
```
core/
```
或
```
builtins/
```
下添加或重构Agently框架内部代码时，若功能包含多个角色（如外观、管理器、后端/提供商、注册表、适配器、策略或验证），优先使用子目录包。仅当能力确实很小且拆分属于过度设计时，才使用单个文件
当项目需要测试模型生成的语义内容时，将测试设计为带有输出控制的Agently模型判断请求：输入明确的规则和上下文，输出每条规则的证据/理由和最终布尔字段，测试断言这些布尔值
对于带有模拟系统的业务示例，将模拟内容限制为事实、记录、策略、不完整数据或冲突源材料；不要返回隐藏的预期答案、通过/失败标签或本地质量 verdict。让AgentTask验证或单独的Agently模型判断来决定模型是否正确处理了有缺陷的数据
对于模型应用的评估、评分、置信度、相关性或质量判断，优先使用明确的概念级别和定义，而非直接数值分数。如果后续工作流逻辑需要阈值或聚合指标，在模型响应后在代码中将这些级别映射为确定性数值
在AI应用中的场景路由、意图检测或业务分类中，使用大小合适的模型请求并搭配Agently输出Schema。对于标签和规则较少的简单路由，较小的模型（包括可用的本地模型）即可满足需求。当标签、决策条件、规则交互或返回的数据结构复杂时，使用更大的模型
当代码拥有模型默认值、固定角色/提示词、挂载的Actions、Skills、Workspace、ContextBuilder配置文件或策略默认值时，使用
```
agent.define(...)
```
配置可复用的Agent定义状态。将普通的
```
agent.input(...)
```
、
```
agent.output(...)
```
、
```
.goal(goal_or_goals, success_criteria=None)
```
/
```
.goals(...)
```
作为相同的目标追求入口点，将执行选项放在AgentExecution草稿上；不要将共享Agent的待处理提示词变异作为默认设置模式
使用
```
agent.effort("low" | "medium" | "high")
```
控制普通策略深度。当应用需要明确的策略姿态时，使用相同方法并传入
```
budget
```
、
```
planning
```
、
```
execution
```
、
```
verification
```
、
```
replan
```
和
```
progress
```
等部分；将
```
budget
```
值视为软规划、反思、修复和证据深度提示，而非静默硬限制。当宿主需要硬资源控制时，使用明确的
```
limits={...}
```
或任务选项。框架默认不应施加模型请求、迭代、TaskBoard刻度、Action轮次、节点数量或工具调用配额；无进展和空闲超时是针对卡住执行的活性保护，而非策略证据。不要引入原始迭代计数构建器，也不要将effort视为权限、数据可见性、资源门控或完成接受的依据。在AgentTask中，effort还控制反思密度：low表示最终反思加上仅计划标记的重要流程节点，medium表示每个主要节点或TaskBoard卡片/刻度，high表示每个框架可观测的有限步骤、Action/ACP调用、TaskBoard卡片和最终反思。反思是重新规划/验证器输入的证据，而非完成证据本身
在目标追求/AgentTask示例中，调用者事实和请求的结构化输出契约可通过
```
.input(...)
```
和
```
.output(...)
```
存在于同一个
```
AgentExecution
```
草稿上；AgentTask在规划、有限步骤执行和验证期间将该执行提示快照视为任务上下文。不要将这些事实复制到框架硬编码中，仅为了让任务循环能看到它们
对于每个具有强结构化契约的中间流程，在所属请求/执行上使用Agently
```
.output(..., format=...)
```
。选择适合负载的格式（
```
json
```
、
```
hybrid
```
、
```
flat_markdown
```
、
```
xml_field
```
或
```
yaml_literal
```
）；如果声明的非JSON格式失败，Agently可通过JSON解析恢复，但只有字典形状的解析负载才能满足结构化控制或最终任务输出契约。AgentTask内部仅在框架有具体消费者的地方添加简短流程字段：路由/计划/控制决策前的意图或决策依据字段，以及主要结果字段后的紧凑自检、摘要、验证、修复或进度消息字段。这些是
```
process_summary
```
的有限事实，用于下一步的清晰度和观测，而非原始思维链、EvidenceEnvelope证据、完成证据或公共运行时模式
对于主要价值在于自然语言正文的长文或散文式交付物，不要仅为了承载文本而强制正文通过
```
.output()
```
。让正文以自然文本生成，然后使用紧凑的结构化判断/回读契约处理状态、证据、质量和工件引用。对于可信文件交付物，使用Workspace工件写入/回读加上紧凑的清单。不要仅为触发正文流的instant字段而添加
```
.output()
```
；当消费者处理重放边界时，普通公共delta仍是有效的正文来源。对于AgentTask支持的AgentExecution，公共
```
delta
```
还可将框架自有进度、动作观测、Flat计划/动作摘要、TaskBoard状态表、阶段、重试和终端结果事实投影为短段落，用空行分隔，而
```
instant
```
仍是UI状态和诊断的结构化流。Flat投影保持线性：计划完成可说明之前完成的动作和当前动作计划，终端输出可总结已完成的工作和结果。TaskBoard状态表是结构化AgentTask事件的仅显示投影；第一个TaskBoard投影可渲染表格，后续刻度可渲染卡片状态变化，而非重新打印整个表格。这些投影不拥有完成或质量判断。不要添加默认的并行叙述者请求来生成流程散文；使用现有计划器、验证器、卡片或最终器请求中的有限流程字段，如
```
progress_message
```
、
```
short_summary
```
、
```
verification_summary
```
和
```
final_response
```
，然后当UI需要更丰富的结构时，通过
```
instant
```
/合成
```
$delta
```
消费它们。内部工件写入器应消费AgentExecution流事实：自然正文文本来自原始delta项，重试边界来自提供商报告的
```
$status
```
。如果公共
```
"<$retry>...</$retry>"
```
delta重放标记到达工件消费者，将该确切标记视为重试控制事件；绝不要将其写入、清理或传输为工件内容。如果完整的Markdown工件正文出现在结构化
```
evidence
```
中，仅当证据项明确标记为artifact/body/deliverable/Markdown或与清单路径关联时，才将其视为交付物正文；普通源内容和源摘录仍是证据片段。可信Workspace写入/回读成功后，让终端验证判断任何过时的工件写入
```
remaining_work
```
，而非计划另一个仅写入步骤。对于长可信Workspace工件，工件交付应在真实Workspace写入/回读后记录
```
workspace_artifact.acceptance_locator
```
分类账项。定位器可使用工件清单部分、TaskBoard卡片标准和可选的模型返回
```
acceptance_points
```
意图，但行范围、偏移量、标题和指纹必须来自实际文件。验证器可见的证据可包括从这些定位器读取的有限
```
workspace_artifact.targeted_readback
```
分类账项，仅将声明的输出契约部分和通用锚点作为 fallback；将定位器视为回读指针，将定向回读视为范围证据片段，而非完成判断。TaskBoard最终确定应将基于文件的交付物正文保留在Workspace中，仅返回简洁的摘要或路径/引用指针作为
```
final_result
```
，而非文件正文的副本。AgentTask终端结果应携带面向用户的
```
final_response
```
，用于已接受、降级、部分完成和阻塞的结果：Flat终端验证可在现有验证器请求中返回它，TaskBoard最终确定可在现有最终器请求中返回它，框架fallback应根据结构化状态、工件引用、final_result指针和未满足的标准确定性生成，无需启动单独的叙述者请求。已接受的降级交付使用
```
artifact_status="degraded"
```
并披露证据限制，而有用但未被接受的工件保持
```
artifact_status="partial"
```
，并应解释未满足的要求，而非报告为已完成。
```
get_text()
```
/
```
async_get_text()
```
可能优先选择
```
final_response
```
作为任务策略结果字典；
```
get_data()
```
/
```
async_get_data()
```
在存在时返回业务
```
final_result
```
视图，而
```
get_full_data()
```
/
```
async_get_full_data()
```
返回完整的路由/任务信封。TaskBoard终端负载可包括有限的
```
taskboard.completion_notes
```
，用于卡片摘要、已知差距、验证器注释和接受进度；使用它们披露最终响应的限制，但将其视为仅投影的流程上下文，而非EvidenceEnvelope证据或完成证明。对于模型生成的验证器/最终器内容，
```
status
```
、
```
reason
```
、
```
progress_message
```
和
```
final_response
```
等散文字段仅为显示上下文；语义完成、可修复性和接受状态必须来自结构化输出字段，如
```
is_complete
```
、
```
requires_block
```
和
```
criterion_checks[].satisfied
```
加上宿主保护，绝不要通过对模型散文的分词、关键词、子字符串、正则或状态文本匹配来判断。TaskBoard规划卡片ID是可选的模型提示。框架拥有规范卡片ID、去重和依赖重映射；模糊的ID提示应失败而非猜测。中间下载、网页快照、生成的代码、搜索笔记、类内存任务笔记和大型提取文本也可作为Workspace/Action引用持久化，稍后通过有限回读打开；这些引用是执行证据，而非最终交付物存在的证明。发现的URL、路径、下载或快照引用也不是其内容已被读取的证据；在有限回读/内容预览可用前，将其视为
```
ref_only
```
。明确的
```
content
```
、
```
excerpt
```
或
```
snippet
```
字段仅为可见摘录的有限预览，而非整个文件已被读取的证明。当TaskBoard控制卡片需要在继续前具体化新的具体URL、路径或引用时，返回结构化
```
target_refs
```
并附带
```
next_board_action=readback
```
；不要依赖隐藏在
```
gaps
```
散文中的URL作为可执行目标。中间TaskBoard工件应保留在工作/证据路径上；框架标记的最终修复或继续卡片可写入所需的最终交付物路径，当该路径是任务输出契约的一部分时。如果TaskBoard控制卡片返回
```
next_board_action=patch
```
并附带Workspace文本补丁提案，AgentTask应将补丁具体化到绑定的Workspace文件中，并暴露生成的回读引用；验证器仍拥有完成判断。对于Flat仓库/文件任务，克隆或列出的清单路径在文件读取、工件回读或有限内容预览可见前是
```
ref_only
```
；将它们作为检索目标，而非源内容证据。TaskBoard最终验证接收保留
```
content_state
```
边界的板级源引用，因此最终合成不得在无有限预览/回读的情况下将发现的路径升级为源内容证据。TaskBoard检查点可包括有限的接受索引投影和交接投影，用于长期运行的恢复和检查。将这些投影仅视为定位：它们总结标准/卡片状态、证据引用、工件引用、预检事实和明确的任务范围脏数据或未解决状态事实，但它们不是
```
EvidenceEnvelope
```
证据，也不接受任务。接受索引还可携带脏数据/缓存状态、 verdict指纹、范围证据引用和进度计数器，以便TaskBoard避免重新验证未更改的绿色标准；脏项、所需交付物保护和明确的阻塞事实仍需通过验证器或宿主检查。预检要求必须来自挂载的Actions、ExecutionResources或现有Workspace引用；不要假设通用的git、浏览器、shell或启动脚本检查。TaskBoard调度默认采用事件驱动的
```
frontier
```
模式：已完成的卡片可立即解锁就绪的后续卡片，而扇入卡片仍需等待所有声明的依赖项。仅在历史刻度批处理诊断或回归比较时使用
```
taskboard_scheduler="batch"
```
。AgentTask基础使用规范的
```
EvidenceEnvelope.evidence_items
```
分类账。在
```
evidence_use
```
中优先使用可见的
```
cite_as
```
句柄或规范ID；路径、URL、记录、工件和动作/引用别名是生产者声明的结构兼容性便利，宿主保护仅在明确时才会规范化。保护不得依赖业务特定的动作名称规则。
```
scoped_retrieval_results
```
和TaskBoard
```
source_refs
```
等兼容性视图是投影。将
```
status=failed|empty
```
仅视为不可用/缺失数据证据，绝不要作为支持正面事实的依据。将
```
body_state=ref_only
```
仅视为发现/引用指针证据。当结构化输出支持时，返回带有
```
claim
```
、
```
evidence_ids
```
和
```
support_type
```
的
```
evidence_use
```
绑定。基于文件的任务输出还可返回可选的
```
acceptance_points
```
，包含标准、预期标题或精确锚点以及支持证据ID，以便框架在Workspace回读后构建定位器证据；不要编造行号或字节偏移量
AgentTask工作单元接收带有中间资源引用/回读策略和提示词安全运行时元数据的内部任务上下文契约。运行时记录可保留紧凑的
```
current_time
```
诊断，但默认的模型热提示词省略具体的运行时时间戳，仅暴露可用性元数据。对于当前、最新、最近或特定时间的任务，当业务日期重要时，要求调用者或源证据提供该日期。此契约是模型决策上下文，而非模型调用、工具调用、节点数量、迭代或挂钟时间上限，运行时时间本身不得用作业务/源事实
AgentTask观测从Action记录投影标准化的
```
agent_task.action.started
```
、
```
agent_task.action.completed
```
和
```
agent_task.action.failed
```
流事件。将它们视为UI、DevTools和实验日志的事实可观测性；恢复的
```
success
```
或
```
partial_success
```
Action记录投影为已完成观测，而失败观测仅保留给失败、阻塞、超时或未恢复的错误记录。不要将它们用作本地质量、相关性、路由或完成判断
将
```
execution.step_plan
```
仅视为兼容性指导。AgentTask不再使用TaskDAG / DynamicTask作为内部有限步骤策略；遗留的
```
dynamic_task
```
/
```
execution_dag
```
步骤建议和
```
effort(..., execution={"step_plan": "dag"})
```
降级为带有诊断的单个直接有限AgentExecution步骤。当应用或可视化自动化表面拥有提交的图时，单独使用TaskDAG / DynamicTask
将
```
AgentExecution.strategy("auto"|"direct"|"flat"|"taskboard")
```
视为顶级路由/执行选择器。
```
direct
```
强制使用带有ActionLoop的普通model_request路由，不创建AgentTask；不要使用
```
.effort("direct")
```
进行路由控制。
```
auto
```
保持普通提示词/动作运行直接进行，除非结构任务信号（如目标、成功标准、任务选项或Skill选择器）进入AgentTask。一旦选择AgentTask，任务
```
execution="auto"
```
使用一个AgentTask自有任务形态模型请求，允许自由自然语言分析，然后返回精简的结构化
```
execution_hint
```
；不要使用关键词、正则或本地评分卡进行路由，也不要将提示视为完成证据。使用
```
execution="flat"
```
/
```
.strategy("flat")
```
强制线性循环，仅当宿主明确需要TaskBoard时使用
```
execution="taskboard"
```
/
```
.strategy("taskboard")
```
。嵌套的AgentExecution实例继承父策略上下文，除非子实例显式覆盖
将Blocks视为从AgentTask
```
ExecutionPlan
```
/
```
PlanBlock
```
实例到TriggerFlow支持的
```
ExecutionBlockGraph
```
的内部转换桥接，而非公共任务生命周期。已验证的TaskDAG节点仅通过显式的
```
compile_blocks(...)
```
/
```
async_run_blocks(...)
```
使用此载体；普通的
```
TaskDAGExecutor.async_run(...)
```
直接编译为TriggerFlow。PlanBlock选择是需求的证据，而非权限；ExecutionBlocks不能接受任务完成。Blocks注册表在遇到未知块类型、无效运行时绑定、无效信号契约、被拒绝的能力或无
```
approval_wait
```
的待处理能力时，默认失败。
```
skill_activation
```
加载选定的Skill指导/资源并记录技能上下文证据，而副作用证据必须来自下游的ActionRuntime、Workspace、审批或其他具体执行块
通过
```
AgentExecutionResult
```
消费Agent快速提示词结果：
```
execution = agent.input(...).output(...)
```
，然后
```
result = execution.get_result()
```
和
```
result.get_data()
```
/
```
await result.async_get_data()
```
，或者当应用需要提示词检查、对象/键读取器、流或流程事实时，使用执行外观方法，如
```
execution.get_prompt_text()
```
、
```
execution.get_data_object()
```
、
```
execution.get_key_result(...)
```
、
```
execution.wait_keys(...)
```
、
```
execution.get_async_generator(type="specific")
```
、
```
execution.streaming_print()
```
和
```
await execution.async_get_meta()
```
。对于任务策略路由内部信息，如
```
status
```
、
```
artifact_status
```
、
```
taskboard
```
或诊断，使用
```
result.get_full_data()
```
/
```
await result.async_get_full_data()
```
。直接底层ModelRequest调用返回ModelRequestResult；不要使用已废弃的ModelResponseResult名称。普通的
```
agent.input(...).start()
```
表达式每次创建一个全新的单次运行执行，在循环中仍然有效。已显式完成的
```
AgentExecution
```
对象是不可变的运行记录；不要重新配置或重新运行同一个对象，为下一个请求创建新的执行
当宿主拥有开发循环并需要一个有限的Agent步骤时，选择
```
agent.create_execution(lineage=..., limits=...)
```
，并在构建下一个ContextPackage前显式调用
```
execution.async_record_workspace(...)
```
进行观测/检查点写入；不要将任务步骤模式作为公共类别引入，也不要让Workspace依赖AgentExecution语义
当模型应拥有单个业务任务的计划、有限执行、证据记录、验证和重新规划循环时，在手动编写TriggerFlow循环前选择
```
agent.create_task(...)
```
；它返回任务策略的
```
AgentExecution
```
草稿，而非单独的公共AgentTask句柄。仅当代码需要明确选择长任务循环策略时，使用
```
agent.create_task_loop(...)
```
；它仍返回AgentExecution草稿，并应通过相同的结果/流/元外观消费。将第一切片边界限制为一个Agent所有者、一个任务、2-5次迭代，以及仅使用显式启用的Actions或Skills的有限步骤；将完成视为模型验证加上保守的宿主证据保护，通过执行结果/元读取任务引用，并使用第二个模型判断来处理模型自有语义内容，而非仅接受结构计数器
当应用需要在任务策略AgentExecution已运行时添加可选的操作员上下文时，使用
```
await execution.async_add_guidance(...)
```
或
```
execution.add_guidance(...)
```
。将指导视为非阻塞上下文：AgentTask将其记录到Workspace
```
workspace_refs["guidance"]
```
，暴露
```
guidance_items
```
/
```
guidance_refs
```
，并在下一个Flat或TaskBoard安全边界应用它。不得将其用作完成证据，不得注入非任务路由提示词，当工作流需要阻塞外部答案时，不得替代
```
pause_for(...)
```
/
```
continue_with(...)
```
当AgentTask完成依赖于特定能力时，将其表示为框架契约而非提示词强制：通过计划器元数据暴露能力，为有限动作步骤使用结构化
```
step_scope
```
，为完成证据使用
```
capability_evidence_requirements
```
。对于诸如工作区写入/回读等副作用，要求宿主Actions提供
```
action_succeeded
```
证据，而非接受模型声明。在庞大的执行元数据前，将先前的动作证据保留在Workspace上下文包中，以便后续Skills或Action步骤可以使用实际证据，而非仅使用说明已收集证据的摘要
当检查点的AgentTask必须在崩溃后恢复时，使用
```
agent.resume(task_id)
```
或
```
await agent.async_resume(task_id)
```
，并通过
```
.start()
```
/
```
.async_start()
```
、结果、流和元表面消费返回的任务策略
```
AgentExecution
```
。仅将
```
resume_task(...)
```
视为兼容性别名；不要将
```
AgentTask.async_resume(...)
```
、
```
task.async_run()
```
或裸AgentTask句柄作为推荐的公共生命周期
对于功能或发布接受，使用覆盖优先推理：从路线图/规范/问题/文档/兼容性/示例规则中的目标契约开始，将每个要求映射到示例、确定性测试、协议测试、文档/规范、兼容性元数据、伴随验证或明确延迟的证据，然后再得出功能是否完整的结论
对于涉及或声称Foundation层能力的发布接受，在pyright/pytest后添加Foundation示例效果门控：将Foundation视为框架基础，如ModelRequest/ModelRequestResult、TriggerFlow、Dynamic Task/TaskDAG、ActionRuntime、ExecutionResource、Workspace/ContextBuilder、RuntimeEvent/EventCenter和提供商协议，而非仅应用级别的AgentExecution或Skills用例；识别受影响的Foundation能力，针对候选版本运行
```
examples/
```
下的相应核心示例，当涉及模型自有行为时使用真实的DeepSeek或本地Ollama，如果示例效果缺失、失效或仅通过测试证明，则默认失败
对于公共API或兼容性版本发布，运行公共类型允许列表门控。
```
compatibility/public-typing-allowlist.json
```
是已文档化
```
Any
```
边界的异常分类账，包含所有者、原因、缩小计划和到期时间；它不是公共方法允许列表，因此新公共方法必须完全类型化，除非添加了经过审核的异常
将复杂算术、长数字计算、加权、聚合或统计工作路由到可执行代码或工具；使用模型生成或审查计算计划，而非让模型充当计算器
当应用开发揭示框架差距时，首先确定缺失的职责属于Agently的公共API、运行时行为、文档、Skills指导、示例还是架构边界。生成简洁的问题报告，包含场景、预期行为、实际行为、当前解决方法、架构职责和最小复现或受影响的文档/示例；建议提交到Agently仓库。场景必须足够清晰，解释正在解决的模型应用开发问题类型。如果业务细节保密，省略或匿名化，但仍需描述应用类别、工作流形态、决策点和框架所需的职责，以便维护者理解问题
将自动问题提交视为明确的用户批准操作。提交前，确认本地环境具备所需的GitHub能力和权限，在本地复现问题，并审核相关的Agently文档、示例、Skills指导和API使用，排除阅读遗漏或框架使用不当的情况。仅提交经过清理的问题正文：无本地绝对路径、用户名、账户名、令牌、私有仓库或工作区名称、内部项目名称、原始私有日志或客户/项目私有提示词。优先使用占位符，如
```
<workspace>
```
、
```
<repo>
```
、
```
<task-file>
```
和
```
outputs/debug/<turn-id>.jsonl
```

Capability Routing

能力路由

model setup, prompt management, output control, response reuse, session memory, embeddings, KB, or retrieval-to-answer ->
```
agently-request
```
Action Runtime, built-in actions, tools compatibility, MCP, ExecutionResource, FastAPIHelper,
```
auto_func
```
,
```
KeyWaiter
```
, or
```
agently-devtools
```
observation and evaluation integration ->
```
agently-runtime
```
model-generated or app-submitted DAG planning, TaskDAG validation, resolver handlers, or Dynamic Task execution ->
```
agently-dynamic-task
```
branching, concurrency, waiting/resume, mixed sync/async orchestration, event-driven fan-out, process-clarity refactors, runtime stream, graph-friendly workflow definitions, or explicit multi-stage quality loops ->
```
agently-triggerflow
```
migration choice between LangChain and LangGraph ->
```
agently-migration
```

模型设置、提示词管理、输出控制、响应复用、会话记忆、嵌入、知识库或检索到回答 ->
```
agently-request
```
Action Runtime、内置动作、工具兼容性、MCP、ExecutionResource、FastAPIHelper、
```
auto_func
```
、
```
KeyWaiter
```
或
```
agently-devtools
```
观测与评估集成 ->
```
agently-runtime
```
模型生成或应用提交的DAG规划、TaskDAG验证、解析器处理程序或Dynamic Task执行 ->
```
agently-dynamic-task
```
分支、并发、等待/恢复、混合同步/异步编排、事件驱动扇出、流程清晰度重构、运行时流、图形友好的工作流定义或明确的多阶段质量循环 ->
```
agently-triggerflow
```
LangChain与LangGraph之间的迁移选择 ->
```
agently-migration
```

Anti-Patterns

反模式

do not skip this playbook when the owner layer is unresolved
do not invent custom output parsers, retry loops, or orchestration first
do not use keyword, substring, regex, or text snapshot checks as the primary correctness signal for model-owned semantic content; keep them only as smoke gates for structure, routing, or required-field presence
do not use tokenization, word segmentation, keyword hits, or substring rules as the route owner for AI-app scenario routing, intent detection, or business classification
do not put model-app quality gates, business scoring, or route choice into local helper functions that only count words, split tokens, search keywords, or compare snapshots when an Agently model request can own the judgment
do not let sync-first sample code dictate the service architecture when the target is clearly async-capable
do not default a complex service or script to all-serial execution without first identifying real data, ordering, side-effect, and capacity constraints
do not split project initialization into a fake standalone framework surface before the owner layers are chosen
do not treat multi-agent, judge, or review flows as separate framework surfaces before checking native Agently capabilities
do not normalize long-lived business patches, workarounds, compatibility glue, or private wrappers when the underlying need is a missing, broken, misleading, undocumented, or unfriendly Agently framework capability

当所属层级尚未明确时，不要跳过本手册
不要首先发明自定义输出解析器、重试循环或编排逻辑
不要将关键词、子字符串、正则或文本快照检查作为模型自有语义内容的主要正确性信号；仅将它们作为结构、路由或必填字段存在性的冒烟测试
不要将分词、分词、关键词命中或子字符串规则作为AI应用场景路由、意图检测或业务分类的路由所有者
当Agently模型请求可负责判断时，不要将模型应用质量门控、业务评分或路由选择放入仅计数单词、拆分令牌、搜索关键词或比较快照的本地辅助函数中
当目标明确支持异步时，不要让同步优先的示例代码决定服务架构
在未首先识别真实数据、顺序、副作用和容量约束前，不要将复杂服务或脚本默认设置为全串行执行
在选择所属层级前，不要将项目初始化为虚假的独立框架表面
在检查原生Agently能力前，不要将多Agent、判断或审查流视为单独的框架表面
当底层需求是Agently框架能力缺失、失效、误导、未文档化或不友好时，不要规范化长期业务补丁、解决方法、兼容性粘合代码或私有包装器

后续阅读

```
references/capability-map.md
```
```
references/project-framework.md
```
```
references/model-quality-validation.md
```

```
references/capability-map.md
```
```
references/project-framework.md
```
```
references/model-quality-validation.md
```
",

agently

Original

Translation

Agently

Agently

Workflow

工作流程

Native-First Rules

原生优先规则

Capability Routing

能力路由

Anti-Patterns

反模式

Read Next

后续阅读