@strands-agents/sdk 0.4.0 → 0.6.0

package/dist/src/agent/agent.d.ts

@@ -1,11 +1,18 @@
-import { AgentResult, type AgentStreamEvent, type ContentBlock, type ContentBlockData, type JSONValue, McpClient, Message, type MessageData, type SystemPrompt, type SystemPromptData, type Tool } from '../index.js';
-import type { BaseModelConfig, Model } from '../models/model.js';
+import { AgentResult, type AgentStreamEvent } from '../types/agent.js';
+import { type ContentBlock, type ContentBlockData, Message, type MessageData, type SystemPrompt, type SystemPromptData } from '../types/messages.js';
+import type { JSONValue } from '../types/json.js';
+import { McpClient } from '../mcp.js';
+import { type Tool } from '../tools/tool.js';
+import { Model } from '../models/model.js';
+import type { BaseModelConfig } from '../models/model.js';
 import { ToolRegistry } from '../registry/tool-registry.js';
-import { AgentState } from './state.js';
+import { AppState } from '../app-state.js';
 import type { AgentData } from '../types/agent.js';
 import type { HookProvider } from '../hooks/types.js';
 import { HookRegistryImplementation } from '../hooks/registry.js';
 import type { z } from 'zod';
+import type { SessionManager } from '../session/session-manager.js';
+import type { AttributeValue } from '@opentelemetry/api';
 /**
  * Recursive type definition for nested tool arrays.
  * Allows tools to be organized in nested arrays of any depth.
@@ -71,6 +78,28 @@ export type AgentConfig = {
      * Zod schema for structured output validation.
      */
     structuredOutputSchema?: z.ZodSchema;
+    /**
+     * Session manager for saving and restoring agent sessions
+     */
+    sessionManager?: SessionManager;
+    /**
+     * 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.
+     */
+    traceAttributes?: Record<string, AttributeValue>;
+    /**
+     * Optional name for the agent. Defaults to "Strands Agent".
+     */
+    name?: string;
+    /**
+     * Optional description of what the agent does.
+     */
+    description?: string;
+    /**
+     * Optional unique identifier for the agent. Defaults to "default".
+     */
+    agentId?: string;
 };
 /**
  * Arguments for invoking an agent.
@@ -81,6 +110,15 @@ export type AgentConfig = {
  * - `Message[]` | `MessageData[]` - Array of messages (appends all to conversation)
  */
 export type InvokeArgs = string | ContentBlock[] | ContentBlockData[] | Message[] | MessageData[];
+/**
+ * Options for a single agent invocation.
+ */
+export interface InvokeOptions {
+    /**
+     * Zod schema for structured output validation, overriding the constructor-provided schema for this invocation only.
+     */
+    structuredOutputSchema?: z.ZodSchema;
+}
 /**
  * Orchestrates the interaction between a model, a set of tools, and MCP clients.
  * The Agent is responsible for managing the lifecycle of tools and clients
@@ -92,10 +130,10 @@ export declare class Agent implements AgentData {
      */
     readonly messages: Message[];
     /**
-     * Agent state storage accessible to tools and application logic.
+     * App state storage accessible to tools and application logic.
      * State is not passed to the model during inference.
      */
-    readonly state: AgentState;
+    readonly state: AppState;
     /**
      * Conversation manager for handling message history and context overflow.
      */
