Agent step definitions and execution boundary

Status: configuration/refusal infrastructure. Agent steps can be authored, validated and retained; execution is unavailable. AGPIPE-1 runtime qualification, trusted requirements, durable acquisition and independent evaluation remain open in BACKLOG.md.

An agent step consumes one upstream target input and describes observation records. It reuses DataContract and the existing Pipeline manifest envelope, pycharter.io/v2. Instructions and executor settings are inline configuration; there is no new task language or profile/account artifact. Normalization belongs in a declared transform. Provider events, usage and evidence manifests are run information, not observation rows.

Authored fields

Every nested agent setting rejects unknown fields. New limit fields require strict positive integers; numeric strings, floats and booleans do not pass.

Field	Meaning
id, type: agent, input	Named step and one upstream input
targets.contract	Existing file/Store DataContract reference for target rows
targets.key_fields, targets.url_field	Explicit stable-key components and source URL field
executor.runtime.name/version	Exact installed runtime binding identity; no import path
executor.credentials	Named env:NAME or absolute file:/... references only
executor.context.id	Non-secret context request, not authority or proof of location
instructions	Nonempty text, at most 16,384 characters
checks	Unique check IDs, exact evaluator name/version, required flag and bounded plain JSON parameters
evidence	Required evidence kinds, per-attempt/run byte caps, retention seconds and requested read roles
limits	Whole-run attempts, per-attempt duration/optional steps, concurrency and whole-run spending bound
permissions	Requested read effects and explicit HTTP(S) origins
contract	Existing output StepContractBlock; validation and on_error: fail are mandatory

Check parameters must be plain JSON objects, at most 16KiB, depth 10 and 1,024 visited values. These are configuration-shape bounds, not evidence or provider limits. Empty credentials and explicitly authored default/null fields survive canonical serialization and retained Store round trips. Both target and output contract references participate in reference collection.

max_attempts includes every attempt and retry across the run. It is distinct from the number of target identities. max_duration_seconds_per_attempt and optional max_steps_per_attempt use per-attempt units. max_concurrent_attempts defaults to one and cannot exceed max_attempts. max_spend.currency/minor_units specifies the whole-run bound, including failures and retries; it is not a per-target allowance or a provider usage estimate.

Evidence's max_bytes_per_run covers retained retry history as well as current attempts. The per-attempt cap cannot exceed it. Retention and read roles are requests to be checked against operator grants and actual Store/runtime support. These declarations do not implement retention, access control or billing limits. No provider timeout, cost, freshness or evidence-size number becomes an implicit production default.

References and mandatory checks

Credential references are validated lexically and never resolved by the parser. Agent bodies do not undergo generic environment-variable interpolation. A variable-disguised agent discriminator cannot cause its credential body to be resolved before refusal. Literal secret values and interpolation expressions are invalid credential references; keep actual values in the approved external secret source.

Origins must be explicit canonical HTTP(S) origins without URL credentials, paths, query data, fragments or wildcard hosts. An origin request does not prevent consequential actions on that origin. Requested read effects remain separate from operator grants and enforceable runtime controls.

The output contract cannot disable validation, use warn/skip/quarantine behavior or select a quarantine destination. Its existing explicitly declared coercion semantics remain available, including narrow timestamp conversion; strict money types are not relaxed. Provider schema acceptance cannot replace canonical validation or independent factual/evidence checks.

A task-authored optional flag cannot waive trusted frozen mandatory checks. No such trusted requirements/runtime admission context exists in this slice, so all agent execution refuses, including an all-optional check list. This is not an evaluator, target-freezing or capability-enforcement implementation.

Current refusal behavior

The capability registry advertises agent configuration with execution unavailable, without a runtime factory. Pipeline.preflight(), normal and dry runs return a failed preflight with agent_execution_unavailable before configured contract-store creation, source/destination construction or progress and lineage callbacks. Low-level run_dag raises a structured PipelineConfigError with the same code instead of silently succeeding. Unknown low-level step types also refuse with unsupported_step_type.

Step preview checks the selected upstream graph, including variable-bound routing fields, before resolving agent bodies or probing sources. Selecting an agent or any dependent transform/load refuses. A separate supported preview branch can still run. Retained executable bundles continue to reject unsupported agent definitions. No provider submission or publication is enabled.

Existing editors reject unsupported agent documents before graph projection, saving, running or source probing, and retain existing raw stored view/export surfaces. They do not supply an agent form or editable fallback. Use a backend containing this schema for retention; older backends reject the unknown tag. Frontend checks cannot establish the contents of an unseen server definition; backend execution refusal remains authoritative. Routine API authentication and operational database access are separate from configured pipeline source I/O.

The historical pilot's 0.1.0 and public-offer 0.2.0 contracts remain examples of record meaning. They do not create a runnable agent Pipeline. See the contract reference and qualification record.