Graphorin API reference v0.15.1
Graphorin API reference / @graphorin/agent / / AgentConfig
Interface: AgentConfig<TDeps, TOutput>
Defined in: packages/agent/src/types.ts:174
Stable
The full options object accepted by createAgent.
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. 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:221 |
cachePolicy? | readonly | ProviderCachePolicy | Opt-in prompt-cache breakpoint policy, 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:367 |
capability? | readonly | "read-only" | Agent-default capability restriction. '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:437 |
causalityMonitor? | readonly | CausalityMonitorConfig | - | packages/agent/src/types.ts:317 |
checkpointPolicy? | readonly | "keep" | "delete-on-terminal" | What happens to the run's checkpoint thread when the run reaches a terminal status. '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:428 |
checkpointStore? | readonly | CheckpointStore | - | packages/agent/src/types.ts:417 |
codeMode? | readonly | { limits?: CodeExecuteLimits; run?: CodeModeRunner; } | 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:301 |
codeMode.limits? | readonly | CodeExecuteLimits | - | packages/agent/src/types.ts:303 |
codeMode.run? | readonly | CodeModeRunner | - | packages/agent/src/types.ts:302 |
dataFlowPolicy? | readonly | DataFlowPolicyConfig | Provenance / taint-based data-flow policy (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:346 |
deps? | readonly | TDeps | - | packages/agent/src/types.ts:480 |
fallbackModels? | readonly | readonly ModelSpec[] | - | packages/agent/src/types.ts:305 |
fallbackPolicy? | readonly | AgentFallbackPolicy | - | packages/agent/src/types.ts:306 |
guardrails? | readonly | { input?: readonly InputGuardrail<string>[]; output?: readonly OutputGuardrail<TOutput>[]; } | Deterministic checks run by the loop (canonical contract is @graphorin/security's GuardrailDefinition). - 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:263 |
guardrails.input? | readonly | readonly InputGuardrail<string>[] | - | packages/agent/src/types.ts:264 |
guardrails.output? | readonly | readonly OutputGuardrail<TOutput>[] | - | packages/agent/src/types.ts:265 |
handoffs? | readonly | readonly HandoffEntry<TDeps>[] | - | packages/agent/src/types.ts:244 |
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:183 |
maxParallelTools? | readonly | number | - | packages/agent/src/types.ts:270 |
maxVerifierRounds? | readonly | number | Cap on verifier-triggered continuation rounds per run. Default 1 | packages/agent/src/types.ts:396 |
memory? | readonly | Memory | - | packages/agent/src/types.ts:187 |
mergeGuard? | readonly | MergeGuardConfig | Sideways-injection merge guard for agent.fanOut 'judge-merge': 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:325 |
modelTierMap? | readonly | Partial<Record<ModelHint, ModelSpec>> | - | packages/agent/src/types.ts:308 |
name | readonly | string | - | packages/agent/src/types.ts:175 |
outputType? | readonly | OutputSpec<TOutput> | - | packages/agent/src/types.ts:245 |
permissionHook? | readonly | PermissionHook | Pre-tool permission hook: one caller-supplied decision point (`allow | deny |
plan? | readonly | boolean | Register the 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:477 |
preferredModel? | readonly | | ModelSpec | ModelHint | - | packages/agent/src/types.ts:307 |
prepareStep? | readonly | PrepareStepHook<TDeps> | - | packages/agent/src/types.ts:269 |
procedureInduction? | readonly | { auto?: boolean; minCostUsd?: number; minSteps?: number; minToolCalls?: number; } | Opt-in auto-induction: 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 configured 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:200 |
procedureInduction.auto? | readonly | boolean | Master switch. Default false. | packages/agent/src/types.ts:202 |
procedureInduction.minCostUsd? | readonly | number | Minimum observed run cost in USD (0 = ignore cost). Default 0. | packages/agent/src/types.ts:208 |
procedureInduction.minSteps? | readonly | number | Minimum completed steps. Default 3. | packages/agent/src/types.ts:204 |
procedureInduction.minToolCalls? | readonly | number | Minimum total tool calls across steps. Default 3. | packages/agent/src/types.ts:206 |
provider | readonly | Provider | - | packages/agent/src/types.ts:184 |
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. | packages/agent/src/types.ts:316 |
recordProviderResponses? | readonly | boolean | 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:415 |
resultReaders? | readonly | readonly ResultReader[] | Additional result-handle readers, 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:355 |
ruleOfTwo? | readonly | RuleOfTwoProfile | Rule-of-Two capability profile. 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:454 |
scaffold? | readonly | "full" | "minimal" | Context-scaffolding preset. 'full' (default) is exactly the long-standing 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:243 |
sensitivity? | readonly | Sensitivity | - | packages/agent/src/types.ts:429 |
sessionId? | readonly | string | - | packages/agent/src/types.ts:478 |
skills? | readonly | SkillsRegistryLike | - | packages/agent/src/types.ts:186 |
stopWhen? | readonly | StopCondition | - | packages/agent/src/types.ts:267 |
toolChoice? | readonly | ToolChoice | - | packages/agent/src/types.ts:268 |
toolInvocation? | readonly | "direct" | "code-mode" | How the model invokes tools. - '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:287 |
toolPolicy? | readonly | ToolArgumentPolicy | Declarative tool-argument policy (Progent-style). 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:445 |
toolPromotion? | readonly | "immediate" | "run-boundary" | When deferred-tool promotions (via tool_search) take effect: - '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:381 |
toolRetry? | readonly | { backoffMs?: number; kinds?: readonly ToolErrorKind[]; maxAttempts?: number; } | 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:403 |
toolRetry.backoffMs? | readonly | number | - | packages/agent/src/types.ts:405 |
toolRetry.kinds? | readonly | readonly ToolErrorKind[] | - | packages/agent/src/types.ts:406 |
toolRetry.maxAttempts? | readonly | number | - | packages/agent/src/types.ts:404 |
tools? | readonly | readonly AnyTool<TDeps>[] | - | packages/agent/src/types.ts:185 |
tracer? | readonly | Tracer | - | packages/agent/src/types.ts:416 |
userId? | readonly | string | - | packages/agent/src/types.ts:479 |
verifiers? | readonly | readonly ResponseVerifier[] | 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:391 |