@upstash/workflow 0.2.5-agents → 0.2.5-agents-2

package/{types-BEyIoCRe.d.mts → types-D9gwTj2n.d.mts}

@@ -2,7 +2,6 @@ import { PublishRequest, Client, Receiver, HTTPMethods as HTTPMethods$1 } from '
 import * as ai from 'ai';
 import { CoreTool, generateText } from 'ai';
 import * as _ai_sdk_openai from '@ai-sdk/openai';
-import { Tool } from 'langchain/tools';
 
 /**
  * Base class outlining steps. Basically, each step kind (run/sleep/sleepUntil)
@@ -391,53 +390,155 @@ declare class WorkflowApi extends BaseWorkflowApi {
     get anthropic(): AnthropicAPI;
 }
 
+/**
+ * An Agent which utilizes the model and tools available to it
+ * to achieve a given task
+ *
+ * @param name Name of the agent
+ * @param background Background of the agent
+ * @param model LLM model to use
+ * @param tools tools available to the agent
+ * @param maxSteps number of times the agent can call the LLM at most. If
+ *   the agent abruptly stops execution after calling tools, you may need
+ *   to increase maxSteps
+ * @param temparature temparature used when calling the LLM
+ */
 declare class Agent {
     readonly name: AgentParameters["name"];
     readonly tools: AgentParameters["tools"];
     readonly maxSteps: AgentParameters["maxSteps"];
     readonly background: AgentParameters["background"];
     readonly model: AgentParameters["model"];
-    constructor({ tools, maxSteps, background, name, model }: AgentParameters);
+    readonly temparature: AgentParameters["temparature"];
+    constructor({ tools, maxSteps, background, name, model, temparature }: AgentParameters);
+    /**
+     * Trigger the agent by passing a prompt
+     *
+     * @param prompt task to assign to the agent
+     * @returns Response as `{ text: string }`
+     */
     call({ prompt }: {
         prompt: string;
-    }): Promise<ai.GenerateTextResult<Record<string, AISDKTool>, never>>;
+    }): Promise<{
+        text: string;
+    }>;
+    /**
+     * Convert the agent to a tool which can be used by other agents.
+     *
+     * @returns the agent as a tool
+     */
     asTool(): AISDKTool;
 }
-type ManagerAgentParameters = {
-    agents: Agent[];
-    model: Model;
-} & Pick<Partial<AgentParameters>, "name" | "background"> & Pick<AgentParameters, "maxSteps">;
-declare class ManagerAgent extends Agent {
-    agents: ManagerAgentParameters["agents"];
-    constructor({ maxSteps, background, agents, model, name, }: ManagerAgentParameters);
-}
 
 type AISDKTool = CoreTool;
-type LangchainTool = Tool;
+type LangchainTool = {
+    description: string;
+    schema: AISDKTool["parameters"];
+    invoke: (...params: any[]) => any;
+};
 type GenerateTextParams = Parameters<typeof generateText>[0];
 type Model = GenerateTextParams["model"];
 type AgentParameters<TTool extends AISDKTool | LangchainTool = AISDKTool> = {
+    /**
+     * number of times the agent can call the LLM at most. If
+     * the agent abruptly stops execution after calling tools, you may need
+     * to increase maxSteps
+     */
     maxSteps: number;
+    /**
+     * Background of the agent
+     */
     background: string;
+    /**
+     * tools available to the agent
+     */
     tools: Record<string, TTool>;
+    /**
+     * Name of the agent
+     */
     name: string;
+    /**
+     * LLM model to use
+     */
     model: Model;
+    /**
+     * temparature used when calling the LLM
+     *
+     * @default 0.1
+     */
+    temparature?: number;
 };
 type TaskParams = {
+    /**
+     * task assigned to the agent
+     */
     prompt: string;
 };
 type SingleAgentTaskParams = TaskParams & {
+    /**
+     * agent to perform the task
+     */
     agent: Agent;
 };
 type MultiAgentTaskParams = TaskParams & {
+    /**
+     * Agents which will collaborate to achieve the task
+     */
     agents: Agent[];
+    /**
+     * number of times the manager agent can call the LLM at most.
+     * If the agent abruptly stops execution after calling other agents, you may
+     * need to increase maxSteps
+     */
     maxSteps: number;
+    /**
+     * LLM model to use
+     */
     model: Model;
+    /**
+     * Background of the agent. If not passed, default will be used.
+     */
     background?: string;
 };
 
