@aigne/core 1.20.1 → 1.22.0

package/lib/esm/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.
@@ -134,7 +143,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * @param options.streaming - Must be false to return a response stream
      * @returns A promise resolving to a tuple containing the agent's response and the final active agent
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions<U> & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options: InvokeOptions<U> & {
         returnActiveAgent: true;
         streaming?: false;
     }): Promise<[O, Agent]>;
@@ -148,7 +157,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * @param options.streaming - Must be true to return a response stream
      * @returns A promise resolving to a tuple containing the agent's response stream and a promise for the final agent
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions<U> & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options: InvokeOptions<U> & {
         returnActiveAgent: true;
         streaming: true;
     }): Promise<[AgentResponseStream<O>, Promise<Agent>]>;
@@ -165,7 +174,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * Here's a simple example of how to invoke an agent:
      * {@includeCode ../../test/aigne/aigne.test.ts#example-simple}
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options?: InvokeOptions<U> & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options?: InvokeOptions<U> & {
         returnActiveAgent?: false;
         streaming?: false;
     }): Promise<O>;
@@ -182,7 +191,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * Here's an example of how to invoke an agent with streaming response:
      * {@includeCode ../../test/aigne/aigne.test.ts#example-streaming}
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions<U> & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options: InvokeOptions<U> & {
         returnActiveAgent?: false;
         streaming: true;
     }): Promise<AgentResponseStream<O>>;
@@ -196,7 +205,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * @returns Either a UserAgent (when no message provided) or a promise resolving to the agent's response
      * with optional active agent information based on the provided options
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message?: I, options?: InvokeOptions<U>): UserAgent<I, O> | Promise<AgentResponse<O> | [AgentResponse<O>, Agent]>;
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message?: I & Message, options?: InvokeOptions<U>): UserAgent<I, O> | Promise<AgentResponse<O> | [AgentResponse<O>, Agent]>;
     /**
      * Publishes a message to the message queue for inter-agent communication.
      * This method broadcasts a message to all subscribers of the specified topic(s).

package/lib/esm/aigne/aigne.js

@@ -1,3 +1,4 @@
+import { AIGNEObserver } from "@aigne/observability";
 import { z } from "zod";
 import { Agent, } from "../agents/agent.js";
 import { ChatModel } from "../agents/chat-model.js";
@@ -49,10 +50,15 @@ export 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 AIGNEObserver());
         if (options?.skills?.length)
             this.skills.push(...options.skills);
         if (options?.agents?.length)
             this.addAgent(...options.agents);
+        this.observer?.serve();
         this.initProcessExitHandler();
     }
     /**
@@ -87,6 +93,10 @@ export class AIGNE {
      * Provides indexed access by agent name.
      */
     agents = 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.
