Graphorin API reference v0.7.0
Graphorin API reference / @graphorin/agent / / AgentConfig
Interface: AgentConfig<TDeps, TOutput>
Defined in: packages/agent/src/types.ts:154
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:179 |
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:287 |
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:357 |
causalityMonitor? | readonly | CausalityMonitorConfig | - | packages/agent/src/types.ts:237 |
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:348 |
checkpointStore? | readonly | CheckpointStore | - | packages/agent/src/types.ts:337 |
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:266 |
deps? | readonly | TDeps | - | packages/agent/src/types.ts:384 |
fallbackModels? | readonly | readonly ModelSpec[] | - | packages/agent/src/types.ts:224 |
fallbackPolicy? | readonly | AgentFallbackPolicy | - | packages/agent/src/types.ts:225 |
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:199 |
guardrails.input? | readonly | readonly InputGuardrail<string>[] | - | packages/agent/src/types.ts:200 |
guardrails.output? | readonly | readonly OutputGuardrail<TOutput>[] | - | packages/agent/src/types.ts:201 |
handoffs? | readonly | readonly HandoffEntry<TDeps>[] | - | packages/agent/src/types.ts:180 |
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:163 |
maxParallelTools? | readonly | number | - | packages/agent/src/types.ts:206 |
maxVerifierRounds? | readonly | number | Cap on verifier-triggered continuation rounds per run (C3). Default 1 | packages/agent/src/types.ts:316 |
memory? | readonly | Memory | - | packages/agent/src/types.ts:167 |
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:245 |
modelTierMap? | readonly | Partial<Record<ModelHint, ModelSpec>> | - | packages/agent/src/types.ts:227 |
name | readonly | string | - | packages/agent/src/types.ts:155 |
outputType? | readonly | OutputSpec<TOutput> | - | packages/agent/src/types.ts:181 |
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:381 |
preferredModel? | readonly | | ModelSpec | ModelHint | - | packages/agent/src/types.ts:226 |
prepareStep? | readonly | PrepareStepHook<TDeps> | - | packages/agent/src/types.ts:205 |
provider | readonly | Provider | - | packages/agent/src/types.ts:164 |
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:236 |
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:335 |
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:275 |
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:374 |
sensitivity? | readonly | Sensitivity | - | packages/agent/src/types.ts:349 |
sessionId? | readonly | string | - | packages/agent/src/types.ts:382 |
skills? | readonly | SkillsRegistryLike | - | packages/agent/src/types.ts:166 |
stopWhen? | readonly | StopCondition | - | packages/agent/src/types.ts:203 |
toolChoice? | readonly | ToolChoice | - | packages/agent/src/types.ts:204 |
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:223 |
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:365 |
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:301 |
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:323 |
toolRetry.backoffMs? | readonly | number | - | packages/agent/src/types.ts:325 |
toolRetry.kinds? | readonly | readonly ToolErrorKind[] | - | packages/agent/src/types.ts:326 |
toolRetry.maxAttempts? | readonly | number | - | packages/agent/src/types.ts:324 |
tools? | readonly | readonly AnyTool<TDeps>[] | - | packages/agent/src/types.ts:165 |
tracer? | readonly | Tracer | - | packages/agent/src/types.ts:336 |
userId? | readonly | string | - | packages/agent/src/types.ts:383 |
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:311 |