Skip to content

AgentConfig

type AgentConfig = {
  model?:   | Model<BaseModelConfig>
     | ModelRouter
     | string;
  auxModel?:   | Model<BaseModelConfig>
     | string;
  messages?:   | Message[]
     | MessageData[];
  tools?: ToolList;
  systemPrompt?:   | SystemPrompt
     | SystemPromptData;
  appState?: Record<string, JSONValue>;
  modelState?: Record<string, JSONValue>;
  printer?: boolean;
  conversationManager?: ConversationManager;
  contextManager?: ContextManagerStrategy;
  plugins?: Plugin[];
  backgroundTasks?:   | boolean
     | BackgroundTasksConfig;
  retryStrategy?:   | RetryStrategy
     | RetryStrategy[]
     | null;
  interventions?: InterventionHandler[];
  structuredOutputSchema?: z.ZodSchema;
  sessionManager?: SessionManager;
  memoryManager?:   | MemoryManager
     | MemoryManagerConfig;
  traceAttributes?: Record<string, AttributeValue>;
  baggageAttributes?: Record<string, string>;
  name?: string;
  description?: string;
  id?: string;
  toolExecutor?:   | ConcurrentToolExecutor
     | SequentialToolExecutor
     | ToolExecutorStrategy;
  checkpointing?: boolean;
  sandbox?: Sandbox | false;
  storage?: Storage;
};

Defined in: src/agent/agent.ts:160

Configuration object for creating a new Agent.

Properties

Section titled “Properties”

model?

Section titled “model?”
model?:
  | Model<BaseModelConfig>
  | ModelRouter
  | string;

Defined in: src/agent/agent.ts:183

The model instance or router that the agent will use to make decisions. Accepts a Model, ModelRouter, or a string representing a Bedrock model ID. When a router is provided, agent.model remains its default concrete model.

Example

Section titled “Example”
// Using a string model ID (creates BedrockModel)
const agent = new Agent({
  model: 'global.anthropic.claude-sonnet-4-6'
})


// Using an explicit BedrockModel instance with configuration
const agent = new Agent({
  model: new BedrockModel({
    modelId: 'global.anthropic.claude-sonnet-4-6',
    temperature: 0.7,
    maxTokens: 2048
  })
})

auxModel?

Section titled “auxModel?”
auxModel?:
  | Model<BaseModelConfig>
  | string;

Defined in: src/agent/agent.ts:193

Model for the auxiliary side calls the SDK makes outside the main agent loop: context summarization, memory extraction, the HITL risk classifier, LLM steering, the goal judge, and the web_fetch analyst. Defaults to model, so leaving it unset changes nothing; set it (typically to a smaller, cheaper model) to move every side call off the main model at once. Each side call resolves its model as component's own model > auxModel > model. Accepts a Model or a string representing a Bedrock model ID, like model; a ModelRouter is not accepted because auxiliary calls run outside the agent loop a router attaches to.

messages?

Section titled “messages?”
messages?:
  | Message[]
  | MessageData[];

Defined in: src/agent/agent.ts:195

An initial set of messages to seed the agent’s conversation history.

tools?

Section titled “tools?”
tools?: ToolList;

Defined in: src/agent/agent.ts:201

An initial set of tools to register with the agent. Accepts nested arrays of tools at any depth, which will be flattened automatically. Agent instances are automatically wrapped as tools via Agent.asTool.

systemPrompt?

Section titled “systemPrompt?”
systemPrompt?:
  | SystemPrompt
  | SystemPromptData;

Defined in: src/agent/agent.ts:205

A system prompt which guides model behavior.

appState?

Section titled “appState?”
appState?: Record<string, JSONValue>;

Defined in: src/agent/agent.ts:207

Optional initial state values for the agent.

modelState?

Section titled “modelState?”
modelState?: Record<string, JSONValue>;

Defined in: src/agent/agent.ts:212

Optional initial model-provider state (e.g., restoring responseId from a prior session). Typically only set when hydrating from a snapshot.

printer?

Section titled “printer?”
printer?: boolean;

Defined in: src/agent/agent.ts:218

Enable automatic printing of agent output to console. When true, prints text generation, reasoning, and tool usage as they occur. Defaults to true.

conversationManager?

Section titled “conversationManager?”
conversationManager?: ConversationManager;

Defined in: src/agent/agent.ts:223

Conversation manager for handling message history and context overflow. Defaults to SlidingWindowConversationManager with windowSize of 40.

contextManager?

Section titled “contextManager?”
contextManager?: ContextManagerStrategy;

Defined in: src/agent/agent.ts:238

Context management strategy that controls how messages are compressed and offloaded.

  • "auto": Proactive truncation of tool results + summarization at 85% utilization.
  • "agentic": (Experimental) Lets the model drive context management via injected tools, with a higher truncation threshold and summarization only on overflow. This mode may change in future versions.
  • ContextManagerConfig object: Custom strategy pipeline and stash configuration.
  • ContextManager instance: Used as-is. An instance binds to one agent; construct one per Agent.
  • false: Explicitly disable context management (no compression, no offloading).