@@ -107,10 +117,16 @@ export class AIGNE {
      * @returns A new AIGNEContext instance bound to this AIGNE.
      */
     newContext(options) {
-        return new AIGNEContext(this, options);
+        const context = new AIGNEContext(this);
+        if (options?.userContext)
+            context.userContext = options.userContext;
+        if (options?.memories)
+            context.memories = options.memories;
+        return context;
     }
     invoke(agent, message, options) {
-        return new AIGNEContext(this).invoke(agent, message, options);
+        const context = new AIGNEContext(this);
+        return context.invoke(agent, message, { ...options, newContext: false });
     }
     /**
      * Publishes a message to the message queue for inter-agent communication.
@@ -188,5 +204,6 @@ const aigneOptionsSchema = z.object({
     model: z.instanceof(ChatModel).optional(),
     skills: z.array(z.instanceof(Agent)).optional(),
     agents: z.array(z.instanceof(Agent)).optional(),
+    observer: z.instanceof(AIGNEObserver).optional(),
 });
 const aigneAddAgentArgsSchema = z.array(z.instanceof(Agent));

package/lib/esm/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";
@@ -78,11 +90,11 @@ export interface Context<U extends UserContext = UserContext> extends TypedEvent
      * @param options.streaming return a stream of the output
      * @returns the output of the agent and the final active agent
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options: InvokeOptions & {
         returnActiveAgent: true;
         streaming?: false;
     }): Promise<[O, Agent]>;
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options: InvokeOptions & {
         returnActiveAgent: true;
         streaming: true;
     }): Promise<[AgentResponseStream<O>, Promise<Agent>]>;
@@ -92,13 +104,13 @@ export interface Context<U extends UserContext = UserContext> extends TypedEvent
      * @param message Message to pass to the agent
      * @returns the output of the agent
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options?: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options?: InvokeOptions & {
         streaming?: false;
     }): Promise<O>;
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I & Message, options: InvokeOptions & {
         streaming: true;
     }): Promise<AgentResponseStream<O>>;
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message?: I, options?: InvokeOptions): UserAgent<I, O> | Promise<AgentResponse<O> | [AgentResponse<O>, Agent]>;
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message?: I & Message, options?: InvokeOptions): UserAgent<I, O> | Promise<AgentResponse<O> | [AgentResponse<O>, Agent]>;
     /**
      * Publish a message to a topic, the aigne will invoke the listeners of the topic
      * @param topic topic name, or an array of topic names
@@ -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"];
@@ -169,7 +190,7 @@ declare class AIGNEContextShared {
     private timer?;
     private initTimeout;
     get status(): "normal" | "timeout";
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, input: I, context: Context, options?: InvokeOptions): AgentProcessAsyncGenerator<O & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, input: I & Message, context: Context, options?: InvokeOptions): AgentProcessAsyncGenerator<O & {
         __activeAgent__: Agent;
     }>;
     private invokeAgent;

package/lib/esm/aigne/context.js

@@ -1,3 +1,4 @@
+import { SpanStatusCode, context, trace } from "@opentelemetry/api";
 import equal from "fast-deep-equal";
 import { Emitter } from "strict-event-emitter";
 import { v7 } from "uuid";
@@ -6,6 +7,7 @@ import { Agent, isAgentResponseDelta, isEmptyChunk, } from "../agents/agent.js";
 import { isTransferAgentOutput, transferAgentOutputKey, } from "../agents/types.js";
 import { UserAgent } from "../agents/user-agent.js";
 import { AgentResponseProgressStream } from "../utils/event-stream.js";
+import { logger } from "../utils/logger.js";
 import { promiseWithResolvers } from "../utils/promise.js";
 import { agentResponseStreamToObject, asyncGeneratorToReadableStream, mergeReadableStreams, onAgentResponseStreamEnd, } from "../utils/stream-utils.js";
 import { checkArguments, isEmpty, isNil, omit, } from "../utils/type-utils.js";
@@ -15,24 +17,47 @@ import { newEmptyContextUsage } from "./usage.js";
  * @hidden
  */
 export 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 = trace.setSpan(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 ?? v7();
         }
+        this.id = this.span?.spanContext()?.spanId ?? v7();
     }
+    id;
     parentId;
-    id = 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;
     }