@@ -113,12 +151,28 @@ export declare class Agent implements AgentData {
      * The system prompt to pass to the model provider.
      */
     systemPrompt?: SystemPrompt;
+    /**
+     * The name of the agent.
+     */
+    readonly name: string;
+    /**
+     * The unique identifier of the agent instance.
+     */
+    readonly agentId: string;
+    /**
+     * Optional description of what the agent does.
+     */
+    readonly description?: string;
     private _toolRegistry;
     private _mcpClients;
     private _initialized;
     private _isInvoking;
     private _printer?;
     private _structuredOutputSchema?;
+    /** Tracer instance for creating and managing OpenTelemetry spans. */
+    private _tracer;
+    /** Meter instance for accumulating loop metrics during invocation. */
+    private _meter;
     /**
      * Creates an instance of the Agent.
      * @param config - The configuration for the agent.
@@ -146,6 +200,7 @@ export declare class Agent implements AgentData {
      * streaming events.
      *
      * @param args - Arguments for invoking the agent
+     * @param options - Optional per-invocation options
      * @returns Promise that resolves to the final AgentResult
      *
      * @example
@@ -155,7 +210,7 @@ export declare class Agent implements AgentData {
      * console.log(result.lastMessage) // Agent's response
      * ```
      */
-    invoke(args: InvokeArgs): Promise<AgentResult>;
+    invoke(args: InvokeArgs, options?: InvokeOptions): Promise<AgentResult>;
     /**
      * Streams the agent execution, yielding events and returning the final result.
      *
@@ -173,6 +228,7 @@ export declare class Agent implements AgentData {
      * with valid toolResponses
      *
      * @param args - Arguments for invoking the agent
+     * @param options - Optional per-invocation options
      * @returns Async generator that yields AgentStreamEvent objects and returns AgentResult
      *
      * @example
@@ -185,12 +241,13 @@ export declare class Agent implements AgentData {
      * // Messages array is mutated in place and contains the full conversation
      * ```
      */
-    stream(args: InvokeArgs): AsyncGenerator<AgentStreamEvent, AgentResult, undefined>;
+    stream(args: InvokeArgs, options?: InvokeOptions): AsyncGenerator<AgentStreamEvent, AgentResult, undefined>;
     /**
      * Internal implementation of the agent streaming logic.
      * Separated to centralize printer event processing in the public stream method.
      *
      * @param args - Arguments for invoking the agent
+     * @param options - Optional per-invocation options
      * @returns Async generator that yields AgentStreamEvent objects and returns AgentResult
      */
     private _stream;
@@ -206,7 +263,7 @@ export declare class Agent implements AgentData {
      *
      * @param args - Optional arguments for invoking the model
      * @param toolChoice - Optional tool choice to force specific tool usage
-     * @returns Object containing the assistant message and stop reason
+     * @returns Object containing the assistant message, stop reason, and optional redaction message
      */
     private invokeModel;
     /**
@@ -223,7 +280,7 @@ export declare class Agent implements AgentData {
      *
      * @param messages - Messages to send to the model
      * @param streamOptions - Options for streaming
-     * @returns Object containing the assistant message and stop reason
+     * @returns StreamAggregatedResult containing message, stop reason, and optional redaction message
      */
     private _streamFromModel;
     /**
@@ -245,6 +302,19 @@ export declare class Agent implements AgentData {
      * @returns Tool result block
      */
     private executeTool;
+    /**
+     * Redacts the last message in the conversation history.
+     * Called when guardrails block user input and redaction is enabled.
+     *
+     * Follows the redaction strategy:
+     * - If the message contains at least one toolResult block, all toolResult blocks
+     *   are kept with redacted content, and all other blocks are discarded.
+     * - Otherwise, the entire content is replaced with a single text block containing
+     *   the redaction message.
+     *
+     * @param redactMessage - The redaction message to replace the content with
+     */
+    private _redactLastMessage;
     /**
      * Appends a message to the conversation history and returns the event for yielding.
      *

package/dist/src/agent/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/agent/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/agent/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEtE,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,OAAO,EACP,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAItB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,EAAE,KAAK,IAAI,EAAoB,MAAM,kBAAkB,CAAA;AAI9D,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAyC,MAAM,oBAAoB,CAAA;AAEhG,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAElD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAA;AAuBjE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAGnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAGxD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,GAAG,SAAS,GAAG,QAAQ,CAAC,EAAE,CAAA;AAEtD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,GAAG,MAAM,CAAA;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,CAAA;IACpC;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB;;OAEG;IACH,YAAY,CAAC,EAAE,YAAY,GAAG,gBAAgB,CAAA;IAC9C,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,YAAY,CAAA;IAClC;;;OAGG;IACH,KAAK,CAAC,EAAE,YAAY,EAAE,CAAA;IACtB;;OAEG;IACH,sBAAsB,CAAC,EAAE,CAAC,CAAC,SAAS,CAAA;IACpC;;OAEG;IACH,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IAChD;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,YAAY,EAAE,GAAG,gBAAgB,EAAE,GAAG,OAAO,EAAE,GAAG,WAAW,EAAE,CAAA;AAEjG;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,sBAAsB,CAAC,EAAE,CAAC,CAAC,SAAS,CAAA;CACrC;AAQD;;;;GAIG;AACH,qBAAa,KAAM,YAAW,SAAS;IACrC;;OAEG;IACH,SAAgB,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnC;;;OAGG;IACH,SAAgB,KAAK,EAAE,QAAQ,CAAA;IAC/B;;OAEG;IACH,SAAgB,mBAAmB,EAAE,YAAY,CAAA;IACjD;;;OAGG;IACH,SAAgB,KAAK,EAAE,0BAA0B,CAAA;IAEjD;;OAEG;IACI,KAAK,EAAE,KAAK,CAAA;IAEnB;;OAEG;IACI,YAAY,CAAC,EAAE,YAAY,CAAA;IAElC;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAA;IAE5B;;OAEG;IACH,SAAgB,OAAO,EAAE,MAAM,CAAA;IAE/B;;OAEG;IACH,SAAgB,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpC,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC,uBAAuB,CAAC,CAAyB;IACzD,qEAAqE;IACrE,OAAO,CAAC,OAAO,CAAQ;IACvB,sEAAsE;IACtE,OAAO,CAAC,MAAM,CAAO;IAErB;;;OAGG;gBACS,MAAM,CAAC,EAAE,WAAW;IAkDnB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBxC;;;OAGG;IACH,OAAO,CAAC,WAAW;IAenB;;OAEG;IACH,IAAI,KAAK,IAAI,IAAI,EAAE,CAElB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,YAAY,CAE/B;IAED;;;;;;;;;;;;;;;;;OAiBG;IACU,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC;IASpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACW,MAAM,CAClB,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,aAAa,GACtB,cAAc,CAAC,gBAAgB,EAAE,WAAW,EAAE,SAAS,CAAC;IAgC3D;;;;;;;OAOG;YACY,OAAO;IAuJtB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAgDvB;;;;;;OAMG;YACY,WAAW;IAuF1B;;;;;;;;;;;;;;;OAeG;YACY,gBAAgB;IAwB/B;;;;;;OAMG;YACY,YAAY;IAqC3B;;;;;;;;;OASG;YACY,WAAW;IA+G1B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,kBAAkB;IAuC1B;;;;;OAKG;IACH,OAAO,CAAC,cAAc;CAIvB"}