Graphorin API reference v0.12.1
Graphorin API reference / @graphorin/agent / / AgentConfig
Interface: AgentConfig<TDeps, TOutput>
Defined in: packages/agent/src/types.ts:166
The full options object accepted by createAgent.
Stable
Type Parameters
| Type Parameter | Default type |
|---|---|
TDeps | unknown |
TOutput | string |
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
autoAssembleContext? | readonly | boolean | Opt in to building the per-run system prompt from the memory ContextEngine (CE-1). When true and memory is wired, the runtime calls memory.contextEngine.assemble(...) once at run start: the agent's instructions become Layer 2 and the engine prepends the memory base and appends working blocks, procedural rules, skill cards, the metadata counts, and - when factsAutoRecall is configured - auto-recalled facts. Defaults false: the prompt is built from instructions alone and the model reaches memory only through the memory tools it calls (the documented explicit pattern). Has no effect without memory. | packages/agent/src/types.ts:213 |
cachePolicy? | readonly | ProviderCachePolicy | Opt-in prompt-cache breakpoint policy (core-provider-02), forwarded verbatim on every ProviderRequest the loop issues. With { breakpoints: 'auto' } the Anthropic path (vercel adapter) anchors cache_control markers on the first and last conversation messages, so the stable prefix (tools + system + early turns) is written to the provider cache once and read at the discounted rate on every later step. Providers with automatic caching ignore it. Pair with the append-only transcript the loop already maintains - cache hit rate is the #1 production cost lever for multi-step agents. | packages/agent/src/types.ts:360 |
capability? | readonly | "read-only" | Agent-default capability restriction (D2). 'read-only' builds a side-effect-free agent: writer tools and handoffs are never advertised and the executor blocks writer calls deterministically (capability_blocked). Per-call override: AgentCallOptions.capability. See AgentCapability. | packages/agent/src/types.ts:430 |
causalityMonitor? | readonly | CausalityMonitorConfig | - | packages/agent/src/types.ts:310 |
checkpointPolicy? | readonly | "keep" | "delete-on-terminal" | What happens to the run's checkpoint thread when the run reaches a terminal status (W-005). 'keep' (default) preserves the current behaviour: checkpoints survive for post-hoc debugging and process-restart resume. 'delete-on-terminal' best-effort deletes the thread after completed / failed runs; awaiting_approval and aborted runs always keep theirs (the thread IS the resume state). Requires AgentConfig.checkpointStore. Default 'keep' | packages/agent/src/types.ts:421 |
checkpointStore? | readonly | CheckpointStore | - | packages/agent/src/types.ts:410 |
codeMode? | readonly | { limits?: CodeExecuteLimits; run?: CodeModeRunner; } | E3 (item 13, step 1): the code-mode runtime and its limits. run substitutes WHERE the model-written script executes (a subprocess provider, a remote runner) - any CodeModeRunner; default is the in-process worker_threads runner (runBridgedSource). limits bound the script (wall-clock, memory, bridged-call count) whatever the runtime. Fixed invariant: the runner receives only the script source, the allowed tool names, the host dispatch bridge and these limits - credentials, RunState and policy stay on the harness side (every in-script tool call routes back through the executor's governance). Only meaningful with toolInvocation: 'code-mode'; ignored otherwise. | packages/agent/src/types.ts:293 |
codeMode.limits? | readonly | CodeExecuteLimits | - | packages/agent/src/types.ts:295 |
codeMode.run? | readonly | CodeModeRunner | - | packages/agent/src/types.ts:294 |
dataFlowPolicy? | readonly | DataFlowPolicyConfig | Provenance / taint-based data-flow policy (P1-3, opt-in). Enforces data-flow rules at the tool-execution boundary using the provenance Graphorin already tracks (trust class + source + sensitivity), to defuse the lethal trifecta: a sink (side-effecting / external-stateful tool) is blocked when untrusted content flows into it verbatim, or - conservatively - when it fires while both untrusted content and secret-tier data are present in the run. - mode: 'shadow' - audit-only; tainted flows are flagged (tool:dataflow:flagged audit + counter) but never blocked. Ship this first to surface false positives. - mode: 'enforce' - tainted flows are blocked (the sink does not run; the call yields a dataflow_policy_blocked error) unless the sink is listed in declassifySinks (an audited operator override). Composes with 'code-mode': each in-script tool call flows through the same executor gate. Absent (the default) leaves the loop unchanged. | packages/agent/src/types.ts:339 |
deps? | readonly | TDeps | - | packages/agent/src/types.ts:473 |
fallbackModels? | readonly | readonly ModelSpec[] | - | packages/agent/src/types.ts:297 |
fallbackPolicy? | readonly | AgentFallbackPolicy | - | packages/agent/src/types.ts:298 |
guardrails? | readonly | { input?: readonly InputGuardrail<string>[]; output?: readonly OutputGuardrail<TOutput>[]; } | Deterministic checks run by the loop (AG-2; canonical contract is @graphorin/security's GuardrailDefinition - SDF-4). - input guardrails run over each fresh-run seed user message (string content) before the first provider call. 'block' fails the run (guardrail-blocked) without reaching the model; 'rewrite' replaces the message content (mirrored into the persisted RunState); 'warn' logs and continues. - output guardrails run over the final output on the completed path before agent.end. 'block' fails the run; 'rewrite' replaces result.output (text deltas were already streamed - the rewrite governs the durable result, not the live token stream). Every trip emits a guardrail.tripped event. | packages/agent/src/types.ts:255 |
guardrails.input? | readonly | readonly InputGuardrail<string>[] | - | packages/agent/src/types.ts:256 |
guardrails.output? | readonly | readonly OutputGuardrail<TOutput>[] | - | packages/agent/src/types.ts:257 |
handoffs? | readonly | readonly HandoffEntry<TDeps>[] | - | packages/agent/src/types.ts:236 |
instructions | readonly | string | ((ctx) => string | Promise<string>) | The agent's system prompt. A string is used verbatim; a function is resolved once per run (sync or async, awaited) against a RunContext snapshot at step 0, and its result is pinned as the run's system-prompt prefix for the whole run (it is not re-evaluated per step). An empty string injects no system message. | packages/agent/src/types.ts:175 |
maxParallelTools? | readonly | number | - | packages/agent/src/types.ts:262 |
maxVerifierRounds? | readonly | number | Cap on verifier-triggered continuation rounds per run (C3). Default 1 | packages/agent/src/types.ts:389 |
memory? | readonly | Memory | - | packages/agent/src/types.ts:179 |
mergeGuard? | readonly | MergeGuardConfig | Sideways-injection merge guard for agent.fanOut 'judge-merge' (AG-7): scores per-child source trust × contribution weight against the judge's merged output; a biased merge emits agent.lateral-leak.detected and 'detect-and-block' throws MergeBlockedError. | packages/agent/src/types.ts:318 |
modelTierMap? | readonly | Partial<Record<ModelHint, ModelSpec>> | - | packages/agent/src/types.ts:300 |
name | readonly | string | - | packages/agent/src/types.ts:167 |
outputType? | readonly | OutputSpec<TOutput> | - | packages/agent/src/types.ts:237 |
permissionHook? | readonly | PermissionHook | E1 pre-tool permission hook: one caller-supplied decision point (`allow | deny |
plan? | readonly | boolean | Register the D6 structured plan tool (update_plan, TodoWrite-style) and recite the plan back into each step's prompt (attention recitation). The plan is journaled in RunState.todos and survives resume. Default false - off keeps the tool surface unchanged. | packages/agent/src/types.ts:470 |
preferredModel? | readonly | | ModelSpec | ModelHint | - | packages/agent/src/types.ts:299 |
prepareStep? | readonly | PrepareStepHook<TDeps> | - | packages/agent/src/types.ts:261 |
procedureInduction? | readonly | { auto?: boolean; minCostUsd?: number; minSteps?: number; minToolCalls?: number; } | Opt-in auto-induction (wave-D D4): after a run COMPLETES at or above every complexity threshold, the runtime calls memory.procedural.induceFromRun(...) to distil the trajectory into a procedure candidate. The induced rule always lands QUARANTINED - it reaches the prompt only after validation (or the D4 promotion policy). Requires memory (and a workflow inducer configured on it - procedureInduction on createMemory); induction failures WARN once and never fail the run. The call is awaited before agent.end, so wire a cheap inducer model. Failed / aborted / suspended runs never induce. | packages/agent/src/types.ts:192 |
procedureInduction.auto? | readonly | boolean | Master switch. Default false. | packages/agent/src/types.ts:194 |
procedureInduction.minCostUsd? | readonly | number | Minimum observed run cost in USD (0 = ignore cost). Default 0. | packages/agent/src/types.ts:200 |
procedureInduction.minSteps? | readonly | number | Minimum completed steps. Default 3. | packages/agent/src/types.ts:196 |
procedureInduction.minToolCalls? | readonly | number | Minimum total tool calls across steps. Default 3. | packages/agent/src/types.ts:198 |
provider | readonly | Provider | - | packages/agent/src/types.ts:176 |
reasoningRetention? | readonly | ReasoningRetention | Per-agent override of the per-provider auto-detected ReasoningRetention default. Wins over the provider- level default when both are present. The agent runtime feeds the effective value into every provider.stream(...) call so the wire-correct contract is honoured per RB-42 / suggested DEC-158 / suggested ADR-046. | packages/agent/src/types.ts:309 |
recordProviderResponses? | readonly | boolean | C3: journal each step's raw model response (text + tool calls + model id) onto RunState.steps[].providerResponse, enabling deterministic replay via createReplayProvider(state) - reproduce an entire run without live model calls. Default false | packages/agent/src/types.ts:408 |
resultReaders? | readonly | readonly ResultReader[] | Additional result-handle readers (P1-4 / WI-13), tried after the built-in spill-file reader. Wire an MCP resource reader (createMcpResourceReader from @graphorin/mcp/client) here so the model can resolve an MCP resource_link on demand via the built-in read_result tool, instead of inlining the resource body. Supplying any reader force-registers read_result even when no tool spills. | packages/agent/src/types.ts:348 |
ruleOfTwo? | readonly | RuleOfTwoProfile | Rule-of-Two capability profile (D4). Declares which of {untrusted input, sensitive data, external side effects} this agent may hold; denying external side effects forces a read-only capability floor and blocks writer tools, denying sensitive data default-denies sensitive tools. Holding all three is the dangerous configuration the preset is designed to prevent. See @graphorin/security/policy. | packages/agent/src/types.ts:447 |
scaffold? | readonly | "full" | "minimal" | Context-scaffolding preset (C6, decision D-10). 'full' (default) is exactly the pre-C6 behaviour. 'minimal' is the cheap-run posture for proactive fires and heartbeats: - instructions-only system prompt - autoAssembleContext must stay off (an explicit autoAssembleContext: true alongside 'minimal' is a config error, fail-fast); - deferred tool loading by default - every registered tool without an explicit defer_loading declaration is withheld from the per-step catalogue and reachable through tool_search promotion (an explicit defer_loading: false stays eager); - no plan tool, no attention recitation - plan: true alongside 'minimal' is a config error. Security layers (permission mode, sandbox, taint, Rule-of-Two) are deliberately NOT touched by the preset. Known limitation: the code-mode API projection covers eager tools only, so a defer-heavy minimal agent projects a near-empty code_search surface (documented in the tools guide). | packages/agent/src/types.ts:235 |
sensitivity? | readonly | Sensitivity | - | packages/agent/src/types.ts:422 |
sessionId? | readonly | string | - | packages/agent/src/types.ts:471 |
skills? | readonly | SkillsRegistryLike | - | packages/agent/src/types.ts:178 |
stopWhen? | readonly | StopCondition | - | packages/agent/src/types.ts:259 |
toolChoice? | readonly | ToolChoice | - | packages/agent/src/types.ts:260 |
toolInvocation? | readonly | "direct" | "code-mode" | How the model invokes tools (P1-2). - 'direct' (default) - the model emits one provider tool-call per tool, each result inlined into the conversation. - 'code-mode' - the agent advertises only the code_execute / code_search meta-tools; the model writes a script that calls tools in a sandbox via tools.<name>(args), and only the script's final result re-enters context (intermediate results stay inside the sandbox). Each in-script call still runs through the executor, so per-tool ACL / sanitization / truncation apply. Approval-gated tools are not reachable from code-mode (there is no durable-HITL path mid-script); call those in 'direct' mode. Default 'direct' | packages/agent/src/types.ts:279 |
toolPolicy? | readonly | ToolArgumentPolicy | Declarative tool-argument policy (D4 / Progent). Forbid-before-allow rules over tool name + validated args, evaluated by the executor on every call; default-deny sensitive tools with defaultDenySensitive. A forbid verdict blocks the call (capability_blocked). Composes on top of ruleOfTwo. See @graphorin/security/policy. | packages/agent/src/types.ts:438 |
toolPromotion? | readonly | "immediate" | "run-boundary" | When deferred-tool promotions (via tool_search) take effect (C1): - 'immediate' (default) - a promoted tool joins the catalogue on the NEXT step. Costs one provider-cache invalidation per promotion (the tools block changes), which is the standard trade for tool discovery. - 'run-boundary' - the catalogue advertised to the model is frozen for the whole run; promotions are still recorded (and persisted on RunState.promotedTools) but only join the catalogue on the next run / resume. Keeps the provider prompt cache byte-stable across every step of a run. | packages/agent/src/types.ts:374 |
toolRetry? | readonly | { backoffMs?: number; kinds?: readonly ToolErrorKind[]; maxAttempts?: number; } | C3: transparent bounded retry for transient tool failures, forwarded to the executor. Defaults (when set): maxAttempts: 3, backoffMs: 250, kinds: ['rate_limited']; retries only ever run for pure / read-only tools or tools with an idempotencyKey. | packages/agent/src/types.ts:396 |
toolRetry.backoffMs? | readonly | number | - | packages/agent/src/types.ts:398 |
toolRetry.kinds? | readonly | readonly ToolErrorKind[] | - | packages/agent/src/types.ts:399 |
toolRetry.maxAttempts? | readonly | number | - | packages/agent/src/types.ts:397 |
tools? | readonly | readonly AnyTool<TDeps>[] | - | packages/agent/src/types.ts:177 |
tracer? | readonly | Tracer | - | packages/agent/src/types.ts:409 |
userId? | readonly | string | - | packages/agent/src/types.ts:472 |
verifiers? | readonly | readonly ResponseVerifier[] | C3: rules-based verifiers that run when the model emits a terminal (no-tool-call) response. A failing verifier's feedback is appended to the transcript as a user message and the loop continues, up to maxVerifierRounds extra rounds. Verifiers are DETERMINISTIC checks (lint/test runners, format validators, exit codes) - deliberately not an evidence-free "reflect on your answer" step, which the self-correction literature shows degrades performance. | packages/agent/src/types.ts:384 |