@aigne/core 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@
 
 * add user context support ([#131](https://github.com/AIGNE-io/aigne-framework/issues/131)) ([4dd9d20](https://github.com/AIGNE-io/aigne-framework/commit/4dd9d20953f6ac33933723db56efd9b44bafeb02))
 
+## [1.22.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.21.0...core-v1.22.0) (2025-06-24)
+
+
+### Features
+
+* support observability for cli and blocklet ([#155](https://github.com/AIGNE-io/aigne-framework/issues/155)) ([5baa705](https://github.com/AIGNE-io/aigne-framework/commit/5baa705a33cfdba1efc5ccbe18674c27513ca97d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/observability bumped to 0.1.0
+
 ## [1.21.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.20.1...core-v1.21.0) (2025-06-20)
 
 

package/lib/cjs/agents/agent.d.ts

@@ -176,6 +176,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * List of memories this agent can use
      */
     readonly memories: MemoryAgent[];
+    tag?: string;
     /**
      * Maximum number of memory items to retrieve
      */
@@ -723,6 +724,7 @@ export interface FunctionAgentOptions<I extends Message = Message, O extends Mes
  * {@includeCode ../../test/agents/agent.test.ts#example-function-agent}
  */
 export declare class FunctionAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+    tag: string;
     /**
      * Create a function agent from a function or options
      *

package/lib/cjs/agents/agent.js

@@ -127,6 +127,7 @@ class Agent {
      * List of memories this agent can use
      */
     memories = [];
+    tag;
     /**
      * Maximum number of memory items to retrieve
      */
@@ -641,6 +642,7 @@ function checkAgentInputOutputSchema(schema) {
  * {@includeCode ../../test/agents/agent.test.ts#example-function-agent}
  */
 class FunctionAgent extends Agent {
+    tag = "FunctionAgent";
     /**
      * Create a function agent from a function or options
      *

package/lib/cjs/agents/ai-agent.d.ts

@@ -132,6 +132,7 @@ export declare const aiAgentOptionsSchema: ZodObject<{
  * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-basic}
  */
 export declare class AIAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+    tag: string;
     /**
      * Create an AIAgent with the specified options
      *

package/lib/cjs/agents/ai-agent.js

@@ -80,6 +80,7 @@ exports.aiAgentOptionsSchema = agent_js_1.agentOptionsSchema.extend({
  * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-basic}
  */
 class AIAgent extends agent_js_1.Agent {
+    tag = "AIAgent";
     /**
      * Create an AIAgent with the specified options
      *

package/lib/cjs/agents/chat-model.d.ts

@@ -24,6 +24,7 @@ import { Agent, type AgentInvokeOptions, type AgentProcessResult, type Message }
  * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelOutput> {
+    tag: string;
     constructor();
     /**
      * Indicates whether the model supports parallel tool calls

package/lib/cjs/agents/chat-model.js

@@ -27,6 +27,7 @@ const agent_js_1 = require("./agent.js");
  * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 class ChatModel extends agent_js_1.Agent {
+    tag = "ChatModelAgent";
     constructor() {
         super({
             inputSchema: chatModelInputSchema,

package/lib/cjs/agents/mcp-agent.d.ts

@@ -57,6 +57,7 @@ export type SSEServerParameters = {
  * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-from-sse}
  */
 export declare class MCPAgent extends Agent {
+    tag: string;
     /**
      * Create an MCPAgent from a connection to an SSE server.
      *
@@ -186,22 +187,26 @@ export interface MCPBaseOptions<I extends Message = Message, O extends Message =
     client: ClientWithReconnect;
 }
 export declare abstract class MCPBase<I extends Message, O extends Message> extends Agent<I, O> {
+    tag: string;
     constructor(options: MCPBaseOptions<I, O>);
     protected client: ClientWithReconnect;
 }
 export declare class MCPTool extends MCPBase<Message, CallToolResult> {
+    tag: string;
     process(input: Message): Promise<CallToolResult>;
 }
 export interface MCPPromptInput extends Record<string, unknown> {
     [key: string]: string;
 }
 export declare class MCPPrompt extends MCPBase<MCPPromptInput, GetPromptResult> {
+    tag: string;
     process(input: MCPPromptInput): Promise<GetPromptResult>;
 }
 export interface MCPResourceOptions extends MCPBaseOptions<MCPPromptInput, ReadResourceResult> {
     uri: string;
 }
 export declare class MCPResource extends MCPBase<MCPPromptInput, ReadResourceResult> {
+    tag: string;
     constructor(options: MCPResourceOptions);
     uri: string;
     process(input: MCPPromptInput): Promise<ReadResourceResult>;

package/lib/cjs/agents/mcp-agent.js

@@ -55,6 +55,7 @@ function getMCPServerString(options) {
  * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-from-sse}
  */
 class MCPAgent extends agent_js_1.Agent {
+    tag = "MCPAgent";
     static from(options) {
         (0, type_utils_js_1.checkArguments)("MCPAgent.from", mcpAgentOptionsSchema, options);
         if (isSSEServerParameters(options)) {
@@ -251,6 +252,7 @@ class ClientWithReconnect extends index_js_2.Client {
     }
 }
 class MCPBase extends agent_js_1.Agent {
+    tag = "MCPBase";
     constructor(options) {
         super(options);
         this.client = options.client;
@@ -259,6 +261,7 @@ class MCPBase extends agent_js_1.Agent {
 }
 exports.MCPBase = MCPBase;
 class MCPTool extends MCPBase {
+    tag = "MCPTool";
     async process(input) {
         const result = await this.client.callTool({ name: this.name, arguments: input });
         return result;
@@ -266,6 +269,7 @@ class MCPTool extends MCPBase {
 }
 exports.MCPTool = MCPTool;
 class MCPPrompt extends MCPBase {
+    tag = "MCPPrompt";
     async process(input) {
         const result = await this.client.getPrompt({ name: this.name, arguments: input });
         return result;
@@ -273,6 +277,7 @@ class MCPPrompt extends MCPBase {
 }
 exports.MCPPrompt = MCPPrompt;
 class MCPResource extends MCPBase {
+    tag = "MCPResource";
     constructor(options) {
         super(options);
         this.uri = options.uri;

package/lib/cjs/agents/team-agent.d.ts

@@ -52,6 +52,7 @@ export interface TeamAgentOptions<I extends Message, O extends Message> extends
  * {@includeCode ../../test/agents/team-agent.test.ts#example-team-agent-sequential}
  */
 export declare class TeamAgent<I extends Message, O extends Message> extends Agent<I, O> {
+    tag: string;
     /**
      * Create a TeamAgent from the provided options.
      *

package/lib/cjs/agents/team-agent.js

@@ -45,6 +45,7 @@ var ProcessMode;
  * {@includeCode ../../test/agents/team-agent.test.ts#example-team-agent-sequential}
  */
 class TeamAgent extends agent_js_1.Agent {
+    tag = "TeamAgent";
     /**
      * Create a TeamAgent from the provided options.
      *

package/lib/cjs/agents/user-agent.d.ts

@@ -7,6 +7,7 @@ export interface UserAgentOptions<I extends Message = Message, O extends Message
     activeAgent?: Agent;
 }
 export declare class UserAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+    tag: string;
     static from<I extends Message, O extends Message>(options: UserAgentOptions<I, O>): UserAgent<I, O>;
     constructor(options: UserAgentOptions<I, O>);
     context: Context;

package/lib/cjs/agents/user-agent.js

@@ -5,6 +5,7 @@ const message_queue_js_1 = require("../aigne/message-queue.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_1 = require("./agent.js");
 class UserAgent extends agent_js_1.Agent {
+    tag = "UserAgent";
     static from(options) {
         return new UserAgent(options);
     }
@@ -26,9 +27,8 @@ class UserAgent extends agent_js_1.Agent {
             super.publishToTopics(output, options);
     }
     invoke = ((input, options = {}) => {
-        if (!options.context)
-            this.context = this.context.newContext({ reset: true });
-        return super.invoke(input, { ...options, context: this.context });
+        options.context ??= this.context.newContext({ reset: true });
+        return super.invoke(input, options);
     });
     async process(input, options) {
         if (this._process) {
@@ -38,6 +38,9 @@ class UserAgent extends agent_js_1.Agent {
             const [output, agent] = await options.context.invoke(this.activeAgent, input, {
                 returnActiveAgent: true,
                 streaming: true,
+                // Do not create a new context for the nested agent invocation,
+                // We are resetting the context in the override invoke method
+                newContext: false,
             });
             agent.then((agent) => {
                 this.activeAgent = agent;

package/lib/cjs/aigne/aigne.d.ts

@@ -1,3 +1,4 @@
+import { AIGNEObserver } from "@aigne/observability";
 import { Agent, type AgentResponse, type AgentResponseStream, type Message } from "../agents/agent.js";
 import { ChatModel } from "../agents/chat-model.js";
 import type { UserAgent } from "../agents/user-agent.js";
@@ -33,6 +34,10 @@ export interface AIGNEOptions {
      * Limits for the AIGNE instance, such as timeout, max tokens, max invocations, etc.
      */
     limits?: ContextLimits;
+    /**
+     * Observer for the AIGNE instance.
+     */
+    observer?: AIGNEObserver;
 }
 /**
  * AIGNE is a class that orchestrates multiple agents to build complex AI applications.
@@ -98,6 +103,10 @@ export declare class AIGNE<U extends UserContext = UserContext> {
     readonly agents: Agent<Message, Message>[] & {
         [key: string]: Agent<Message, Message>;
     };
+    /**
+     * Observer for the AIGNE instance.
+     */
+    readonly observer?: AIGNEObserver;
     /**
      * Adds one or more agents to this AIGNE instance.
      * Each agent is attached to this AIGNE instance, allowing it to access the AIGNE's resources.
@@ -111,7 +120,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      *
      * @returns A new AIGNEContext instance bound to this AIGNE.
      */
-    newContext(options?: Partial<Context>): AIGNEContext;
+    newContext(options?: Partial<Pick<Context, "userContext" | "memories">>): AIGNEContext;
     /**
      * Creates a user agent for consistent interactions with a specified agent.
      * This method allows you to create a wrapper around an agent for repeated invocations.

package/lib/cjs/aigne/aigne.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AIGNE = void 0;
+const observability_1 = require("@aigne/observability");
 const zod_1 = require("zod");
 const agent_js_1 = require("../agents/agent.js");
 const chat_model_js_1 = require("../agents/chat-model.js");
@@ -52,10 +53,15 @@ class AIGNE {
         this.description = options?.description;
         this.model = options?.model;
         this.limits = options?.limits;
+        this.observer =
+            process.env.AIGNE_OBSERVABILITY_DISABLED === "true"
+                ? undefined
+                : (options?.observer ?? new observability_1.AIGNEObserver());
         if (options?.skills?.length)
             this.skills.push(...options.skills);
         if (options?.agents?.length)
             this.addAgent(...options.agents);
+        this.observer?.serve();
         this.initProcessExitHandler();
     }
     /**
@@ -90,6 +96,10 @@ class AIGNE {
      * Provides indexed access by agent name.
      */
     agents = (0, type_utils_js_1.createAccessorArray)([], (arr, name) => arr.find((i) => i.name === name));
+    /**
+     * Observer for the AIGNE instance.
+     */
+    observer;
     /**
      * Adds one or more agents to this AIGNE instance.
      * Each agent is attached to this AIGNE instance, allowing it to access the AIGNE's resources.
@@ -110,10 +120,16 @@ class AIGNE {
      * @returns A new AIGNEContext instance bound to this AIGNE.
      */
     newContext(options) {
-        return new context_js_1.AIGNEContext(this, options);
+        const context = new context_js_1.AIGNEContext(this);
+        if (options?.userContext)
+            context.userContext = options.userContext;
+        if (options?.memories)
+            context.memories = options.memories;
+        return context;
     }
     invoke(agent, message, options) {
-        return new context_js_1.AIGNEContext(this).invoke(agent, message, options);
+        const context = new context_js_1.AIGNEContext(this);
+        return context.invoke(agent, message, { ...options, newContext: false });
     }
     /**
      * Publishes a message to the message queue for inter-agent communication.
@@ -192,5 +208,6 @@ const aigneOptionsSchema = zod_1.z.object({
     model: zod_1.z.instanceof(chat_model_js_1.ChatModel).optional(),
     skills: zod_1.z.array(zod_1.z.instanceof(agent_js_1.Agent)).optional(),
     agents: zod_1.z.array(zod_1.z.instanceof(agent_js_1.Agent)).optional(),
+    observer: zod_1.z.instanceof(observability_1.AIGNEObserver).optional(),
 });
 const aigneAddAgentArgsSchema = zod_1.z.array(zod_1.z.instanceof(agent_js_1.Agent));

package/lib/cjs/aigne/context.d.ts

@@ -1,3 +1,5 @@
+import type { AIGNEObserver } from "@aigne/observability";
+import type { Span } from "@opentelemetry/api";
 import { Emitter } from "strict-event-emitter";
 import { Agent, type AgentInvokeOptions, type AgentProcessAsyncGenerator, type AgentResponse, type AgentResponseStream, type Message } from "../agents/agent.js";
 import type { ChatModel } from "../agents/chat-model.js";
@@ -45,6 +47,13 @@ export interface InvokeOptions<U extends UserContext = UserContext> extends Part
     returnMetadata?: boolean;
     disableTransfer?: boolean;
     sourceAgent?: Agent;
+    /**
+     * Whether to create a new context for this invocation.
+     * If false, the invocation will use the current context.
+     *
+     * @default true
+     */
+    newContext?: boolean;
 }
 /**
  * @hidden
@@ -57,8 +66,11 @@ export interface UserContext extends Record<string, unknown> {
 export interface Context<U extends UserContext = UserContext> extends TypedEventEmitter<ContextEventMap, ContextEmitEventMap> {
     id: string;
     parentId?: string;
+    rootId: string;
     model?: ChatModel;
     skills?: Agent[];
+    observer?: AIGNEObserver;
+    span?: Span;
     usage: ContextUsage;
     limits?: ContextLimits;
     status?: "normal" | "timeout";
@@ -126,12 +138,18 @@ export interface Context<U extends UserContext = UserContext> extends TypedEvent
  * @hidden
  */
 export declare class AIGNEContext implements Context {
-    constructor(...[parent, ...args]: ConstructorParameters<typeof AIGNEContextShared>);
-    parentId?: string;
+    constructor(parent?: ConstructorParameters<typeof AIGNEContextShared>[0], { reset }?: {
+        reset?: boolean;
+    });
     id: string;
+    parentId?: string;
+    rootId: string;
+    span?: Span;
     readonly internal: AIGNEContextShared;
+    get messageQueue(): MessageQueue;
     get model(): ChatModel | undefined;
     get skills(): Agent<Message, Message>[] | undefined;
+    get observer(): AIGNEObserver | undefined;
     get limits(): ContextLimits | undefined;
     get status(): "normal" | "timeout";
     get usage(): ContextUsage;
@@ -148,19 +166,22 @@ export declare class AIGNEContext implements Context {
     subscribe: Context["subscribe"];
     unsubscribe: Context["unsubscribe"];
     emit<K extends keyof ContextEmitEventMap>(eventName: K, ...args: Args<K, ContextEmitEventMap>): boolean;
+    private trace;
     on<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;
     once<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;
     off<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;
 }
 declare class AIGNEContextShared {
     private readonly parent?;
-    constructor(parent?: (Pick<Context, "model" | "skills" | "limits"> & {
+    span?: Span;
+    constructor(parent?: (Pick<Context, "model" | "skills" | "limits" | "observer"> & {
         messageQueue?: MessageQueue;
-    }) | undefined, overrides?: Partial<Context>);
+    }) | undefined);
     readonly messageQueue: MessageQueue;
     readonly events: Emitter<any>;
     get model(): ChatModel | undefined;
     get skills(): Agent<Message, Message>[] | undefined;
+    get observer(): AIGNEObserver | undefined;
     get limits(): ContextLimits | undefined;
     usage: ContextUsage;
     userContext: Context["userContext"];

package/lib/cjs/aigne/context.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AIGNEContext = void 0;
+const api_1 = require("@opentelemetry/api");
 const fast_deep_equal_1 = __importDefault(require("fast-deep-equal"));
 const strict_event_emitter_1 = require("strict-event-emitter");
 const uuid_1 = require("uuid");
@@ -12,6 +13,7 @@ const agent_js_1 = require("../agents/agent.js");
 const types_js_1 = require("../agents/types.js");
 const user_agent_js_1 = require("../agents/user-agent.js");
 const event_stream_js_1 = require("../utils/event-stream.js");
+const logger_js_1 = require("../utils/logger.js");
 const promise_js_1 = require("../utils/promise.js");
 const stream_utils_js_1 = require("../utils/stream-utils.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
@@ -21,24 +23,47 @@ const usage_js_1 = require("./usage.js");
  * @hidden
  */
 class AIGNEContext {
-    constructor(...[parent, ...args]) {
-        if (parent instanceof AIGNEContext) {
-            this.parentId = parent.id;
+    constructor(parent, { reset } = {}) {
+        const tracer = parent?.observer?.tracer;
+        if (parent instanceof AIGNEContext && !reset) {
             this.internal = parent.internal;
+            this.parentId = parent.id;
+            this.rootId = parent.rootId;
+            if (parent.span) {
+                const parentContext = api_1.trace.setSpan(api_1.context.active(), parent.span);
+                this.span = tracer?.startSpan("childAIGNEContext", undefined, parentContext);
+            }
+            else {
+                if (!process.env.AIGNE_OBSERVABILITY_DISABLED) {
+                    throw new Error("parent span is not set");
+                }
+            }
         }
         else {
-            this.internal = new AIGNEContextShared(parent, ...args);
+            this.internal = new AIGNEContextShared(parent);
+            this.span = tracer?.startSpan("AIGNEContext");
+            // 修改了 rootId 是否会之前的有影响？，之前为 this.id
+            this.rootId = this.span?.spanContext?.().traceId ?? (0, uuid_1.v7)();
         }
+        this.id = this.span?.spanContext()?.spanId ?? (0, uuid_1.v7)();
     }
+    id;
     parentId;
-    id = (0, uuid_1.v7)();
+    rootId;
+    span;
     internal;
+    get messageQueue() {
+        return this.internal.messageQueue;
+    }
     get model() {
         return this.internal.model;
     }
     get skills() {
         return this.internal.skills;
     }
+    get observer() {
+        return this.internal.observer;
+    }
     get limits() {
         return this.internal.limits;
     }
@@ -61,9 +86,7 @@ class AIGNEContext {
         this.internal.memories = memories;
     }
     newContext({ reset } = {}) {
-        if (reset)
-            return new AIGNEContext(this, { userContext: {} });
-        return new AIGNEContext(this);
+        return new AIGNEContext(this, { reset });
     }
     invoke = ((agent, message, options) => {
         (0, type_utils_js_1.checkArguments)("AIGNEContext.invoke", aigneContextInvokeArgsSchema, {
@@ -85,7 +108,7 @@ class AIGNEContext {
                 activeAgent: agent,
             });
         }
-        const newContext = this.newContext();
+        const newContext = options?.newContext === false ? this : this.newContext();
         return Promise.resolve(newContext.internal.invoke(agent, message, newContext, options)).then(async (response) => {
             if (!options?.streaming) {
                 let { __activeAgent__: activeAgent, ...output } = await (0, stream_utils_js_1.agentResponseStreamToObject)(response);
@@ -162,8 +185,55 @@ class AIGNEContext {
             timestamp: Date.now(),
         };
         const newArgs = [b, ...args.slice(1)];
+        this.trace(eventName, args, b);
         return this.internal.events.emit(eventName, ...newArgs);
     }
+    async trace(eventName, args, b) {
+        const span = this.span;
+        if (!span)
+            return;
+        try {
+            switch (eventName) {
+                case "agentStarted": {
+                    const { agent, input } = args[0];
+                    span.updateName(agent.name);
+                    span.setAttribute("custom.trace_id", this.rootId);
+                    span.setAttribute("custom.span_id", this.id);
+                    if (this.parentId) {
+                        span.setAttribute("custom.parent_id", this.parentId);
+                    }
+                    span.setAttribute("custom.started_at", b.timestamp);
+                    span.setAttribute("input", JSON.stringify(input));
+                    span.setAttribute("agentTag", agent.tag ?? "UnknownAgent");
+                    break;
+                }
+                case "agentSucceed": {
+                    const { output } = args[0];
+                    try {
+                        span.setAttribute("output", JSON.stringify(output));
+                    }
+                    catch (_e) {
+                        logger_js_1.logger.error("parse output error", _e.message);
+                        span.setAttribute("output", JSON.stringify({}));
+                    }
+                    span.setStatus({ code: api_1.SpanStatusCode.OK, message: "Agent succeed" });
+                    span.end();
+                    await this.observer?.traceExporter?.forceFlush?.();
+                    break;
+                }
+                case "agentFailed": {
+                    const { error } = args[0];
+                    span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+                    span.end();
+                    await this.observer?.traceExporter?.forceFlush?.();
+                    break;
+                }
+            }
+        }
+        catch (err) {
+            logger_js_1.logger.error("AIGNEContext.trace observer error", { eventName, error: err });
+        }
+    }
     on(eventName, listener) {
         this.internal.events.on(eventName, listener);
         return this;
@@ -180,11 +250,10 @@ class AIGNEContext {
 exports.AIGNEContext = AIGNEContext;
 class AIGNEContextShared {
     parent;
-    constructor(parent, overrides) {
+    span;
+    constructor(parent) {
         this.parent = parent;
         this.messageQueue = this.parent?.messageQueue ?? new message_queue_js_1.MessageQueue();
-        this.userContext = overrides?.userContext ?? {};
-        this.memories = overrides?.memories ?? [];
     }
     messageQueue;
     events = new strict_event_emitter_1.Emitter();
@@ -194,12 +263,15 @@ class AIGNEContextShared {
     get skills() {
         return this.parent?.skills;
     }
+    get observer() {
+        return this.parent?.observer;
+    }
     get limits() {
         return this.parent?.limits;
     }
     usage = (0, usage_js_1.newEmptyContextUsage)();
-    userContext;
-    memories;
+    userContext = {};
+    memories = [];
     abortController = new AbortController();
     timer;
     initTimeout() {

package/lib/cjs/loader/agent-yaml.d.ts

@@ -4,8 +4,8 @@ import { ProcessMode } from "../agents/team-agent.js";
 export declare function loadAgentFromYamlFile(path: string): Promise<{
     type: "mcp";
     url?: string | undefined;
-    args?: string[] | undefined;
     command?: string | undefined;
+    args?: string[] | undefined;
 } | {
     type: "team";
     name: string;

package/lib/cjs/memory/memory.d.ts

@@ -21,6 +21,7 @@ export interface MemoryAgentOptions extends Partial<Pick<MemoryAgent, "recorder"
  * instead provides memory management capabilities to the system.
  */
 export declare class MemoryAgent extends Agent {
+    tag: string;
     /**
      * Creates a new MemoryAgent instance.
      */

package/lib/cjs/memory/memory.js

@@ -16,6 +16,7 @@ exports.newMemoryId = newMemoryId;
  * instead provides memory management capabilities to the system.
  */
 class MemoryAgent extends agent_js_1.Agent {
+    tag = "MemoryAgent";
     /**
      * Creates a new MemoryAgent instance.
      */

package/lib/cjs/memory/recorder.d.ts

@@ -77,6 +77,7 @@ export declare const memoryRecorderOutputSchema: z.ZodObject<{
  * implementations of the process method to handle the actual storage logic.
  */
 export declare abstract class MemoryRecorder extends Agent<MemoryRecorderInput, MemoryRecorderOutput> {
+    tag: string;
     /**
      * Creates a new MemoryRecorder instance with predefined input and output schemas.
      *

package/lib/cjs/memory/recorder.js

@@ -34,6 +34,7 @@ exports.memoryRecorderOutputSchema = zod_1.z.object({
  * implementations of the process method to handle the actual storage logic.
  */
 class MemoryRecorder extends agent_js_1.Agent {
+    tag = "MemoryRecorderAgent";
     /**
      * Creates a new MemoryRecorder instance with predefined input and output schemas.
      *

package/lib/cjs/memory/retriever.d.ts

@@ -90,6 +90,7 @@ export declare const memoryRetrieverOutputSchema: z.ZodObject<{
  * implementations of the process method to handle the actual retrieval logic.
  */
 export declare abstract class MemoryRetriever extends Agent<MemoryRetrieverInput, MemoryRetrieverOutput> {
+    tag: string;
     /**
      * Creates a new MemoryRetriever instance with predefined input and output schemas.
      *

package/lib/cjs/memory/retriever.js

@@ -35,6 +35,7 @@ exports.memoryRetrieverOutputSchema = zod_1.z.object({
  * implementations of the process method to handle the actual retrieval logic.
  */
 class MemoryRetriever extends agent_js_1.Agent {
+    tag = "MemoryRetrieverAgent";
     /**
      * Creates a new MemoryRetriever instance with predefined input and output schemas.
      *

package/lib/dts/agents/agent.d.ts

@@ -176,6 +176,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * List of memories this agent can use
      */
     readonly memories: MemoryAgent[];
+    tag?: string;
     /**
      * Maximum number of memory items to retrieve
      */
@@ -723,6 +724,7 @@ export interface FunctionAgentOptions<I extends Message = Message, O extends Mes
  * {@includeCode ../../test/agents/agent.test.ts#example-function-agent}
  */
 export declare class FunctionAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+    tag: string;
     /**
      * Create a function agent from a function or options
      *

package/lib/dts/agents/ai-agent.d.ts

@@ -132,6 +132,7 @@ export declare const aiAgentOptionsSchema: ZodObject<{
  * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-basic}
  */
 export declare class AIAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+    tag: string;
     /**
      * Create an AIAgent with the specified options
      *