+/**
+ * creates an AI SDK openai client with a custom
+ * fetch implementation which uses context.call.
+ *
+ * @param context workflow context
+ * @returns ai sdk openai
+ */
 declare const createWorkflowOpenAI: (context: WorkflowContext) => _ai_sdk_openai.OpenAIProvider;
 
+/**
+ * An Agent Task
+ *
+ * Can be run to make the agent(s) complete it using the tools available to them
+ *
+ * Can consist of a single agent or multiple agents.
+ *
+ * Single agent:
+ *
+ * ```ts
+ * const task = context.agents.task({
+ *   agent: researcherAgent,
+ *   prompt: "Tell me about 5 topics in advanced physics.",
+ * });
+ * const { text } = await task.run();
+ * ```
+ *
+ * Multi Agent:
+ *
+ * ```ts
+ * const task = context.agents.task({
+ *   model,
+ *   maxSteps: 3,
+ *   agents: [researcherAgent, mathAgent],
+ *   prompt: "Tell me about 3 cities in Japan and calculate the sum of their populations",
+ * });
+ * const { text } = await task.run();
+ * ```
+ */
 declare class Task {
     private readonly context;
     private readonly taskParameters;
@@ -445,19 +546,80 @@ declare class Task {
         context: WorkflowContext;
         taskParameters: SingleAgentTaskParams | MultiAgentTaskParams;
     });
+    /**
+     * Run the agents to complete the task
+     *
+     * @returns Result of the task as { text: string }
+     */
     run(): Promise<{
         text: string;
     }>;
 }
 
+/**
+ * Workflow Agents API
+ *
+ * https://upstash.com/docs/workflow/agents/overview
+ *
+ * Allows defining agents which can complete a given task
+ * using tools available to them.
+ */
 declare class WorkflowAgents {
     private context;
     constructor({ context }: {
         context: WorkflowContext;
     });
+    /**
+     * Defines an agent
+     *
+     * ```ts
+     * const researcherAgent = context.agents.agent({
+     *   model,
+     *   name: 'academic',
+     *   maxSteps: 2,
+     *   tools: {
+     *     wikiTool: new WikipediaQueryRun({
+     *       topKResults: 1,
+     *       maxDocContentLength: 500,
+     *     })
+     *   },
+     *   background:
+     *     'You are researcher agent with access to Wikipedia. ' +
+     *     'Utilize Wikipedia as much as possible for correct information',
+     * });
+     * ```
+     *
+     * @param params agent parameters
+     * @returns
+     */
     agent(params: AgentParameters<AISDKTool | LangchainTool>): Agent;
+    /**
+     * Defines a task to be executed by a single agent
+     *
+     * ```ts
+     * const task = context.agents.task({
+     *   agent: researcherAgent,
+     *   prompt: "Tell me about 5 topics in advanced physics.",
+     * });
+     * ```
+     */
     task(taskParameters: SingleAgentTaskParams): Task;
+    /**
+     * Defines a task to be executed by multiple collaborating agents
+     *
+     * ```ts
+     * const task = context.agents.task({
+     *  model,
+     *  maxSteps: 3,
+     *  agents: [researcherAgent, mathAgent],
+     *  prompt: "Tell me about 3 cities in Japan and calculate the sum of their populations",
+     * });
+     * ```
+     */
     task(taskParameters: MultiAgentTaskParams): Task;
+    /**
+     * creates an openai model for agents
+     */
     openai(...params: Parameters<ReturnType<typeof createWorkflowOpenAI>>): ai.LanguageModelV1;
 }
 
@@ -1132,4 +1294,4 @@ type HeaderParams = {
     callTimeout?: never;
 });
 
