@microsoft/teams-ai/lib/planners/AssistantsPlanner.d.ts

SDK focused on building AI based applications for Microsoft Teams.

/**
 * @module teams-ai
 */
/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */
import { TurnContext } from 'botbuilder';
import OpenAI, { AzureClientOptions } from 'openai';
import { AI } from '../AI';
import { TurnState } from '../TurnState';
import { Planner, Plan } from './Planner';
/**
 * Options for configuring the AssistantsPlanner.
 */
export interface AssistantsPlannerOptions {
    /**
     * The OpenAI or Azure OpenAI API key. Required.
     */
    apiKey: string;
    /**
     * The Azure OpenAI resource endpoint.
     * @remarks
     * Required when using Azure OpenAI. Not used for OpenAI.
     */
    endpoint?: string;
    /**
     * The ID of the assistant to use. Required.
     */
    assistant_id: string;
    /**
     * Optional. Polling interval in milliseconds.
     * @remarks
     * Defaults to 1000 (once a second).
     */
    polling_interval?: number;
    /**
     * Optional. The state variable to use for storing the assistants state.
     * @remarks
     * Defaults to 'conversation.assistants_state'.
     */
    assistants_state_variable?: string;
    /**
     * Optional. Version of the API being called. Default is '2024-02-15-preview'.
     */
    apiVersion?: string;
}
/**
 * A Planner that uses the OpenAI Assistants API to generate plans for the AI system.
 * @template TState Optional. Type of application state.
 * @remarks
 * This planner manages conversations through OpenAI's thread-based system, handling:
 * - Thread creation and management
 * - Message submission
 * - Tool/function calling
 * - Response processing
 */
export declare class AssistantsPlanner<TState extends TurnState = TurnState> implements Planner<TState> {
    private readonly _options;
    private _client;
    /**
     * Creates a new `AssistantsPlanner` instance.
     * @param {AssistantsPlannerOptions} options - Options for configuring the AssistantsPlanner.
     */
    constructor(options: AssistantsPlannerOptions);
    /**
     * Starts a new task.
     * @remarks
     * This method is called when the AI system is ready to start a new task. It delegates the
     * task handling to the `continueTask` method. The planner should
     * generate a plan that the AI system will execute. Returning an empty plan signals that
     * there is no work to be performed.
     *
     * The planner should take the users input from `state.temp.input`.
     * @param {TurnContext} context - Context for the current turn of conversation.
     * @param {TState} state - Application state for the current turn of conversation.
     * @param {AI<TState>} ai - The AI system that is generating the plan.
     * @returns {Promise<Plan>} The plan that was generated.
     */
    beginTask(context: TurnContext, state: TState, ai: AI<TState>): Promise<Plan>;
    /**
     * Continues the current task.
     * @remarks
     * This method is called when the AI system is ready to continue the current task. It handles:
     * - Creating a new thread if one doesn't exist
     * - Submitting tool outputs if required
     * - Waiting for any in-progress runs to complete
     * - Submitting user input and creating a new run
     * The method generates a plan that the AI system will execute. Returning an empty plan signals
     * that the task is completed and there is no work to be performed.
     *
     * The output from the last plan step that was executed is passed to the planner via `state.temp.input`.
     * @param {TurnContext} context - Context for the current turn of conversation.
     * @param {TState} state - Application state for the current turn of conversation.
     * @param {AI<TState>} ai - The AI system that is generating the plan.
     * @returns {Promise<Plan>} The plan that was generated.
     */
    continueTask(context: TurnContext, state: TState, ai: AI<TState>): Promise<Plan>;
    /**
     * Creates a new assistant using the OpenAI Assistants API.
     * @param {string} apiKey - OpenAI API key.
     * @param {OpenAI.Beta.AssistantCreateParams} request - Definition of the assistant to create.
     * @param {string} endpoint - Optional. The Azure OpenAI resource endpoint. Required when using Azure OpenAI.
     * @param {Record<string, string | undefined>} azureClientOptions - Optional. The Azure OpenAI client options.
     * @returns {Promise<OpenAI.Beta.Assistant>} The created assistant.
     * @throws {Error} If the assistant creation fails.
     */
    static createAssistant(apiKey: string, request: OpenAI.Beta.AssistantCreateParams, endpoint?: string, azureClientOptions?: AzureClientOptions): Promise<OpenAI.Beta.Assistant>;
    /**
     * Ensures a thread exists for the current conversation.
     * @private
     * @param {TurnState} state - The application Turn State.
     * @param {string} input - The initial thread input.
     * @returns {Promise<string>} The thread ID.
     */
    private ensureThreadCreated;
    /**
     * Checks if a run has reached a terminal state.
     * @private
     * @param {OpenAI.Beta.Threads.Run} run - The run to check.
     * @returns {boolean} True if the run is in a completed state.
     */
    private isRunCompleted;
    /**
     * @private
     * Waits for a run to complete.
     * @param {string} thread_id - The ID of the thread.
     * @param {string} run_id - The ID of the run.
     * @param {boolean} handleActions - Whether to handle actions.
     * @returns {Promise<OpenAI.Beta.Threads.Run>} The completed run.
     */
    private waitForRun;
    /**
     * @private
     * Submits action results to the assistant.
     * @param {TurnContext} context - The turn context.
     * @param {TState} state - The turn state.
     * @param {AI<TState>} ai - The AI instance.
     * @returns {Promise<Plan>} A plan based on the action results.
     */
    private submitActionResults;
    /**
     * @private
     * Submits user input to the assistant.
     * @param {TurnContext} context - The turn context.
     * @param {TState} state - The turn state.
     * @param {AI<TState>} ai - The AI instance.
     * @returns {Promise<Plan>} A plan based on the user input.
     */
    private submitUserInput;
    /**
     * @private
     * Generates a plan from tool calls.
     * @param {TState} state - The turn state.
     * @param {OpenAI.Beta.Threads.Runs.RequiredActionFunctionToolCall[]} toolCalls - The tool calls to generate the plan from.
     * @returns {Plan} A plan based on the tool calls.
     */
    private generatePlanFromTools;
    /**
     * @private
     * Generates a plan from messages.
     * @param {string} thread_id - The ID of the thread.
     * @param {string} last_message_id - The ID of the last message.
     * @returns {Promise<Plan>} A plan based on the messages.
     */
    private generatePlanFromMessages;
    /**
     * @private
     * Ensures that the assistants state exists in the turn state.
     * @param {TState} state - The turn state.
     * @returns {AssistantsState} The assistants state.
     */
    private ensureAssistantsState;
    /**
     * @private
     * Updates the assistants state in the turn state.
     * @param {TState} state - The turn state.
     * @param {AssistantsState} assistantsState - The new assistants state.
     */
    private updateAssistantsState;
    /**
     * @private
     * Blocks until all in-progress runs are completed.
     * @param {string} thread_id - The ID of the thread.
     */
    private blockOnInProgressRuns;
    /**
     * @private
     * @param {string} apiKey - The api key
     * @param {string} endpoint  - The Azure OpenAI resource endpoint
     * @param {Record<string, string | undefined>} azureClientOptions - The Azure OpenAI client options.
     * @returns {OpenAI} the client
     */
    private static createClient;
}
//# sourceMappingURL=AssistantsPlanner.d.ts.map