@@ -55,9 +80,7 @@ export 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) => {
         checkArguments("AIGNEContext.invoke", aigneContextInvokeArgsSchema, {
@@ -79,7 +102,7 @@ export 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 agentResponseStreamToObject(response);
@@ -156,8 +179,55 @@ export 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.error("parse output error", _e.message);
+                        span.setAttribute("output", JSON.stringify({}));
+                    }
+                    span.setStatus({ code: SpanStatusCode.OK, message: "Agent succeed" });
+                    span.end();
+                    await this.observer?.traceExporter?.forceFlush?.();
+                    break;
+                }
+                case "agentFailed": {
+                    const { error } = args[0];
+                    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+                    span.end();
+                    await this.observer?.traceExporter?.forceFlush?.();
+                    break;
+                }
+            }
+        }
+        catch (err) {
+            logger.error("AIGNEContext.trace observer error", { eventName, error: err });
+        }
+    }
     on(eventName, listener) {
         this.internal.events.on(eventName, listener);
         return this;
@@ -173,11 +243,10 @@ export class AIGNEContext {
 }
 class AIGNEContextShared {
     parent;
-    constructor(parent, overrides) {
+    span;
+    constructor(parent) {
         this.parent = parent;
         this.messageQueue = this.parent?.messageQueue ?? new MessageQueue();
-        this.userContext = overrides?.userContext ?? {};
-        this.memories = overrides?.memories ?? [];
     }
     messageQueue;
     events = new Emitter();
@@ -187,12 +256,15 @@ class AIGNEContextShared {
     get skills() {
         return this.parent?.skills;
     }
+    get observer() {
+        return this.parent?.observer;
+    }
     get limits() {
         return this.parent?.limits;
     }
     usage = newEmptyContextUsage();
-    userContext;
-    memories;
+    userContext = {};
+    memories = [];
     abortController = new AbortController();
     timer;
     initTimeout() {

package/lib/esm/loader/agent-js.d.ts

@@ -1,6 +1,6 @@
 import { type ZodObject, type ZodType, z } from "zod";
-import type { Message } from "../agents/agent.js";
-export declare function loadAgentFromJsFile(path: string): Promise<{
+import { Agent, type Message } from "../agents/agent.js";
+export declare function loadAgentFromJsFile(path: string): Promise<Agent<any, any> | {
     process: (args_0: Message) => Message;
     name: string;
     description?: string | undefined;

package/lib/esm/loader/agent-js.js

@@ -1,5 +1,6 @@
 import { jsonSchemaToZod } from "@aigne/json-schema-to-zod";
 import { z } from "zod";
+import { Agent } from "../agents/agent.js";
 import { customCamelize } from "../utils/camelize.js";
 import { tryOrThrow } from "../utils/type-utils.js";
 import { inputOutputSchema } from "./schema.js";
@@ -19,6 +20,8 @@ const agentJsFileSchema = z.object({
 });
 export async function loadAgentFromJsFile(path) {
     const { default: agent } = await tryOrThrow(() => import(path), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
+    if (agent instanceof Agent)
+        return agent;
     if (typeof agent !== "function") {
         throw new Error(`Agent file ${path} must export a default function, but got ${typeof agent}`);
     }

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

@@ -1,6 +1,29 @@
 import { type ZodObject, type ZodType, z } from "zod";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
+import { ProcessMode } from "../agents/team-agent.js";
 export declare function loadAgentFromYamlFile(path: string): Promise<{
+    type: "mcp";
+    url?: string | undefined;
+    command?: string | undefined;
+    args?: string[] | undefined;
+} | {
+    type: "team";
+    name: string;
+    description?: string | undefined;
+    skills?: string[] | undefined;
+    mode?: ProcessMode | undefined;
+    inputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }> | undefined;
+    outputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }> | undefined;
+} | {
+    instructions: string | undefined;
     type: "ai";
     name: string;
     description?: string | undefined;
@@ -9,7 +32,6 @@ export declare function loadAgentFromYamlFile(path: string): Promise<{
         provider: string;
         subscribeTopic?: string[] | undefined;
     } | undefined;
-    instructions?: string | undefined;
     inputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
         [x: string]: any;
     }, {
@@ -23,9 +45,4 @@ export declare function loadAgentFromYamlFile(path: string): Promise<{
     inputKey?: string | undefined;
     outputKey?: string | undefined;
     toolChoice?: AIAgentToolChoice | undefined;
-} | {
-    type: "mcp";
-    url?: string | undefined;
-    args?: string[] | undefined;
-    command?: string | undefined;
 }>;

package/lib/esm/loader/agent-yaml.js

@@ -3,6 +3,7 @@ import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { parse } from "yaml";
 import { z } from "zod";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
+import { ProcessMode } from "../agents/team-agent.js";
 import { customCamelize } from "../utils/camelize.js";
 import { tryOrThrow } from "../utils/type-utils.js";
 import { inputOutputSchema } from "./schema.js";
@@ -15,7 +16,12 @@ const agentFileSchema = z.discriminatedUnion("type", [
             .nullish()
             .transform((v) => v ?? undefined),
         instructions: z
-            .string()
+            .union([
+            z.string(),
+            z.object({
+                url: z.string(),
+            }),
+        ])
             .nullish()
             .transform((v) => v ?? undefined),
         input_key: z
@@ -69,16 +75,46 @@ const agentFileSchema = z.discriminatedUnion("type", [
             .nullish()
             .transform((v) => v ?? undefined),
     }),
+    z.object({
+        type: z.literal("team"),
+        name: z.string(),
+        description: z
+            .string()
+            .nullish()
+            .transform((v) => v ?? undefined),
+        input_schema: inputOutputSchema
+            .nullish()
+            .transform((v) => (v ? jsonSchemaToZod(v) : undefined)),
+        output_schema: inputOutputSchema
+            .nullish()
+            .transform((v) => (v ? jsonSchemaToZod(v) : undefined)),
+        skills: z
+            .array(z.string())
+            .nullish()
+            .transform((v) => v ?? undefined),
+        mode: z
+            .nativeEnum(ProcessMode)
+            .nullish()
+            .transform((v) => v ?? undefined),
+    }),
 ]);
 export async function loadAgentFromYamlFile(path) {
     const raw = await tryOrThrow(() => nodejs.fs.readFile(path, "utf8"), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
     const json = await tryOrThrow(() => parse(raw), (error) => new Error(`Failed to parse agent definition from ${path}: ${error.message}`));
-    const agent = tryOrThrow(() => customCamelize(agentFileSchema.parse({
+    const agent = await tryOrThrow(async () => customCamelize(await agentFileSchema.parseAsync({
         ...json,
         type: json.type ?? "ai",
         skills: json.skills ?? json.tools,
     }), {
         shallowKeys: ["input_schema", "output_schema"],
     }), (error) => new Error(`Failed to validate agent definition from ${path}: ${error.message}`));
+    if (agent.type === "ai") {
+        return {
+            ...agent,
+            instructions: typeof agent.instructions === "object" && "url" in agent.instructions
+                ? await nodejs.fs.readFile(nodejs.path.join(nodejs.path.dirname(path), agent.instructions.url), "utf8")
+                : agent.instructions,
+        };
+    }
     return agent;
 }

package/lib/esm/loader/index.d.ts

@@ -1,6 +1,6 @@
 import type { Camelize } from "camelize-ts";
 import { z } from "zod";
-import { type Agent } from "../agents/agent.js";
+import { Agent } from "../agents/agent.js";
 import type { ChatModel, ChatModelOptions } from "../agents/chat-model.js";
 import type { MemoryAgent, MemoryAgentOptions } from "../memory/memory.js";
 export interface LoadOptions {

package/lib/esm/loader/index.js

@@ -1,9 +1,10 @@
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { parse } from "yaml";
 import { z } from "zod";
-import { FunctionAgent } from "../agents/agent.js";
+import { Agent, FunctionAgent } from "../agents/agent.js";
 import { AIAgent } from "../agents/ai-agent.js";
 import { MCPAgent } from "../agents/mcp-agent.js";
+import { TeamAgent } from "../agents/team-agent.js";
 import { tryOrThrow } from "../utils/type-utils.js";
 import { loadAgentFromJsFile } from "./agent-js.js";
 import { loadAgentFromYamlFile } from "./agent-yaml.js";
@@ -22,20 +23,25 @@ export async function load(options) {
     };
 }
 export async function loadAgent(path, options) {
-    if (nodejs.path.extname(path) === ".js") {
+    if ([".js", ".mjs", ".ts", ".mts"].includes(nodejs.path.extname(path))) {
         const agent = await loadAgentFromJsFile(path);
+        if (agent instanceof Agent)
+            return agent;
         return FunctionAgent.from(agent);
     }
-    if (nodejs.path.extname(path) === ".yaml" || nodejs.path.extname(path) === ".yml") {
+    if ([".yml", ".yaml"].includes(nodejs.path.extname(path))) {
         const agent = await loadAgentFromYamlFile(path);
+        const skills = "skills" in agent
+            ? agent.skills &&
+                (await Promise.all(agent.skills.map((filename) => loadAgent(nodejs.path.join(nodejs.path.dirname(path), filename), options))))
+            : undefined;
         if (agent.type === "ai") {
             return AIAgent.from({
                 ...agent,
                 memory: !options?.memories?.length || !agent.memory
                     ? undefined
                     : await loadMemory(options.memories, typeof agent.memory === "object" ? agent.memory.provider : undefined, typeof agent.memory === "object" ? agent.memory : {}),
-                skills: agent.skills &&
-                    (await Promise.all(agent.skills.map((filename) => loadAgent(nodejs.path.join(nodejs.path.dirname(path), filename), options)))),
+                skills,
             });
         }
         if (agent.type === "mcp") {
@@ -52,6 +58,12 @@ export async function loadAgent(path, options) {
             }
             throw new Error(`Missing url or command in mcp agent: ${path}`);
         }
+        if (agent.type === "team") {
+            return TeamAgent.from({
+                ...agent,
+                skills,
+            });
+        }
     }
     throw new Error(`Unsupported agent file type: ${path}`);
 }

package/lib/esm/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/esm/memory/memory.js

@@ -12,6 +12,7 @@ export const newMemoryId = () => v7();
  * instead provides memory management capabilities to the system.
  */
 export class MemoryAgent extends Agent {
+    tag = "MemoryAgent";
     /**
      * Creates a new MemoryAgent instance.
      */

package/lib/esm/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/esm/memory/recorder.js

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