-export { type AsyncStepFunction as A, type CallResponse as C, type Duration as D, type FinishCondition as F, type HeaderParams as H, type LogLevel as L, ManagerAgent as M, type NotifyResponse as N, type ParallelCallState as P, type RouteFunction as R, type Step as S, type Telemetry as T, type WorkflowServeOptions as W, type Waiter as a, WorkflowContext as b, type WorkflowClient as c, type WorkflowReceiver as d, StepTypes as e, type StepType as f, type RawStep as g, type SyncStepFunction as h, type StepFunction as i, type PublicServeOptions as j, type FailureFunctionPayload as k, type RequiredExceptFields as l, type WaitRequest as m, type WaitStepResponse as n, type NotifyStepResponse as o, type WaitEventOptions as p, type CallSettings as q, type WorkflowLoggerOptions as r, WorkflowLogger as s, WorkflowAgents as t, createWorkflowOpenAI as u, Agent as v };
+export { type AsyncStepFunction as A, type CallResponse as C, type Duration as D, type FinishCondition as F, type HeaderParams as H, type LogLevel as L, type NotifyResponse as N, type ParallelCallState as P, type RouteFunction as R, type Step as S, type Telemetry as T, type WorkflowServeOptions as W, type Waiter as a, WorkflowContext as b, type WorkflowClient as c, type WorkflowReceiver as d, StepTypes as e, type StepType as f, type RawStep as g, type SyncStepFunction as h, type StepFunction as i, type PublicServeOptions as j, type FailureFunctionPayload as k, type RequiredExceptFields as l, type WaitRequest as m, type WaitStepResponse as n, type NotifyStepResponse as o, type WaitEventOptions as p, type CallSettings as q, type WorkflowLoggerOptions as r, WorkflowLogger as s };

package/{types-BEyIoCRe.d.ts → types-D9gwTj2n.d.ts}

@@ -2,7 +2,6 @@ import { PublishRequest, Client, Receiver, HTTPMethods as HTTPMethods$1 } from '
 import * as ai from 'ai';
 import { CoreTool, generateText } from 'ai';
 import * as _ai_sdk_openai from '@ai-sdk/openai';
-import { Tool } from 'langchain/tools';
 
 /**
  * Base class outlining steps. Basically, each step kind (run/sleep/sleepUntil)
@@ -391,53 +390,155 @@ declare class WorkflowApi extends BaseWorkflowApi {
     get anthropic(): AnthropicAPI;
 }
 
+/**
+ * An Agent which utilizes the model and tools available to it
+ * to achieve a given task
+ *
+ * @param name Name of the agent
+ * @param background Background of the agent
+ * @param model LLM model to use
+ * @param tools tools available to the agent
+ * @param maxSteps number of times the agent can call the LLM at most. If
+ *   the agent abruptly stops execution after calling tools, you may need
+ *   to increase maxSteps
+ * @param temparature temparature used when calling the LLM
+ */
 declare class Agent {
     readonly name: AgentParameters["name"];
     readonly tools: AgentParameters["tools"];
     readonly maxSteps: AgentParameters["maxSteps"];
     readonly background: AgentParameters["background"];
     readonly model: AgentParameters["model"];
-    constructor({ tools, maxSteps, background, name, model }: AgentParameters);
+    readonly temparature: AgentParameters["temparature"];
+    constructor({ tools, maxSteps, background, name, model, temparature }: AgentParameters);
+    /**
+     * Trigger the agent by passing a prompt
+     *
+     * @param prompt task to assign to the agent
+     * @returns Response as `{ text: string }`
+     */
     call({ prompt }: {
         prompt: string;
-    }): Promise<ai.GenerateTextResult<Record<string, AISDKTool>, never>>;
+    }): Promise<{
+        text: string;
+    }>;
+    /**
+     * Convert the agent to a tool which can be used by other agents.
+     *
+     * @returns the agent as a tool
+     */
     asTool(): AISDKTool;
 }
