/** * @license * Copyright 2026 Steven Roussey * SPDX-License-Identifier: Apache-2.0 */ import { CreateWorkflow } from "@workglow/task-graph"; import type { IExecuteContext, IRunConfig, StreamEvent, TaskConfig } from "@workglow/task-graph"; import { ServiceRegistry } from "@workglow/util"; import { DataPortSchema } from "@workglow/util/schema"; import type { AiJobInput } from "../job/AiJob"; import type { ModelConfig } from "../model/ModelSchema"; import { StreamingAiTask } from "./base/StreamingAiTask"; import type { ChatMessage } from "./ChatMessage"; import type { ToolDefinition } from "./ToolCallingUtils"; export interface ToolDefinitionWithTaskType extends ToolDefinition { /** The task type name this definition was generated from. */ readonly taskType: string; } /** * Converts an allow-list of task type names into {@link ToolDefinitionWithTaskType} objects * suitable for the ToolCallingTask input. Each entry carries the originating * `taskType` so callers don't need to rely on index correspondence. * * Each task's `type`, `description`, `inputSchema()`, and `outputSchema()` * are used to build the tool definition. * * @param taskNames - Array of task type names registered in the task constructors * @param registry - Optional service registry for DI-based lookups * @returns Array of ToolDefinitionWithTaskType objects * @throws Error if a task name is not found in the registry */ export declare function taskTypesToTools(taskNames: ReadonlyArray, registry?: ServiceRegistry): ToolDefinitionWithTaskType[]; export declare const ToolDefinitionSchema: { 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; }; export declare const ToolCallingInputSchema: { readonly type: "object"; readonly properties: { readonly model: { readonly oneOf: readonly [{ readonly title: "Model"; readonly description: `The model ${string}`; } & Record & { readonly format: import(".").TypeModelSemantic; readonly type: "string"; }, { readonly type: "object"; readonly properties: { readonly model_id: { readonly type: "string"; }; readonly capabilities: { 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 native_dimensions: { readonly type: "integer"; readonly description: "Native output vector dimensions for embedding models"; }; readonly mrl: { readonly type: "boolean"; readonly description: "Whether the model supports Matryoshka Representation Learning"; }; }; 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; } & Record & { readonly format: import(".").TypeModelSemantic; }]; } & Record & { readonly format: import(".").TypeModelSemantic; }; readonly prompt: { readonly oneOf: readonly [{ readonly type: "string"; readonly title: "Prompt"; readonly description: "The prompt to send to the model"; }, { readonly type: "array"; readonly title: "Prompt"; readonly description: "The prompt as an array of strings or content blocks"; readonly items: { readonly oneOf: readonly [{ readonly type: "string"; }, { 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 prompt to send to the model"; }; readonly systemPrompt: { readonly type: "string"; readonly title: "System Prompt"; readonly description: "Optional system instructions for the model"; }; readonly messages: { readonly type: "array"; readonly title: "Messages"; readonly description: "Full conversation history for multi-turn interactions. When provided, used instead of prompt to construct the messages array sent to the provider."; readonly items: { readonly type: "object"; readonly properties: { readonly role: { readonly type: "string"; readonly enum: readonly ["user", "assistant", "tool", "system"]; }; readonly content: { readonly type: "array"; readonly items: { readonly oneOf: readonly [{ readonly type: "object"; readonly properties: { readonly type: { readonly type: "string"; readonly enum: readonly ["text"]; }; readonly text: { readonly type: "string"; }; }; readonly required: readonly ["type", "text"]; readonly additionalProperties: false; }, { readonly type: "object"; readonly properties: { readonly type: { readonly type: "string"; readonly enum: readonly ["image"]; }; readonly mimeType: { readonly type: "string"; }; readonly data: { readonly type: "string"; }; }; readonly required: readonly ["type", "mimeType", "data"]; readonly additionalProperties: false; }, { readonly type: "object"; readonly properties: { readonly type: { readonly type: "string"; readonly enum: readonly ["tool_use"]; }; readonly id: { readonly type: "string"; }; readonly name: { readonly type: "string"; }; readonly input: { readonly type: "object"; readonly additionalProperties: true; }; }; readonly required: readonly ["type", "id", "name", "input"]; readonly additionalProperties: false; }, { readonly type: "object"; readonly properties: { readonly type: { readonly type: "string"; readonly enum: readonly ["tool_result"]; }; readonly tool_use_id: { readonly type: "string"; }; readonly content: { readonly type: "array"; readonly items: { readonly oneOf: readonly [{ readonly type: "object"; readonly properties: { readonly type: { readonly type: "string"; readonly enum: readonly ["text"]; }; readonly text: { readonly type: "string"; }; }; readonly required: readonly ["type", "text"]; readonly additionalProperties: false; }, { readonly type: "object"; readonly properties: { readonly type: { readonly type: "string"; readonly enum: readonly ["image"]; }; readonly mimeType: { readonly type: "string"; }; readonly data: { readonly type: "string"; }; }; readonly required: readonly ["type", "mimeType", "data"]; readonly additionalProperties: false; }, { readonly type: "object"; readonly properties: { readonly type: { readonly type: "string"; readonly enum: readonly ["tool_use"]; }; readonly id: { readonly type: "string"; }; readonly name: { readonly type: "string"; }; readonly input: { readonly type: "object"; readonly additionalProperties: true; }; }; readonly required: readonly ["type", "id", "name", "input"]; readonly additionalProperties: false; }]; }; }; readonly is_error: { readonly type: "boolean"; }; }; readonly required: readonly ["type", "tool_use_id", "content"]; readonly additionalProperties: false; }]; readonly title: "ContentBlock"; readonly description: "A single content block within a chat message"; }; }; }; readonly required: readonly ["role", "content"]; readonly additionalProperties: false; readonly title: "ChatMessage"; readonly description: "A single chat message with role and structured content blocks"; }; }; readonly tools: { readonly type: "array"; readonly format: "tasks"; readonly title: "Tools"; readonly description: "Tool definitions available for the model to call"; 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 toolChoice: { readonly type: "string"; readonly title: "Tool Choice"; readonly description: 'Controls tool selection: "auto" (model decides), "none" (no tools), "required" (must call a tool), or a specific tool name'; readonly "x-ui-group": "Configuration"; }; readonly maxTokens: { readonly type: "number"; readonly title: "Max Tokens"; readonly description: "The maximum number of tokens to generate"; readonly minimum: 1; readonly "x-ui-group": "Configuration"; }; readonly temperature: { readonly type: "number"; readonly title: "Temperature"; readonly description: "The temperature to use for sampling"; readonly minimum: 0; readonly maximum: 2; readonly "x-ui-group": "Configuration"; }; }; readonly required: readonly ["model", "prompt", "tools"]; readonly additionalProperties: false; }; export declare const ToolCallingOutputSchema: { readonly type: "object"; readonly properties: { readonly text: { readonly type: "string"; readonly title: "Text"; readonly description: "Any text content generated by the model"; readonly "x-stream": "append"; }; readonly toolCalls: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly id: { readonly type: "string"; readonly title: "ID"; readonly description: "Unique identifier for this tool call"; }; readonly name: { readonly type: "string"; readonly title: "Name"; readonly description: "The name of the tool to invoke"; }; readonly input: { readonly type: "object"; readonly title: "Input"; readonly description: "The input arguments for the tool call"; readonly additionalProperties: true; }; }; readonly required: readonly ["id", "name", "input"]; readonly additionalProperties: false; }; readonly title: "Tool Calls"; readonly description: "Tool calls requested by the model"; readonly "x-stream": "object"; }; }; readonly required: readonly ["text", "toolCalls"]; readonly additionalProperties: false; }; /** * Runtime input type for ToolCallingTask. * * The schema uses `oneOf: [string, object]` so the UI can accept both task-name * references and inline tool definitions, but the input resolver converts all * strings to {@link ToolDefinition} objects before execution. The `tools` field * is therefore narrowed to `ToolDefinition[]` here. * * Extends the schema-derived base with the * `messages` field typed explicitly (the loose `content: {}` in the * schema prevents `FromSchema` from producing a useful type). */ export type ToolCallingTaskInput = Omit<{ systemPrompt?: string | undefined; messages?: ChatMessage[] | undefined; toolChoice?: string | undefined; maxTokens?: number | undefined; temperature?: number | undefined; model: string | ModelConfig; prompt: string | (string | { [x: string]: unknown; type: "text" | "image" | "audio"; })[]; tools: (string | { [x: string]: unknown; outputSchema?: { [x: string]: unknown; } | undefined; configSchema?: { [x: string]: unknown; } | undefined; config?: { [x: string]: unknown; } | undefined; description: string; name: string; inputSchema: { [x: string]: unknown; }; })[]; }, "messages" | "tools"> & { readonly tools: ToolDefinition[]; readonly messages?: ReadonlyArray; readonly sessionId?: string; }; export type ToolCallingTaskOutput = { text: string; toolCalls: { id: string; name: string; input: { [x: string]: unknown; }; }[]; }; export type ToolCallingTaskConfig = TaskConfig; export declare class ToolCallingTask extends StreamingAiTask { static type: string; /** Capabilities required of the model; gated in {@link StreamingAiTask.executeStream}. */ static readonly requires: ["tool-use"]; protected static readonly streamingPhaseLabel = "Generating"; static category: string; static title: string; static description: string; static inputSchema(): DataPortSchema; static outputSchema(): DataPortSchema; /** Session ID computed during getJobInput, used to register cleanup. */ private _computedSessionId; /** * Override to auto-compute a prefix-rewind session ID from tools + systemPrompt * + runnerId when no explicit sessionId is provided. The runnerId scopes the * cache to the current graph run so it's cleaned up via ResourceScope. */ protected getJobInput(input: ToolCallingTaskInput): Promise>; private registerSessionDispose; execute(input: ToolCallingTaskInput, executeContext: IExecuteContext): Promise; executeStream(input: ToolCallingTaskInput, context: IExecuteContext): AsyncIterable>; } export declare const toolCalling: (input: ToolCallingTaskInput, config?: ToolCallingTaskConfig, runConfig?: Partial) => Promise; declare module "@workglow/task-graph" { interface Workflow { toolCalling: CreateWorkflow; } } //# sourceMappingURL=ToolCallingTask.d.ts.map