@agentscope-ai/agentscope 0.0.2

package/dist/agent/index.d.mts

@@ -0,0 +1,234 @@
+import { z } from 'zod';
+import { M as Msg } from '../message-CkN21KaY.mjs';
+import { b as ToolCallBlock, C as ContentBlock, c as ToolResultBlock } from '../block-VsnHrllL.mjs';
+import { C as ChatModelBase, a as ChatUsage, b as ChatResponse } from '../base-DYlBMCy_.mjs';
+import { a as ToolResponse } from '../index-BTJDlKvQ.mjs';
+import { T as Toolkit } from '../toolkit-CGEZSZPa.mjs';
+import { UserConfirmResultEvent, ExternalExecutionResultEvent, AgentEvent, EventType, ToolResultTextDeltaEvent, ToolResultBinaryDeltaEvent, ToolResultEndEvent } from '../event/index.mjs';
+import { a as ToolChoice } from '../index-CAxQAkiP.mjs';
+import { S as StorageBase } from '../base-C7jwyH4Z.mjs';
+import '../base-BOx3UzOl.mjs';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '@modelcontextprotocol/sdk/client/sse.js';
+import '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import '@modelcontextprotocol/sdk/shared/protocol.js';
+import '@modelcontextprotocol/sdk/client/stdio.js';
+
+interface ReplyOptions {
+    msgs?: Msg | Msg[];
+    event?: UserConfirmResultEvent | ExternalExecutionResultEvent;
+    structuredModel?: z.ZodObject;
+}
+interface ReasoningOptions {
+    toolChoice?: ToolChoice;
+}
+interface ActingOptions {
+    toolCall: ToolCallBlock;
+}
+interface ObserveOptions {
+    msg?: Msg | Msg[];
+}
+
+interface CompressionConfig {
+    /**
+     * Whether to enable memory compression.
+     */
+    enabled: boolean;
+    /**
+     * The token count threshold to trigger memory compression.
+     */
+    triggerThreshold: number;
+    /**
+     * The function to count the tokens of the messages in memory. If not provided, a heuristic token counting method will be used by default.
+     */
+    tokenCountFunc?: (msgs: Msg[]) => number;
+    /**
+     * The chat model used for compression. If not provided, the same model as the agent will be used by default.
+     */
+    compressionModel?: ChatModelBase;
+    /**
+     * The prompt template for memory compression. It should be designed to instruct the model to compress the input messages into a concise summary while preserving important information. If not provided, a default prompt will be used.
+     */
+    compressionPrompt?: string;
+    /**
+     * The JSON schema for the compressed summary. The model will be guided to compress the memory into a structured summary following this schema. If not provided, a default schema with a single text field will be used.
+     */
+    summarySchema?: z.ZodObject;
+    /**
+     * The number of recent messages to keep in the context without compression.
+     */
+    keepRecent?: number;
+}
+interface AgentOptions {
+    name: string;
+    sysPrompt: string;
+    model: ChatModelBase;
+    maxIters?: number;
+    toolkit?: Toolkit;
+    storage?: StorageBase;
+    compressionConfig?: CompressionConfig;
+}
+/**
+ * The unified agent class in AgentScope library.
+ */
+declare class Agent {
+    name: string;
+    model: ChatModelBase;
+    maxIters: number;
+    toolkit: Toolkit;
+    storage?: StorageBase;
+    context: Msg[];
+    private _loaded;
+    private _sysPrompt;
+    compressionConfig?: CompressionConfig;
+    replyId: string;
+    curIter: number;
+    confirmedToolCallIds: string[];
+    curSummary: string;
+    /**
+     * Initialize an agent instance with the given parameters.
+     *
+     * @param options - The agent configuration options.
+     * @param options.name - The name of the agent.
+     * @param options.sysPrompt - The system prompt for the agent.
+     * @param options.model - The chat model to use.
+     * @param options.maxIters - Maximum iterations (default: 5).
+     * @param options.memory - Memory storage (default: InMemoryMemory).
+     * @param options.toolkit - Toolkit for tools (default: Toolkit).
+     */
+    constructor(options: AgentOptions);
+    /**
+     * Load the state from the storage if storage is provided and not loaded yet.
+     */
+    loadState(): Promise<void>;
+    /**
+     * Save the state of the current reply session to storage if storage is provided.
+     */
+    saveState(): Promise<void>;
+    /**
+     * Get the system prompt of the agent.
+     *
+     * @returns The system prompt string.
+     */
+    get sysPrompt(): string;
+    /**
+     * Reply to the given message and stream agent events as they are generated.
+     *
+     * @param options - The reply options containing the incoming message.
+     * @returns An async generator that yields agent events and resolves to the final reply message.
+     */
+    replyStream(options: ReplyOptions): AsyncGenerator<AgentEvent, Msg>;
+    /**
+     * Reply to the given message, consuming all streamed events internally.
+     *
+     * @param options - The reply options containing the incoming message.
+     * @param options.msgs - The incoming message(s) to reply to.
+     * @returns A promise that resolves to the final reply message.
+     */
+    reply(options: ReplyOptions): Promise<Msg>;
+    /**
+     * Save the given content blocks into the context as a new block in the last assistant message,
+     * or create a new assistant message if the last message is not from the assistant or has a different name.
+     * @param blocks
+     * @param usage
+     */
+    protected _saveToContext(blocks: ContentBlock[], usage?: ChatUsage): void;
+    /**
+     * Get the pending tool calls that have no results yet in the context.
+     * @returns An array of pending `ToolCallBlock`s that are waiting for execution results.
+     */
+    protected _getPendingToolCalls(): ToolCallBlock[];
+    /**
+     * Get the awaiting tool calls that require user confirmation or external execution.
+     * @returns An array of `ToolCallBlock`s that are waiting for user confirmation or external execution.
+     */
+    protected _getAwaitingToolCalls(): {
+        awaitingType?: EventType.REQUIRE_USER_CONFIRM | EventType.REQUIRE_EXTERNAL_EXECUTION;
+        expectedEventType?: EventType.USER_CONFIRM_RESULT | EventType.EXTERNAL_EXECUTION_RESULT;
+        awaitingToolCalls: ToolCallBlock[];
+        preToolCalls: ToolCallBlock[];
+    };
+    /**
+     * Core reply logic without middlewares. Observes the incoming message, runs
+     * reasoning/acting iterations up to `maxIters`, and returns the final response.
+     *
+     * @param options - The reply options containing the incoming message.
+     * @returns An async generator that yields agent events and resolves to the final reply message.
+     */
+    protected _reply(options?: ReplyOptions): AsyncGenerator<AgentEvent, Msg>;
+    /**
+     * Core reasoning logic without middlewares. Calls the model with the current
+     * memory and system prompt, converts the response to agent events, and saves
+     * the resulting message to memory.
+     *
+     * @param options - The reasoning options, including tool choice strategy.
+     * @returns An async generator that yields agent events and resolves to the content blocks of the model response.
+     */
+    protected _reasoning(options: ReasoningOptions): AsyncGenerator<AgentEvent, ChatResponse>;
+    /**
+     * Core acting logic without middlewares. Executes the given tool call, streams
+     * intermediate tool result events, and saves the final tool response to memory.
+     *
+     * @param options - The acting options containing the tool call to execute.
+     * @returns An async generator that yields tool result events.
+     */
+    protected _acting(options: ActingOptions): AsyncGenerator<AgentEvent, ToolResultBlock>;
+    /**
+     * Receive external observation message(s) and save them into memory.
+     *
+     * @param options - The observe options containing the message to store.
+     * @returns A promise that resolves when the message has been saved to memory.
+     */
+    protected _observe(options: ObserveOptions): Promise<void>;
+    /**
+     * Convert a `ChatResponse` chunk into a sequence of typed agent events.
+     * Tracks message IDs across calls via the mutable `responseId` object so that
+     * start/content/end events are correctly correlated.
+     *
+     * @param responseId - Mutable object tracking IDs for the current text, thinking, and tool-call messages.
+     * @param responseId.textMessageId - ID of the in-progress text message, or `null` if not yet started.
+     * @param responseId.thinkingMessageId - ID of the in-progress thinking message, or `null` if not yet started.
+     * @param responseId.textBlockId
+     * @param responseId.thinkingBlockId
+     * @param responseId.toolCallIds - List of tool-call IDs seen so far in this response.
+     * @param chunk - The chat response chunk to convert.
+     * @returns An async generator that yields the corresponding agent events.
+     */
+    protected convertChatResponseToEvent(responseId: {
+        textBlockId: string | null;
+        thinkingBlockId: string | null;
+        toolCallIds: string[];
+    }, chunk: ChatResponse): AsyncGenerator<AgentEvent>;
+    /**
+     * Convert a `ToolResponse` into a sequence of typed agent events, followed by
+     * a final `TOOL_RESULT_END` event.
+     *
+     * @param toolCall - The original tool-use block that triggered this response.
+     * @param toolRes - The tool response containing result content blocks.
+     * @returns An async generator that yields tool result events.
+     */
+    protected convertToolResponseToEvent(toolCall: ToolCallBlock, toolRes: ToolResponse): AsyncGenerator<ToolResultTextDeltaEvent | ToolResultBinaryDeltaEvent | ToolResultEndEvent, void, unknown>;
+    /**
+     * Convert the agent instance to a JSON-serializable object.
+     * @returns An object containing the agent's name and system prompt.
+     */
+    toJSON(): Promise<{
+        replyId: string;
+        confirmedToolCallIds: string[];
+        curIter: number;
+    }>;
+    /**
+     * Split the current context into two parts: one part that needs to be compressed and another part that should be reserved based on the compression configuration. The method calculates how many recent "units" (blocks or tool call pairs) to keep uncompressed according to the `keepRecent` setting in the compression configuration, and ensures that tool calls and their corresponding results are not separated during the split.
+     * @returns An object containing the `toCompressedContext` which includes the messages that need to be compressed, and the `reservedContext` which includes the recent messages that should be kept uncompressed.
+     */
+    protected _splitContextForCompression(): {
+        toCompressedContext: Msg[];
+        reservedContext: Msg[];
+    };
+    /**
+     * Compress the agent's memory using the specified compression model (if provided) or the original model.
+     */
+    protected compressMemoryIfNeeded(): Promise<void>;
+}
+
+export { type ActingOptions, Agent, type AgentOptions, type CompressionConfig, type ReasoningOptions, type ReplyOptions };