-type ManagerAgentParameters = {
-    agents: Agent[];
-    model: Model;
-} & Pick<Partial<AgentParameters>, "name" | "background"> & Pick<AgentParameters, "maxSteps">;
-declare class ManagerAgent extends Agent {
-    agents: ManagerAgentParameters["agents"];
-    constructor({ maxSteps, background, agents, model, name, }: ManagerAgentParameters);
-}
 
 type AISDKTool = CoreTool;
-type LangchainTool = Tool;
+type LangchainTool = {
+    description: string;
+    schema: AISDKTool["parameters"];
+    invoke: (...params: any[]) => any;
+};
 type GenerateTextParams = Parameters<typeof generateText>[0];
 type Model = GenerateTextParams["model"];
 type AgentParameters<TTool extends AISDKTool | LangchainTool = AISDKTool> = {
+    /**
+     * number of times the agent can call the LLM at most. If
+     * the agent abruptly stops execution after calling tools, you may need
+     * to increase maxSteps
+     */
     maxSteps: number;
+    /**
+     * Background of the agent
+     */
     background: string;
+    /**
+     * tools available to the agent
+     */
     tools: Record<string, TTool>;
+    /**
+     * Name of the agent
+     */
     name: string;
+    /**
+     * LLM model to use
+     */
     model: Model;
+    /**
+     * temparature used when calling the LLM
+     *
+     * @default 0.1
+     */
+    temparature?: number;
 };
 type TaskParams = {
+    /**
+     * task assigned to the agent
+     */
     prompt: string;
 };
 type SingleAgentTaskParams = TaskParams & {
+    /**
+     * agent to perform the task
+     */
     agent: Agent;
 };
 type MultiAgentTaskParams = TaskParams & {
+    /**
+     * Agents which will collaborate to achieve the task
+     */
     agents: Agent[];
+    /**
+     * number of times the manager agent can call the LLM at most.
+     * If the agent abruptly stops execution after calling other agents, you may
+     * need to increase maxSteps
+     */
     maxSteps: number;
+    /**
+     * LLM model to use
+     */
     model: Model;
+    /**
+     * Background of the agent. If not passed, default will be used.
+     */
     background?: string;
 };
 
+/**
+ * creates an AI SDK openai client with a custom
+ * fetch implementation which uses context.call.
+ *
+ * @param context workflow context
+ * @returns ai sdk openai
+ */
 declare const createWorkflowOpenAI: (context: WorkflowContext) => _ai_sdk_openai.OpenAIProvider;
 
+/**
+ * An Agent Task
+ *
+ * Can be run to make the agent(s) complete it using the tools available to them
+ *
+ * Can consist of a single agent or multiple agents.
+ *
+ * Single agent:
+ *
+ * ```ts
+ * const task = context.agents.task({
+ *   agent: researcherAgent,
+ *   prompt: "Tell me about 5 topics in advanced physics.",
+ * });
+ * const { text } = await task.run();
+ * ```
+ *
+ * Multi Agent:
+ *
+ * ```ts
+ * const task = context.agents.task({
+ *   model,
+ *   maxSteps: 3,
+ *   agents: [researcherAgent, mathAgent],
+ *   prompt: "Tell me about 3 cities in Japan and calculate the sum of their populations",
+ * });
+ * const { text } = await task.run();
+ * ```
+ */
 declare class Task {
     private readonly context;
     private readonly taskParameters;
@@ -445,19 +546,80 @@ declare class Task {
         context: WorkflowContext;
         taskParameters: SingleAgentTaskParams | MultiAgentTaskParams;
     });
+    /**
+     * Run the agents to complete the task
+     *
+     * @returns Result of the task as { text: string }
+     */
     run(): Promise<{
         text: string;
     }>;
 }
 