When set (except false), any co-provided conversationManager is ignored. Defaults to undefined (SlidingWindowConversationManager).

plugins?

Section titled “plugins?”
plugins?: Plugin[];

Defined in: src/agent/agent.ts:242

Plugins to register with the agent.

backgroundTasks?

Section titled “backgroundTasks?”
backgroundTasks?:
  | boolean
  | BackgroundTasksConfig;

Defined in: src/agent/agent.ts:244

Background tool execution configuration.

retryStrategy?

Section titled “retryStrategy?”
retryStrategy?:
  | RetryStrategy
  | RetryStrategy[]
  | null;

Defined in: src/agent/agent.ts:255

Retry strategy (or strategies) for failed model/tool calls.

  • Omitted: a sensible default DefaultModelRetryStrategy with exponential backoff is used.
  • Single strategy: the given strategy is used.
  • Array of strategies: all are registered, in the given order. Passing two instances of the same concrete class logs a warning — they will collide on plugin.name when the plugin registry initializes.
  • null or []: retries are explicitly disabled; failures propagate to the caller.

interventions?

Section titled “interventions?”
interventions?: InterventionHandler[];

Defined in: src/agent/agent.ts:259

Intervention handlers evaluated in registration order at each lifecycle point.

structuredOutputSchema?

Section titled “structuredOutputSchema?”
structuredOutputSchema?: z.ZodSchema;

Defined in: src/agent/agent.ts:263

Zod schema for structured output validation.

sessionManager?

Section titled “sessionManager?”
sessionManager?: SessionManager;

Defined in: src/agent/agent.ts:267

Session manager for saving and restoring agent sessions

memoryManager?

Section titled “memoryManager?”
memoryManager?:
  | MemoryManager
  | MemoryManagerConfig;

Defined in: src/agent/agent.ts:273

Memory manager for cross-session memory retrieval and storage. Manages one or more memory stores and exposes search/add tools. Accepts a MemoryManager instance or a MemoryManagerConfig object (auto-wrapped).

traceAttributes?

Section titled “traceAttributes?”
traceAttributes?: Record<string, AttributeValue>;

Defined in: src/agent/agent.ts:279

Custom trace attributes to include in all spans. These attributes are merged with standard attributes in telemetry spans. Telemetry must be enabled globally via telemetry.setupTracer() for these to take effect.

baggageAttributes?

Section titled “baggageAttributes?”
baggageAttributes?: Record<string, string>;

Defined in: src/agent/agent.ts:284

OpenTelemetry baggage entries attached to the context for the whole invocation. Baggage propagates to downstream services via the W3C baggage header.

name?

Section titled “name?”
name?: string;

Defined in: src/agent/agent.ts:288

Optional name for the agent. Defaults to “Strands Agent”.

description?

Section titled “description?”
description?: string;

Defined in: src/agent/agent.ts:292

Optional description of what the agent does.

id?

Section titled “id?”
id?: string;

Defined in: src/agent/agent.ts:296

Optional unique identifier for the agent. Defaults to “agent”.

toolExecutor?

Section titled “toolExecutor?”
toolExecutor?:
  | ConcurrentToolExecutor
  | SequentialToolExecutor
  | ToolExecutorStrategy;

Defined in: src/agent/agent.ts:304

Executor for tool calls from a single assistant turn.

Accepts a ConcurrentToolExecutor, a SequentialToolExecutor, or the corresponding ToolExecutorStrategy string shorthand. Defaults to concurrent execution.

checkpointing?

Section titled “checkpointing?”
checkpointing?: boolean;

Defined in: src/agent/agent.ts:317

Experimental

When true, the agent loop pauses at cycle boundaries (afterModel, afterTools) and returns stopReason: 'checkpoint' with a populated checkpoint field. Resume by passing the checkpoint back as { checkpointResume: { checkpoint: ... } }.

The SDK does not capture conversation state in the checkpoint; pair with a SessionManager for cross-process state continuity. Defaults to false. See the experimental checkpoint module.

sandbox?

Section titled “sandbox?”
sandbox?: Sandbox | false;

Defined in: src/agent/agent.ts:331

Execution environment for running commands, code, and file operations. When provided, sandbox-aware tools route operations through it.

Two distinct intents, even though they resolve to the same host execution in Node today:

  • Omitted: use the environment’s default sandbox (host execution in Node). This default is the slot reserved for richer behavior later.
  • false: explicitly opt out of a managed sandbox and run on the host.

Keep false distinct from omitting so the opt-out stays stable even if the default changes.

storage?

Section titled “storage?”
storage?: Storage;

Defined in: src/agent/agent.ts:341

Default storage backend for agent subsystems.

When provided, subsystems that do not have their own explicit storage (e.g., SessionManager, ContextManager) resolve from this value. Each subsystem auto-namespaces under its own prefix to avoid key collisions. Storage specified directly on a subsystem always takes precedence over this agent-level default.