AgentConfig

type AgentConfig = {
  model?:   | Model<BaseModelConfig>
     | ModelRouter
     | 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>;
  name?: string;
  description?: string;
  id?: string;
  toolExecutor?:   | ConcurrentToolExecutor
     | SequentialToolExecutor
     | ToolExecutorStrategy;
  checkpointing?: boolean;
  sandbox?: Sandbox | false;
  storage?: Storage;
};

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

Configuration object for creating a new Agent.

Properties

model?

optional model?:
  | Model<BaseModelConfig>
  | ModelRouter
  | string;

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

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

// 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
  })
})

messages?

optional messages?:
  | Message[]
  | MessageData[];

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

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

tools?

optional tools?: ToolList;

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

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?

optional systemPrompt?:
  | SystemPrompt
  | SystemPromptData;

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

A system prompt which guides model behavior.

appState?

optional appState?: Record<string, JSONValue>;

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

Optional initial state values for the agent.

modelState?

optional modelState?: Record<string, JSONValue>;

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

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

printer?

optional printer?: boolean;

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

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

conversationManager?

optional conversationManager?: ConversationManager;

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

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

contextManager?

optional contextManager?: ContextManagerStrategy;

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

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

"auto": SummarizingConversationManager with proactive compression + ContextOffloader.
"agentic": (Experimental) Lets the model drive context management via injected tools. This mode may change in future versions.
ContextManager instance: Strategy-driven offloading with overflow recovery.
false: Explicitly disable context management (no compression, no offloading).

When a ContextManager instance is provided, any co-provided conversationManager is ignored. Defaults to undefined (SlidingWindowConversationManager, no offloader).

Remarks

The offloader uses in-memory storage by default. When an agent-level storage is provided, the offloader uses that instead. Alternatively, provide an explicit ContextOffloader with its own storage via the plugins parameter.

plugins?

optional plugins?: Plugin[];

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

Plugins to register with the agent.

backgroundTasks?

optional backgroundTasks?:
  | boolean
  | BackgroundTasksConfig;

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

Background tool execution configuration.

retryStrategy?

optional retryStrategy?:
  | RetryStrategy
  | RetryStrategy[]
  | null;

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

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?

optional interventions?: InterventionHandler[];

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

Intervention handlers evaluated in registration order at each lifecycle point.

structuredOutputSchema?

optional structuredOutputSchema?: z.ZodSchema;

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

Zod schema for structured output validation.

sessionManager?

optional sessionManager?: SessionManager;

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

Session manager for saving and restoring agent sessions

memoryManager?

optional memoryManager?:
  | MemoryManager
  | MemoryManagerConfig;

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

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?

optional traceAttributes?: Record<string, AttributeValue>;

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

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.

name?

optional name?: string;

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

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

description?

optional description?: string;

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

Optional description of what the agent does.

id?

optional id?: string;

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

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

toolExecutor?

optional toolExecutor?:
  | ConcurrentToolExecutor
  | SequentialToolExecutor
  | ToolExecutorStrategy;

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

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?

optional checkpointing?: boolean;

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

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?

optional sandbox?: Sandbox | false;

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

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?

optional storage?: Storage;

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

Default storage backend for agent subsystems.

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