+/**
+ * Workflow Agents API
+ *
+ * https://upstash.com/docs/workflow/agents/overview
+ *
+ * Allows defining agents which can complete a given task
+ * using tools available to them.
+ */
 declare class WorkflowAgents {
     private context;
     constructor({ context }: {
         context: WorkflowContext;
     });
+    /**
+     * Defines an agent
+     *
+     * ```ts
+     * const researcherAgent = context.agents.agent({
+     *   model,
+     *   name: 'academic',
+     *   maxSteps: 2,
+     *   tools: {
+     *     wikiTool: new WikipediaQueryRun({
+     *       topKResults: 1,
+     *       maxDocContentLength: 500,
+     *     })
+     *   },
+     *   background:
+     *     'You are researcher agent with access to Wikipedia. ' +
+     *     'Utilize Wikipedia as much as possible for correct information',
+     * });
+     * ```
+     *
+     * @param params agent parameters
+     * @returns
+     */
     agent(params: AgentParameters<AISDKTool | LangchainTool>): Agent;
+    /**
+     * Defines a task to be executed by a single agent
+     *
+     * ```ts
+     * const task = context.agents.task({
+     *   agent: researcherAgent,
+     *   prompt: "Tell me about 5 topics in advanced physics.",
+     * });
+     * ```
+     */
     task(taskParameters: SingleAgentTaskParams): Task;
+    /**
+     * Defines a task to be executed by multiple collaborating agents
+     *
+     * ```ts
+     * const task = context.agents.task({
+     *  model,
+     *  maxSteps: 3,
+     *  agents: [researcherAgent, mathAgent],
+     *  prompt: "Tell me about 3 cities in Japan and calculate the sum of their populations",
+     * });
+     * ```
+     */
     task(taskParameters: MultiAgentTaskParams): Task;
+    /**
+     * creates an openai model for agents
+     */
     openai(...params: Parameters<ReturnType<typeof createWorkflowOpenAI>>): ai.LanguageModelV1;
 }
 
@@ -1132,4 +1294,4 @@ type HeaderParams = {
     callTimeout?: never;
 });
 
-export { type AsyncStepFunction as A, type CallResponse as C, type Duration as D, type FinishCondition as F, type HeaderParams as H, type LogLevel as L, ManagerAgent as M, type NotifyResponse as N, type ParallelCallState as P, type RouteFunction as R, type Step as S, type Telemetry as T, type WorkflowServeOptions as W, type Waiter as a, WorkflowContext as b, type WorkflowClient as c, type WorkflowReceiver as d, StepTypes as e, type StepType as f, type RawStep as g, type SyncStepFunction as h, type StepFunction as i, type PublicServeOptions as j, type FailureFunctionPayload as k, type RequiredExceptFields as l, type WaitRequest as m, type WaitStepResponse as n, type NotifyStepResponse as o, type WaitEventOptions as p, type CallSettings as q, type WorkflowLoggerOptions as r, WorkflowLogger as s, WorkflowAgents as t, createWorkflowOpenAI as u, Agent as v };
+export { type AsyncStepFunction as A, type CallResponse as C, type Duration as D, type FinishCondition as F, type HeaderParams as H, type LogLevel as L, type NotifyResponse as N, type ParallelCallState as P, type RouteFunction as R, type Step as S, type Telemetry as T, type WorkflowServeOptions as W, type Waiter as a, WorkflowContext as b, type WorkflowClient as c, type WorkflowReceiver as d, StepTypes as e, type StepType as f, type RawStep as g, type SyncStepFunction as h, type StepFunction as i, type PublicServeOptions as j, type FailureFunctionPayload as k, type RequiredExceptFields as l, type WaitRequest as m, type WaitStepResponse as n, type NotifyStepResponse as o, type WaitEventOptions as p, type CallSettings as q, type WorkflowLoggerOptions as r, WorkflowLogger as s };

package/agents.d.mts

@@ -1,5 +0,0 @@
-import 'ai';
-export { v as Agent, M as ManagerAgent, t as WorkflowAgents, u as createWorkflowOpenAI } from './types-BEyIoCRe.mjs';
-import '@upstash/qstash';
-import '@ai-sdk/openai';
-import 'langchain/tools';

package/agents.d.ts

@@ -1,5 +0,0 @@
-import 'ai';
-export { v as Agent, M as ManagerAgent, t as WorkflowAgents, u as createWorkflowOpenAI } from './types-BEyIoCRe.js';
-import '@upstash/qstash';
-import '@ai-sdk/openai';
-import 'langchain/tools';