Interface: AgentOptions

Generated from the public TypeScript API.

Constructor options for the ergonomic Agent facade.

With no connection options, Agent uses one process-global local server with isolated:true, 127.0.0.1, an ephemeral port, a 30-second startup timeout, automatic process cleanup, disabled LSP/formatters/title agent, no setting sources, and question, todowrite, and skill hidden. Supplying a field replaces its default; settingSources restores selected discovery and disallowedTools: [] restores the hidden tools. Supplying an allowedTools list drops the facade deny defaults. Re-enabling question without a user-input path can hang a headless run. Custom tools run in the caller process and are model-visible as sdk_<sanitized-name>.

Isolation protects config, credentials, and state discovery. It is not an operating-system, filesystem, process, tool, or network sandbox.

​

Example

import { Agent } from "cognitio-agent-sdk"

const agent = new Agent({ model: "anthropic/claude-sonnet-4-5", spawn: {} })
try {
  const result = await agent.run("Summarize this repository.")
  console.log(result.text)
} finally {
  await agent.close() // explicit spawn options give this Agent its own runtime
}

​

Extends

• RuntimeConfig

​

Extended by

• QueryOptions

​

Properties

​

agents?

optional agents?: Record<string, AgentDefinition>;

Session-scoped helper and subagent definitions, keyed by name.

​

Inherited from

RuntimeConfig.agents

---

​

allowedTools?

optional allowedTools?: string[];

Nonempty tool allowlist, including scoped expressions such as bash(npm:). An empty array adds no allowlist restriction; use disallowedTools: [""] to hide ordinary tools. Matching grants can bypass the permission callback.

​

Inherited from

RuntimeConfig.allowedTools

---

​

appendSystemPrompt?

optional appendSystemPrompt?: string;

Append application instructions after the selected base system prompt.

​

Inherited from

RuntimeConfig.appendSystemPrompt

---

​

autoPermissionClassifierModel?

optional autoPermissionClassifierModel?: ModelId;

Provider/model used to classify unresolved permissions in auto mode.

​

Inherited from

RuntimeConfig.autoPermissionClassifierModel

---

​

backgroundTaskPolicy?

optional backgroundTaskPolicy?: object;

V2 awaits tasks within the current turn. Detached durable jobs are outside this release.

​

mode

mode: "foreground";

​

Inherited from

RuntimeConfig.backgroundTaskPolicy

---

​

baseUrl?

optional baseUrl?: string;

Attach to an existing server; mutually exclusive with spawn and client.

---

​

canUseTool?

optional canUseTool?: false | CanUseToolCallback;

Answer unresolved tool approval requests. Explicit allow rules can approve a tool before this callback runs. Set false to disable a prior callback on resume.

​

Inherited from

RuntimeConfig.canUseTool

---

​

checkpointing?

optional checkpointing?: CheckpointingConfig;

Fine-grained file checkpoint policy.

​

Inherited from

RuntimeConfig.checkpointing

---

​

client?

optional client?: AgentClient;

Borrowed low-level client. Agent and shutdown() never close it.

---

​

commands?

optional commands?: CommandDefinition[];

Programmatic commands invoked by Session.command(name, arguments).

​

Inherited from

RuntimeConfig.commands

---

​

compaction?

optional compaction?: object;

Per-session automatic compaction and summary formatting.

​

auto?

optional auto?: boolean;

​

includeFiles?

optional includeFiles?: boolean;

​

Inherited from

RuntimeConfig.compaction

---

​

control?

optional control?: ControlOptions;

Control-channel tuning for a dedicated client.

---

​

cwd?

optional cwd?: string;

Session working directory.

---

​

deleteSessionsOnClose?

optional deleteSessionsOnClose?: boolean;

Delete sessions created or forked by this Agent on close. Resumed sessions are retained. Defaults to false.

---

​

directory?

optional directory?: string;

Alias for cwd; the two must match when both are supplied.

---

​

disallowedTools?

optional disallowedTools?: string[];

Tool denylist. [”*”] disables tool execution, including the runtime’s StructuredOutput tool. Use deterministic deny rules for operations that must never be approved.

​

Inherited from

RuntimeConfig.disallowedTools

---

​

effort?

optional effort?: "high" | "medium" | "low" | "max";

Provider-specific reasoning effort; unsupported combinations are rejected.

​