package/dist/agent/index.d.ts

@@ -0,0 +1,234 @@
+import { z } from 'zod';
+import { M as Msg } from '../message-CzLeTlua.js';
+import { b as ToolCallBlock, C as ContentBlock, c as ToolResultBlock } from '../block-VsnHrllL.js';
+import { C as ChatModelBase, a as ChatUsage, b as ChatResponse } from '../base-Cwi4bjze.js';
+import { a as ToolResponse } from '../index-BcatlwXQ.js';
+import { T as Toolkit } from '../toolkit-CEpulFi0.js';
+import { UserConfirmResultEvent, ExternalExecutionResultEvent, AgentEvent, EventType, ToolResultTextDeltaEvent, ToolResultBinaryDeltaEvent, ToolResultEndEvent } from '../event/index.js';
+import { a as ToolChoice } from '../index-CAxQAkiP.js';
+import { S as StorageBase } from '../base-NX-knWOv.js';
+import '../base-BoIps2RL.js';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '@modelcontextprotocol/sdk/client/sse.js';
+import '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import '@modelcontextprotocol/sdk/shared/protocol.js';
+import '@modelcontextprotocol/sdk/client/stdio.js';
+
+interface ReplyOptions {
+    msgs?: Msg | Msg[];
+    event?: UserConfirmResultEvent | ExternalExecutionResultEvent;
+    structuredModel?: z.ZodObject;
+}
+interface ReasoningOptions {
+    toolChoice?: ToolChoice;
+}
+interface ActingOptions {
+    toolCall: ToolCallBlock;
+}
+interface ObserveOptions {
+    msg?: Msg | Msg[];
+}
+
+interface CompressionConfig {
+    /**
+     * Whether to enable memory compression.
+     */
+    enabled: boolean;
+    /**
+     * The token count threshold to trigger memory compression.
+     */
+    triggerThreshold: number;
+    /**
+     * The function to count the tokens of the messages in memory. If not provided, a heuristic token counting method will be used by default.
+     */
+    tokenCountFunc?: (msgs: Msg[]) => number;
+    /**
+     * The chat model used for compression. If not provided, the same model as the agent will be used by default.
+     */
+    compressionModel?: ChatModelBase;
+    /**
+     * The prompt template for memory compression. It should be designed to instruct the model to compress the input messages into a concise summary while preserving important information. If not provided, a default prompt will be used.
+     */
+    compressionPrompt?: string;
+    /**
+     * The JSON schema for the compressed summary. The model will be guided to compress the memory into a structured summary following this schema. If not provided, a default schema with a single text field will be used.
+     */
+    summarySchema?: z.ZodObject;
+    /**
+     * The number of recent messages to keep in the context without compression.
+     */
+    keepRecent?: number;
+}
+interface AgentOptions {
+    name: string;
+    sysPrompt: string;
+    model: ChatModelBase;
+    maxIters?: number;
+    toolkit?: Toolkit;
+    storage?: StorageBase;
+    compressionConfig?: CompressionConfig;
+}
+/**
+ * The unified agent class in AgentScope library.
+ */
+declare class Agent {
+    name: string;
+    model: ChatModelBase;
+    maxIters: number;
+    toolkit: Toolkit;
+    storage?: StorageBase;
+    context: Msg[];
+    private _loaded;
+    private _sysPrompt;
+    compressionConfig?: CompressionConfig;
+    replyId: string;
+    curIter: number;
+    confirmedToolCallIds: string[];
+    curSummary: string;
+    /**
+     * Initialize an agent instance with the given parameters.
+     *
+     * @param options - The agent configuration options.
+     * @param options.name - The name of the agent.
+     * @param options.sysPrompt - The system prompt for the agent.
+     * @param options.model - The chat model to use.
+     * @param options.maxIters - Maximum iterations (default: 5).
+     * @param options.memory - Memory storage (default: InMemoryMemory).
+     * @param options.toolkit - Toolkit for tools (default: Toolkit).
+     */
+    constructor(options: AgentOptions);
+    /**
+     * Load the state from the storage if storage is provided and not loaded yet.
+     */
+    loadState(): Promise<void>;
+    /**
+     * Save the state of the current reply session to storage if storage is provided.
+     */
+    saveState(): Promise<void>;
+    /**
+     * Get the system prompt of the agent.
+     *
+     * @returns The system prompt string.
+     */
+    get sysPrompt(): string;
+    /**
+     * Reply to the given message and stream agent events as they are generated.
+     *
+     * @param options - The reply options containing the incoming message.
+     * @returns An async generator that yields agent events and resolves to the final reply message.
+     */
+    replyStream(options: ReplyOptions): AsyncGenerator<AgentEvent, Msg>;
+    /**
+     * Reply to the given message, consuming all streamed events internally.
+     *
+     * @param options - The reply options containing the incoming message.
+     * @param options.msgs - The incoming message(s) to reply to.
+     * @returns A promise that resolves to the final reply message.
+     */
+    reply(options: ReplyOptions): Promise<Msg>;
+    /**
+     * Save the given content blocks into the context as a new block in the last assistant message,
+     * or create a new assistant message if the last message is not from the assistant or has a different name.
+     * @param blocks
+     * @param usage
+     */
+    protected _saveToContext(blocks: ContentBlock[], usage?: ChatUsage): void;
+    /**
+     * Get the pending tool calls that have no results yet in the context.
+     * @returns An array of pending `ToolCallBlock`s that are waiting for execution results.
+     */
+    protected _getPendingToolCalls(): ToolCallBlock[];
+    /**
+     * Get the awaiting tool calls that require user confirmation or external execution.
+     * @returns An array of `ToolCallBlock`s that are waiting for user confirmation or external execution.
+     */
+    protected _getAwaitingToolCalls(): {
+        awaitingType?: EventType.REQUIRE_USER_CONFIRM | EventType.REQUIRE_EXTERNAL_EXECUTION;
+        expectedEventType?: EventType.USER_CONFIRM_RESULT | EventType.EXTERNAL_EXECUTION_RESULT;
+        awaitingToolCalls: ToolCallBlock[];
+        preToolCalls: ToolCallBlock[];
+    };
+    /**
+     * Core reply logic without middlewares. Observes the incoming message, runs
+     * reasoning/acting iterations up to `maxIters`, and returns the final response.
+     *
+     * @param options - The reply options containing the incoming message.
+     * @returns An async generator that yields agent events and resolves to the final reply message.
+     */
+    protected _reply(options?: ReplyOptions): AsyncGenerator<AgentEvent, Msg>;
+    /**
+     * Core reasoning logic without middlewares. Calls the model with the current
+     * memory and system prompt, converts the response to agent events, and saves
+     * the resulting message to memory.
+     *
+     * @param options - The reasoning options, including tool choice strategy.
+     * @returns An async generator that yields agent events and resolves to the content blocks of the model response.
+     */
+    protected _reasoning(options: ReasoningOptions): AsyncGenerator<AgentEvent, ChatResponse>;
+    /**
+     * Core acting logic without middlewares. Executes the given tool call, streams
+     * intermediate tool result events, and saves the final tool response to memory.
+     *
+     * @param options - The acting options containing the tool call to execute.
+     * @returns An async generator that yields tool result events.
+     */
+    protected _acting(options: ActingOptions): AsyncGenerator<AgentEvent, ToolResultBlock>;
+    /**
+     * Receive external observation message(s) and save them into memory.
+     *
+     * @param options - The observe options containing the message to store.
+     * @returns A promise that resolves when the message has been saved to memory.
+     */
+    protected _observe(options: ObserveOptions): Promise<void>;
+    /**
+     * Convert a `ChatResponse` chunk into a sequence of typed agent events.
+     * Tracks message IDs across calls via the mutable `responseId` object so that
+     * start/content/end events are correctly correlated.
+     *
+     * @param responseId - Mutable object tracking IDs for the current text, thinking, and tool-call messages.
+     * @param responseId.textMessageId - ID of the in-progress text message, or `null` if not yet started.
+     * @param responseId.thinkingMessageId - ID of the in-progress thinking message, or `null` if not yet started.
+     * @param responseId.textBlockId
+     * @param responseId.thinkingBlockId
+     * @param responseId.toolCallIds - List of tool-call IDs seen so far in this response.
+     * @param chunk - The chat response chunk to convert.
+     * @returns An async generator that yields the corresponding agent events.
+     */
+    protected convertChatResponseToEvent(responseId: {
+        textBlockId: string | null;
+        thinkingBlockId: string | null;
+        toolCallIds: string[];
+    }, chunk: ChatResponse): AsyncGenerator<AgentEvent>;
+    /**
+     * Convert a `ToolResponse` into a sequence of typed agent events, followed by
+     * a final `TOOL_RESULT_END` event.
+     *
+     * @param toolCall - The original tool-use block that triggered this response.
+     * @param toolRes - The tool response containing result content blocks.
+     * @returns An async generator that yields tool result events.
+     */
+    protected convertToolResponseToEvent(toolCall: ToolCallBlock, toolRes: ToolResponse): AsyncGenerator<ToolResultTextDeltaEvent | ToolResultBinaryDeltaEvent | ToolResultEndEvent, void, unknown>;
+    /**
+     * Convert the agent instance to a JSON-serializable object.
+     * @returns An object containing the agent's name and system prompt.
+     */
+    toJSON(): Promise<{
+        replyId: string;
+        confirmedToolCallIds: string[];
+        curIter: number;
+    }>;
+    /**
+     * Split the current context into two parts: one part that needs to be compressed and another part that should be reserved based on the compression configuration. The method calculates how many recent "units" (blocks or tool call pairs) to keep uncompressed according to the `keepRecent` setting in the compression configuration, and ensures that tool calls and their corresponding results are not separated during the split.
+     * @returns An object containing the `toCompressedContext` which includes the messages that need to be compressed, and the `reservedContext` which includes the recent messages that should be kept uncompressed.
+     */
+    protected _splitContextForCompression(): {
+        toCompressedContext: Msg[];
+        reservedContext: Msg[];
+    };
+    /**
+     * Compress the agent's memory using the specified compression model (if provided) or the original model.
+     */
+    protected compressMemoryIfNeeded(): Promise<void>;
+}
+
+export { type ActingOptions, Agent, type AgentOptions, type CompressionConfig, type ReasoningOptions, type ReplyOptions };