@workglow/ai 0.0.116 → 0.0.118

package/dist/task/AgentTask.d.ts

@@ -0,0 +1,524 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CreateWorkflow, Task, type IExecuteContext, type StreamEvent, type TaskConfig } from "@workglow/task-graph";
+import type { AgentHooks, ChatMessage, UserContentBlock } from "./AgentTypes";
+import type { ToolDefinition } from "./ToolCallingTask";
+export interface AgentTaskConfig extends TaskConfig {
+    /** Lifecycle hooks for intercepting the agent loop. */
+    readonly hooks?: AgentHooks;
+    /** Max concurrent tool executions per iteration (default: 5). */
+    readonly maxConcurrency?: number;
+}
+/**
+ * Input for the AgentTask. The JSON Schema ({@link AgentInputSchema}) is
+ * used for runtime validation and UI; this interface is the TypeScript
+ * source of truth.
+ *
+ * Tools follow the same resolution pattern as `model`: each entry is
+ * either a **string** (task type name resolved from the TaskRegistry) or
+ * a full **{@link ToolDefinition}** object. Configurable tasks (e.g.
+ * `McpToolCallTask`, `JavaScriptTask`) can be pre-configured via the
+ * `config` field on the definition — the LLM never sees this config.
+ */
+export interface AgentTaskInput {
+    readonly [key: string]: unknown;
+    readonly model: string;
+    readonly prompt: string | ReadonlyArray<UserContentBlock>;
+    readonly systemPrompt?: string;
+    /**
+     * Tools available to the agent. Each entry is either:
+     * - A **string** — resolved from the TaskRegistry by name (like `model`).
+     * - A **{@link ToolDefinition}** — inline definition with optional `config`
+     *   for configurable tasks and optional `execute` for custom function tools.
+     */
+    readonly tools?: ReadonlyArray<string | ToolDefinition>;
+    readonly maxIterations?: number;
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    /**
+     * Name of a "stop tool". When the LLM calls this tool the agent loop
+     * ends and the tool's input becomes the {@link AgentTaskOutput.structuredOutput}.
+     * If no tool source with this name exists, a synthetic definition is
+     * added automatically.
+     */
+    readonly stopTool?: string;
+    /**
+     * Maximum number of messages to keep in the conversation window sent
+     * to the LLM. When exceeded, the oldest messages (after the initial
+     * user message) are dropped. Helps prevent context-window overflow.
+     */
+    readonly maxContextMessages?: number;
+}
+export interface AgentTaskOutput {
+    readonly [key: string]: unknown;
+    readonly text: string;
+    readonly messages: ReadonlyArray<ChatMessage>;
+    readonly iterations: number;
+    readonly toolCallCount: number;
+    /** Present when the agent terminated via a stop tool. */
+    readonly structuredOutput?: Record<string, unknown>;
+}
+export declare const AgentInputSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly model: {
+            readonly oneOf: readonly [{
+                readonly title: "Model";
+                readonly description: `The model ${string}`;
+            } & {
+                readonly format: import(".").TypeModelSemantic;
+                readonly type: "string";
+            }, {
+                readonly type: "object";
+                readonly properties: {
+                    readonly model_id: {
+                        readonly type: "string";
+                    };
+                    readonly tasks: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly "x-ui-editor": "multiselect";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                        readonly "x-ui-editor": "textarea";
+                    };
+                    readonly provider: {
+                        readonly type: "string";
+                    };
+                    readonly provider_config: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly credential_key: {
+                                readonly type: "string";
+                                readonly format: "credential";
+                                readonly "x-ui-hidden": true;
+                            };
+                        };
+                        readonly additionalProperties: true;
+                        readonly default: {};
+                    };
+                    readonly metadata: {
+                        readonly type: "object";
+                        readonly default: {};
+                        readonly "x-ui-hidden": true;
+                    };
+                };
+                readonly required: readonly ["provider", "provider_config"];
+                readonly format: "model";
+                readonly additionalProperties: true;
+            } & {
+                readonly format: import(".").TypeModelSemantic;
+            }];
+        } & {
+            readonly format: import(".").TypeModelSemantic;
+        };
+        readonly prompt: {
+            readonly oneOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly type: {
+                            readonly type: "string";
+                            readonly enum: readonly ["text", "image", "audio"];
+                        };
+                    };
+                    readonly required: readonly ["type"];
+                    readonly additionalProperties: true;
+                };
+            }];
+            readonly title: "Prompt";
+            readonly description: "The user prompt to start the agent loop. Can be a string or an array of content blocks (text, image, audio).";
+        };
+        readonly systemPrompt: {
+            readonly type: "string";
+            readonly title: "System Prompt";
+            readonly description: "Optional system instructions for the agent";
+        };
+        readonly tools: {
+            readonly type: "array";
+            readonly format: "tasks";
+            readonly title: "Tools";
+            readonly description: "Tools available to the agent. Each entry is a task type name (string, resolved from TaskRegistry) or a full ToolDefinition object with optional config for configurable tasks.";
+            readonly items: {
+                readonly oneOf: readonly [{
+                    readonly type: "string";
+                    readonly format: "tasks";
+                    readonly description: "Task type name";
+                }, {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly name: {
+                            readonly type: "string";
+                            readonly title: "Name";
+                            readonly description: "The tool name";
+                        };
+                        readonly description: {
+                            readonly type: "string";
+                            readonly title: "Description";
+                            readonly description: "A description of what the tool does";
+                        };
+                        readonly inputSchema: {
+                            readonly type: "object";
+                            readonly title: "Input Schema";
+                            readonly description: "JSON Schema describing the tool's input parameters";
+                            readonly additionalProperties: true;
+                        };
+                        readonly outputSchema: {
+                            readonly type: "object";
+                            readonly title: "Output Schema";
+                            readonly description: "JSON Schema describing what the tool returns";
+                            readonly additionalProperties: true;
+                        };
+                        readonly configSchema: {
+                            readonly type: "object";
+                            readonly title: "Config Schema";
+                            readonly description: "JSON Schema describing the task's configuration options (not sent to the LLM)";
+                            readonly additionalProperties: true;
+                        };
+                        readonly config: {
+                            readonly type: "object";
+                            readonly title: "Config";
+                            readonly description: "Concrete configuration values for the backing task (not sent to the LLM)";
+                            readonly additionalProperties: true;
+                        };
+                    };
+                    readonly required: readonly ["name", "description", "inputSchema"];
+                    readonly additionalProperties: true;
+                }];
+            };
+        };
+        readonly stopTool: {
+            readonly type: "string";
+            readonly title: "Stop Tool";
+            readonly description: "Name of a tool that signals agent completion. When called, the loop ends and the tool input becomes structuredOutput.";
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly maxIterations: {
+            readonly type: "number";
+            readonly title: "Max Iterations";
+            readonly description: "Maximum number of agent loop iterations (default: 10)";
+            readonly minimum: 1;
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly maxContextMessages: {
+            readonly type: "number";
+            readonly title: "Max Context Messages";
+            readonly description: "Maximum messages in conversation history. Older messages are trimmed to prevent context overflow.";
+            readonly minimum: 3;
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly maxTokens: {
+            readonly type: "number";
+            readonly title: "Max Tokens";
+            readonly description: "Maximum tokens per LLM call";
+            readonly minimum: 1;
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly temperature: {
+            readonly type: "number";
+            readonly title: "Temperature";
+            readonly description: "Sampling temperature for LLM calls";
+            readonly minimum: 0;
+            readonly maximum: 2;
+            readonly "x-ui-group": "Configuration";
+        };
+    };
+    readonly required: readonly ["model", "prompt"];
+    readonly additionalProperties: false;
+};
+export declare const AgentOutputSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly text: {
+            readonly type: "string";
+            readonly title: "Text";
+            readonly description: "The final text response from the agent";
+            readonly "x-stream": "append";
+        };
+        readonly messages: {
+            readonly type: "array";
+            readonly title: "Messages";
+            readonly description: "Full conversation history including all tool calls and results";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: true;
+            };
+        };
+        readonly iterations: {
+            readonly type: "number";
+            readonly title: "Iterations";
+            readonly description: "Number of LLM calls made during the agent loop";
+        };
+        readonly toolCallCount: {
+            readonly type: "number";
+            readonly title: "Tool Call Count";
+            readonly description: "Total number of tool calls executed";
+        };
+        readonly structuredOutput: {
+            readonly type: "object";
+            readonly title: "Structured Output";
+            readonly description: "Present when the agent terminated via a stop tool";
+            readonly additionalProperties: true;
+        };
+    };
+    readonly required: readonly ["text", "messages", "iterations", "toolCallCount"];
+    readonly additionalProperties: false;
+};
+export declare class AgentTask extends Task<AgentTaskInput, AgentTaskOutput, AgentTaskConfig> {
+    static type: string;
+    static category: string;
+    static title: string;
+    static description: string;
+    static cacheable: boolean;
+    static inputSchema(): {
+        readonly type: "object";
+        readonly properties: {
+            readonly model: {
+                readonly oneOf: readonly [{
+                    readonly title: "Model";
+                    readonly description: `The model ${string}`;
+                } & {
+                    readonly format: import(".").TypeModelSemantic;
+                    readonly type: "string";
+                }, {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly model_id: {
+                            readonly type: "string";
+                        };
+                        readonly tasks: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                            readonly "x-ui-editor": "multiselect";
+                        };
+                        readonly title: {
+                            readonly type: "string";
+                        };
+                        readonly description: {
+                            readonly type: "string";
+                            readonly "x-ui-editor": "textarea";
+                        };
+                        readonly provider: {
+                            readonly type: "string";
+                        };
+                        readonly provider_config: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly credential_key: {
+                                    readonly type: "string";
+                                    readonly format: "credential";
+                                    readonly "x-ui-hidden": true;
+                                };
+                            };
+                            readonly additionalProperties: true;
+                            readonly default: {};
+                        };
+                        readonly metadata: {
+                            readonly type: "object";
+                            readonly default: {};
+                            readonly "x-ui-hidden": true;
+                        };
+                    };
+                    readonly required: readonly ["provider", "provider_config"];
+                    readonly format: "model";
+                    readonly additionalProperties: true;
+                } & {
+                    readonly format: import(".").TypeModelSemantic;
+                }];
+            } & {
+                readonly format: import(".").TypeModelSemantic;
+            };
+            readonly prompt: {
+                readonly oneOf: readonly [{
+                    readonly type: "string";
+                }, {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly type: {
+                                readonly type: "string";
+                                readonly enum: readonly ["text", "image", "audio"];
+                            };
+                        };
+                        readonly required: readonly ["type"];
+                        readonly additionalProperties: true;
+                    };
+                }];
+                readonly title: "Prompt";
+                readonly description: "The user prompt to start the agent loop. Can be a string or an array of content blocks (text, image, audio).";
+            };
+            readonly systemPrompt: {
+                readonly type: "string";
+                readonly title: "System Prompt";
+                readonly description: "Optional system instructions for the agent";
+            };
+            readonly tools: {
+                readonly type: "array";
+                readonly format: "tasks";
+                readonly title: "Tools";
+                readonly description: "Tools available to the agent. Each entry is a task type name (string, resolved from TaskRegistry) or a full ToolDefinition object with optional config for configurable tasks.";
+                readonly items: {
+                    readonly oneOf: readonly [{
+                        readonly type: "string";
+                        readonly format: "tasks";
+                        readonly description: "Task type name";
+                    }, {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly name: {
+                                readonly type: "string";
+                                readonly title: "Name";
+                                readonly description: "The tool name";
+                            };
+                            readonly description: {
+                                readonly type: "string";
+                                readonly title: "Description";
+                                readonly description: "A description of what the tool does";
+                            };
+                            readonly inputSchema: {
+                                readonly type: "object";
+                                readonly title: "Input Schema";
+                                readonly description: "JSON Schema describing the tool's input parameters";
+                                readonly additionalProperties: true;
+                            };
+                            readonly outputSchema: {
+                                readonly type: "object";
+                                readonly title: "Output Schema";
+                                readonly description: "JSON Schema describing what the tool returns";
+                                readonly additionalProperties: true;
+                            };
+                            readonly configSchema: {
+                                readonly type: "object";
+                                readonly title: "Config Schema";
+                                readonly description: "JSON Schema describing the task's configuration options (not sent to the LLM)";
+                                readonly additionalProperties: true;
+                            };
+                            readonly config: {
+                                readonly type: "object";
+                                readonly title: "Config";
+                                readonly description: "Concrete configuration values for the backing task (not sent to the LLM)";
+                                readonly additionalProperties: true;
+                            };
+                        };
+                        readonly required: readonly ["name", "description", "inputSchema"];
+                        readonly additionalProperties: true;
+                    }];
+                };
+            };
+            readonly stopTool: {
+                readonly type: "string";
+                readonly title: "Stop Tool";
+                readonly description: "Name of a tool that signals agent completion. When called, the loop ends and the tool input becomes structuredOutput.";
+                readonly "x-ui-group": "Configuration";
+            };
+            readonly maxIterations: {
+                readonly type: "number";
+                readonly title: "Max Iterations";
+                readonly description: "Maximum number of agent loop iterations (default: 10)";
+                readonly minimum: 1;
+                readonly "x-ui-group": "Configuration";
+            };
+            readonly maxContextMessages: {
+                readonly type: "number";
+                readonly title: "Max Context Messages";
+                readonly description: "Maximum messages in conversation history. Older messages are trimmed to prevent context overflow.";
+                readonly minimum: 3;
+                readonly "x-ui-group": "Configuration";
+            };
+            readonly maxTokens: {
+                readonly type: "number";
+                readonly title: "Max Tokens";
+                readonly description: "Maximum tokens per LLM call";
+                readonly minimum: 1;
+                readonly "x-ui-group": "Configuration";
+            };
+            readonly temperature: {
+                readonly type: "number";
+                readonly title: "Temperature";
+                readonly description: "Sampling temperature for LLM calls";
+                readonly minimum: 0;
+                readonly maximum: 2;
+                readonly "x-ui-group": "Configuration";
+            };
+        };
+        readonly required: readonly ["model", "prompt"];
+        readonly additionalProperties: false;
+    };
+    static outputSchema(): {
+        readonly type: "object";
+        readonly properties: {
+            readonly text: {
+                readonly type: "string";
+                readonly title: "Text";
+                readonly description: "The final text response from the agent";
+                readonly "x-stream": "append";
+            };
+            readonly messages: {
+                readonly type: "array";
+                readonly title: "Messages";
+                readonly description: "Full conversation history including all tool calls and results";
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: true;
+                };
+            };
+            readonly iterations: {
+                readonly type: "number";
+                readonly title: "Iterations";
+                readonly description: "Number of LLM calls made during the agent loop";
+            };
+            readonly toolCallCount: {
+                readonly type: "number";
+                readonly title: "Tool Call Count";
+                readonly description: "Total number of tool calls executed";
+            };
+            readonly structuredOutput: {
+                readonly type: "object";
+                readonly title: "Structured Output";
+                readonly description: "Present when the agent terminated via a stop tool";
+                readonly additionalProperties: true;
+            };
+        };
+        readonly required: readonly ["text", "messages", "iterations", "toolCallCount"];
+        readonly additionalProperties: false;
+    };
+    execute(input: AgentTaskInput, context: IExecuteContext): Promise<AgentTaskOutput>;
+    executeStream(input: AgentTaskInput, context: IExecuteContext): AsyncIterable<StreamEvent<AgentTaskOutput>>;
+    private agentLoop;
+    private resolveToolSources;
+    /**
+     * Build the tool definitions to send to the LLM.
+     * If a stopTool is configured and no matching source exists, adds a
+     * synthetic tool definition so the LLM can call it.
+     */
+    private resolveToolDefs;
+    /**
+     * Trim messages to stay within maxContextMessages.
+     * Keeps the first message (initial user prompt) and the most recent
+     * messages. Trims at assistant/tool pair boundaries so that a
+     * tool_use message is never separated from its tool_result message.
+     */
+    private trimMessages;
+}
+export declare const agent: (input: AgentTaskInput, config?: AgentTaskConfig) => Promise<AgentTaskOutput>;
+declare module "@workglow/task-graph" {
+    interface Workflow {
+        agent: CreateWorkflow<AgentTaskInput, AgentTaskOutput, AgentTaskConfig>;
+    }
+}
+//# sourceMappingURL=AgentTask.d.ts.map

package/dist/task/AgentTask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentTask.d.ts","sourceRoot":"","sources":["../../src/task/AgentTask.ts"],"names":[],"mappings":"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"}