Inherited from

RuntimeConfig.effort

---

​

enableFileCheckpointing?

optional enableFileCheckpointing?: boolean;

Enable automatic file checkpointing. Requires a Git-backed workspace with runtime snapshots enabled.

​

Inherited from

RuntimeConfig.enableFileCheckpointing

---

​

enableToolSearch?

optional enableToolSearch?: boolean | "always" | "auto" | "never";

Control deferred tool discovery. Directly loaded tools remain governed by normal tool policy.

​

Inherited from

RuntimeConfig.enableToolSearch

---

​

headers?

optional headers?: Record<string, string>;

Remote runtime request headers, including Authorization. Requires baseUrl; incompatible with client or spawn.

---

​

hooks?

optional hooks?: HookRegistration;

Callbacks keyed by lifecycle event. Callbacks remain local and must be rebound after restarting the application. An empty object clears prior hooks on resume.

​

Inherited from

RuntimeConfig.hooks

---

​

includeEnvironment?

optional includeEnvironment?: boolean;

Include working directory and platform context in the model’s system prompt.

​

Inherited from

RuntimeConfig.includeEnvironment

---

​

instructions?

optional instructions?: string;

Full custom system prompt (sugar for a custom systemPrompt). Cannot be combined with systemPrompt.

​

Inherited from

RuntimeConfig.instructions

---

​

maxBudgetUsd?

optional maxBudgetUsd?: number;

Positive estimated USD budget; a reached limit ends with error_max_budget. Provider accounting is authoritative.

​

Inherited from

RuntimeConfig.maxBudgetUsd

---

​

maxTurns?

optional maxTurns?: number;

Positive maximum number of assistant turns before error_max_turns.

​

Inherited from

RuntimeConfig.maxTurns

---

​

model?

optional model?: ModelId;

Provider/model identifier used for the main agent turn.

​

Inherited from

RuntimeConfig.model

---

​

outputFormat?

optional outputFormat?: OutputFormatSpec<unknown>;

Expected structured JSON output schema and bounded schema retry policy.

​

Inherited from

RuntimeConfig.outputFormat

---

​

permission?

optional permission?: PermissionRuleset;

Server permission rules, distinct from runtime permissionMode.

---

​

permissionMode?

optional permissionMode?: PermissionMode;

Approval policy for unresolved tool requests. This does not create an OS sandbox.

​

Inherited from

RuntimeConfig.permissionMode

---

​

plugins?

optional plugins?: PluginSpec[];

Inline plugin bundles or local Claude-format plugin directories.

​

Inherited from

RuntimeConfig.plugins

---

​

sdkMcpServers?

optional sdkMcpServers?: RuntimeMcpServer[];

SDK-hosted or external MCP descriptors. An explicit empty array clears prior MCP registrations on resume.

​

Inherited from

RuntimeConfig.sdkMcpServers

---

​

settingSources?

optional settingSources?: ("user" | "local" | "project")[];

Instruction/config resource sources to load. SDK sessions default to an empty array.

​

Inherited from

RuntimeConfig.settingSources

---

​

skills?

optional skills?: SkillDefinition[];

Programmatic reusable skill descriptions and content.

​

Inherited from

RuntimeConfig.skills

---

​

spawn?

optional spawn?: SpawnOptions;

Dedicated local-server options.

Defined scalar values replace facade defaults. config is merged by top-level key and, under agent, by agent name; a named agent’s own object replaces wholesale, so agent: { title: {…} } drops the facade’s title.disable and restores the per-session title model call. Explicit false, "", and [] values are preserved.

---

​

systemPrompt?

optional systemPrompt?: SystemPromptSpec;

Replace the base prompt with a string/custom prompt, or explicitly select the coding preset.

​

Inherited from

RuntimeConfig.systemPrompt

---

​

thinkingConfig?

optional thinkingConfig?: ThinkingConfig;

Provider reasoning configuration; unsupported model/provider combinations fail explicitly.

​

Inherited from

RuntimeConfig.thinkingConfig

---

​

title?

optional title?: string;

Explicit server-session title.

---

​

tools?

optional tools?: ToolDefinition[];

Direct SDK tools, exposed as sdk_<sanitized-name>.

They execute in the caller process rather than the isolated server.

---

​

workspaceId?

optional workspaceId?: string;

Workspace id for a dedicated client.