Skip to content

Integration Seams

Agent integrations cross content, control, provider, artifact, and runtime boundaries. These seams must remain separate: a model adapter supplies role content, while typed orchestration owns lifecycle authority. A convenient provider or CLI wrapper must not become hidden approval policy.

Orchestration Handoff

flowchart LR
    input["AgentInput and source identity"] --> controller["typed pipeline control"]
    config["resolved policy and hashes"] --> controller
    provider["model adapter and metadata"] --> roles["passive roles"]
    controller --> roles
    roles --> observations["validated role outputs"]
    observations --> controller
    controller --> trace["ordered RunTrace"]
    trace --> result["derived PipelineResult"]
    result --> runtime["runtime admission"]

The feedback edge carries observations, not authority. Roles cannot select their own transitions, erase vetoes, or declare terminal success outside typed control.

Seam Contracts

Seam Required input Agent produces Refusal boundary
task input immutable task goal, payload, context, source identity, execution mode normalized AgentInput and attempt identity changed bytes or meaning under reused identity
configuration YAML plus explicit overrides resolved limits, retry, feedback, logging and model configuration with hashes untracked override or invalid policy
provider declared model adapter, credentials, timeout and metadata schema-validated role output and actual model metadata authentication, rate limit, timeout, provider or schema failure
controller valid input, resolved policy, passive role observations lifecycle transitions, convergence, veto, stop and termination states forbidden transition or incompatible terminal state
trace/result complete ordered trace and derived public fields run_trace.json and final_result.json missing mandatory field, schema failure, or parity mismatch
runtime full agent evidence and authority-neutral result no implicit run acceptance runtime policy rejects or cannot establish complete custody

Input And Configuration Identity

In-process callers construct AgentInput values. The CLI resolves a file or directory and applies the configured task goal to selected inputs. If source bytes, task meaning, or material context changes, issue a new identity; do not reuse cached, comparable, or replayable labels from the earlier attempt.

Configuration precedence is constructor parameters, pipeline parameters, top-level values, then defaults. Archive the resolved configuration and its hash. Retaining source YAML alone loses command-line and constructor overrides. The recorded provider, model, temperature, and token limit must describe the actual call, not only the intended configuration.

Provider Admission

flowchart TD
    adapter["provider adapter"] --> identity{"model metadata complete?"}
    identity -->|no| reject["reject call evidence"]
    identity -->|yes| effect{"network and retry policy declared?"}
    effect -->|no| reject
    effect -->|yes| output{"output validates?"}
    output -->|no| reject
    output -->|yes| record["record role observation"]

Provider adapters expose authentication, network, timeout, rate-limit, version, and retry failure domains. A retry policy must distinguish transient reads from effects that cannot safely repeat.

The CLI currently requires OpenAI, Anthropic, HuggingFace, and DeepSeek keys before command dispatch, including offline-oriented commands. This bootstrap constraint does not mean a workflow executes all four providers.

CLI, HTTP, And Replay

A successful non-dry CLI run writes result/final_result.json and trace/run_trace.json. They are separate writes without a manifest or transactional completion marker. Directory execution may process multiple files while the primary artifact reflects the first successful entry. Batch consumers must retain every per-file outcome and reconcile the full input set.

The HTTP application exposes a fixed deterministic offline simple/extractive pipeline. Its narrow configuration schema does not grant arbitrary role, provider, backend, or model selection. It is a distinct integration posture from the provider-backed CLI.

Replay upgrades and validates the stored trace, reconstructs the public result, and compares the adjacent result when available. It does not call providers. Non-zero temperature and incomplete replay identity restrict replayability.

Runtime Admission

Runtime needs input and task identity, resolved configuration, pipeline hash, model metadata, complete trace, per-input outcomes, convergence and termination state, and final result. It may accept, reject, and persist the wider run; it must not rewrite agent history, turn interruption into completion, or convert a verification veto into success.

For the installed local research path, Runtime supplies an InstalledResearchPort that exposes Reason planning/convergence and persistent Index retrieval. InstalledResearchService combines the plan with its content-addressed observed state and selects actions from explicit guards. A satisfied no-search state, a bounded no-result search, material opposition, ambiguous evidence, unclassified candidates, and tool failure therefore do not emit the same role sequence. This keeps evidence semantics in Reason, retrieval semantics in Index, workflow decisions in Agent, and durable artifact/run custody in Runtime. Runtime may serialize the returned state and events into its versioned artifact, but it must not synthesize missing Agent events or promote a blocking gap to completion.

Before Agent selects an action, Reason derives a question-specific answer requirement plan from the actual grounded claims, semantic citation verdicts, admission gaps, synthesis roles, and any exact prior skeptical-search closure. Runtime maps that typed plan without inventing requirements. Agent retains the full requirement semantics in observed state and permits search only for material unresolved requirements with a query and an in-scope claim target.

Agent also owns requirement-targeted query selection. Each admitted call binds one unresolved requirement, its support, opposition, limitation, disambiguation, or context intent, substantive query, satisfaction criteria, causal trigger, and prior attempts. Case, Unicode, whitespace, and punctuation-equivalent attempts share an equivalence identity and cannot be executed repeatedly. Runtime executes the selected query but cannot replace it with the same generic per-claim request.

After each call, Agent records a typed observation and replans from the full attempt history. A bounded no-result observation broadens terminology and context, ambiguity targets exact entity/scope/quantity qualifiers, and classified opposition requests reconciliation and boundary evidence. A material unclassified candidate or retrieval refusal pauses further querying; neither is treated as support. Every executed call consumes one search-budget unit.

See configuration for precedence and artifact contracts for evidence fields.