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

package/{types-Bt4-paRy.d.mts → types-D9gwTj2n.d.mts}

@@ -1,4 +1,7 @@
 import { PublishRequest, Client, Receiver, HTTPMethods as HTTPMethods$1 } from '@upstash/qstash';
+import * as ai from 'ai';
+import { CoreTool, generateText } from 'ai';
+import * as _ai_sdk_openai from '@ai-sdk/openai';
 
 /**
  * Base class outlining steps. Basically, each step kind (run/sleep/sleepUntil)
@@ -387,6 +390,239 @@ 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"];
+    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<{
+        text: string;
+    }>;
+    /**
+     * Convert the agent to a tool which can be used by other agents.
+     *
+     * @returns the agent as a tool
+     */
+    asTool(): AISDKTool;
+}
+
+type AISDKTool = CoreTool;
+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;
+    constructor({ context, taskParameters, }: {
+        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;
+}
+
 /**
  * Upstash Workflow context
  *
@@ -682,6 +918,7 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      */
     protected addStep<TResult = unknown>(step: BaseLazyStep<TResult>): Promise<TResult>;
     get api(): WorkflowApi;
+    get agents(): WorkflowAgents;
 }
 
 /**

package/{types-Bt4-paRy.d.ts → types-D9gwTj2n.d.ts}

@@ -1,4 +1,7 @@
 import { PublishRequest, Client, Receiver, HTTPMethods as HTTPMethods$1 } from '@upstash/qstash';
+import * as ai from 'ai';
+import { CoreTool, generateText } from 'ai';
+import * as _ai_sdk_openai from '@ai-sdk/openai';
 
 /**
  * Base class outlining steps. Basically, each step kind (run/sleep/sleepUntil)
@@ -387,6 +390,239 @@ 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"];
+    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<{
+        text: string;
+    }>;
+    /**
+     * Convert the agent to a tool which can be used by other agents.
+     *
+     * @returns the agent as a tool
+     */
+    asTool(): AISDKTool;
+}
+
+type AISDKTool = CoreTool;
+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;
+    constructor({ context, taskParameters, }: {
+        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;
+}
+
 /**
  * Upstash Workflow context
  *
@@ -682,6 +918,7 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      */
     protected addStep<TResult = unknown>(step: BaseLazyStep<TResult>): Promise<TResult>;
     get api(): WorkflowApi;
+    get agents(): WorkflowAgents;
 }
 
 /**