> ## Documentation Index
> Fetch the complete documentation index at: https://cognitio-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```ts theme={null}
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`](RuntimeConfig)

## Extended by

* [`QueryOptions`](QueryOptions)

## Properties

### agents?

```ts theme={null}
optional agents?: Record<string, AgentDefinition>;
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`agents`](RuntimeConfig#agents)

***

### allowedTools?

```ts theme={null}
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`](RuntimeConfig).[`allowedTools`](RuntimeConfig#allowedtools)

***

### appendSystemPrompt?

```ts theme={null}
optional appendSystemPrompt?: string;
```

Append application instructions after the selected base system prompt.

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`appendSystemPrompt`](RuntimeConfig#appendsystemprompt)

***

### autoPermissionClassifierModel?

```ts theme={null}
optional autoPermissionClassifierModel?: ModelId;
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`autoPermissionClassifierModel`](RuntimeConfig#autopermissionclassifiermodel)

***

### backgroundTaskPolicy?

```ts theme={null}
optional backgroundTaskPolicy?: object;
```

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

#### mode

```ts theme={null}
mode: "foreground";
```

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`backgroundTaskPolicy`](RuntimeConfig#backgroundtaskpolicy)

***

### baseUrl?

```ts theme={null}
optional baseUrl?: string;
```

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

***

### canUseTool?

```ts theme={null}
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`](RuntimeConfig).[`canUseTool`](RuntimeConfig#canusetool)

***

### checkpointing?

```ts theme={null}
optional checkpointing?: CheckpointingConfig;
```

Fine-grained file checkpoint policy.

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`checkpointing`](RuntimeConfig#checkpointing)

***

### client?

```ts theme={null}
optional client?: AgentClient;
```

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

***

### commands?

```ts theme={null}
optional commands?: CommandDefinition[];
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`commands`](RuntimeConfig#commands)

***

### compaction?

```ts theme={null}
optional compaction?: object;
```

Per-session automatic compaction and summary formatting.

#### auto?

```ts theme={null}
optional auto?: boolean;
```

#### includeFiles?

```ts theme={null}
optional includeFiles?: boolean;
```

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`compaction`](RuntimeConfig#compaction)

***

### control?

```ts theme={null}
optional control?: ControlOptions;
```

Control-channel tuning for a dedicated client.

***

### cwd?

```ts theme={null}
optional cwd?: string;
```

Session working directory.

***

### deleteSessionsOnClose?

```ts theme={null}
optional deleteSessionsOnClose?: boolean;
```

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

***

### directory?

```ts theme={null}
optional directory?: string;
```

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

***

### disallowedTools?

```ts theme={null}
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`](RuntimeConfig).[`disallowedTools`](RuntimeConfig#disallowedtools)

***

### effort?

```ts theme={null}
optional effort?: "high" | "medium" | "low" | "max";
```

Provider-specific reasoning effort; unsupported combinations are rejected.

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`effort`](RuntimeConfig#effort)

***

### enableFileCheckpointing?

```ts theme={null}
optional enableFileCheckpointing?: boolean;
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`enableFileCheckpointing`](RuntimeConfig#enablefilecheckpointing)

***

### enableToolSearch?

```ts theme={null}
optional enableToolSearch?: boolean | "always" | "auto" | "never";
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`enableToolSearch`](RuntimeConfig#enabletoolsearch)

***

### headers?

```ts theme={null}
optional headers?: Record<string, string>;
```

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

***

### hooks?

```ts theme={null}
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`](RuntimeConfig).[`hooks`](RuntimeConfig#hooks)

***

### includeEnvironment?

```ts theme={null}
optional includeEnvironment?: boolean;
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`includeEnvironment`](RuntimeConfig#includeenvironment)

***

### instructions?

```ts theme={null}
optional instructions?: string;
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`instructions`](RuntimeConfig#instructions)

***

### maxBudgetUsd?

```ts theme={null}
optional maxBudgetUsd?: number;
```

Positive estimated USD budget; a reached limit ends with error\_max\_budget. Provider accounting is authoritative.

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`maxBudgetUsd`](RuntimeConfig#maxbudgetusd)

***

### maxTurns?

```ts theme={null}
optional maxTurns?: number;
```

Positive maximum number of assistant turns before error\_max\_turns.

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`maxTurns`](RuntimeConfig#maxturns)

***

### model?

```ts theme={null}
optional model?: ModelId;
```

Provider/model identifier used for the main agent turn.

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`model`](RuntimeConfig#model)

***

### outputFormat?

```ts theme={null}
optional outputFormat?: OutputFormatSpec<unknown>;
```

Expected structured JSON output schema and bounded schema retry policy.

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`outputFormat`](RuntimeConfig#outputformat)

***

### permission?

```ts theme={null}
optional permission?: PermissionRuleset;
```

Server permission rules, distinct from runtime `permissionMode`.

***

### permissionMode?

```ts theme={null}
optional permissionMode?: PermissionMode;
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`permissionMode`](RuntimeConfig#permissionmode)

***

### plugins?

```ts theme={null}
optional plugins?: PluginSpec[];
```

Inline plugin bundles or local Claude-format plugin directories.

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`plugins`](RuntimeConfig#plugins)

***

### sdkMcpServers?

```ts theme={null}
optional sdkMcpServers?: RuntimeMcpServer[];
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`sdkMcpServers`](RuntimeConfig#sdkmcpservers)

***

### settingSources?

```ts theme={null}
optional settingSources?: ("user" | "local" | "project")[];
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`settingSources`](RuntimeConfig#settingsources)

***

### skills?

```ts theme={null}
optional skills?: SkillDefinition[];
```

Programmatic reusable skill descriptions and content.

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`skills`](RuntimeConfig#skills)

***

### spawn?

```ts theme={null}
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?

```ts theme={null}
optional systemPrompt?: SystemPromptSpec;
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`systemPrompt`](RuntimeConfig#systemprompt)

***

### thinkingConfig?

```ts theme={null}
optional thinkingConfig?: ThinkingConfig;
```

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

#### Inherited from

[`RuntimeConfig`](RuntimeConfig).[`thinkingConfig`](RuntimeConfig#thinkingconfig)

***

### title?

```ts theme={null}
optional title?: string;
```

Explicit server-session title.

***

### tools?

```ts theme={null}
optional tools?: ToolDefinition[];
```

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

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

***

### workspaceId?

```ts theme={null}
optional workspaceId?: string;
```

Workspace id for a dedicated client.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.