@openai/agents-core
Version:
The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.
228 lines (227 loc) • 9.96 kB
TypeScript
import { Agent, AgentOutputType } from './agent';
import { RunContext } from './runContext';
import { AgentInputItem, JsonObjectSchema, ResolveParsedToolParameters, TextOutput, UnknownContext } from './types';
import { RunItem } from './items';
import { ToolInputParameters } from './tool';
/**
* Data passed to the handoff function.
*/
export type HandoffInputData = {
/**
* The input history before `Runner.run()` was called.
*/
inputHistory: string | AgentInputItem[];
/**
* The items generated before the agent turn where the handoff was invoked.
*/
preHandoffItems: RunItem[];
/**
* The new items generated during the current agent turn, including the item that triggered the
* handoff and the tool output message representing the response from the handoff output.
*/
newItems: RunItem[];
/**
* The context of the handoff.
* Note that, since this property was added later on, it's optional to pass from users.
*/
runContext?: RunContext<any>;
};
export type HandoffInputFilter = (input: HandoffInputData) => HandoffInputData;
/**
* Generates the message that will be given as tool output to the model that requested the handoff.
*
* @param agent The agent to transfer to
* @returns The message that will be given as tool output to the model that requested the handoff
*/
export declare function getTransferMessage<TContext, TOutput extends AgentOutputType>(agent: Agent<TContext, TOutput>): string;
/**
* A handoff is when an agent delegates a task to another agent.
* For example, in a customer support scenario you might have a "triage agent" that determines which
* agent should handle the user's request, and sub-agents that specialize in different areas like
* billing, account management, etc.
*
* @template TContext The context of the handoff
* @template TOutput The output type of the handoff
*/
type HandoffEnabledPredicate<TContext = UnknownContext> = (args: {
runContext: RunContext<TContext>;
agent: Agent<any, any>;
}) => boolean | Promise<boolean>;
type HandoffEnabledOption<TContext> = boolean | HandoffEnabledPredicate<TContext>;
export type HandoffEnabledFunction<TContext = UnknownContext> = (args: {
runContext: RunContext<TContext>;
agent: Agent<any, any>;
}) => Promise<boolean>;
type HandoffErrorFunction<TContext> = (context: RunContext<TContext>, error: unknown) => string | Promise<string>;
export type HandoffCloneOptions<TContext = UnknownContext, TOutput extends AgentOutputType = TextOutput> = {
/**
* The agent that the cloned handoff should target.
*/
agent?: Agent<TContext, TOutput>;
/**
* The callback that should run when the cloned handoff is invoked.
*/
onInvokeHandoff?: (context: RunContext<TContext>, args: string) => Promise<Agent<TContext, TOutput>> | Agent<TContext, TOutput>;
/**
* The model-facing name of the target agent.
*/
agentName?: string;
/**
* The name of the tool that represents the cloned handoff.
*/
toolName?: string;
/**
* The description of the tool that represents the cloned handoff.
*/
toolDescription?: string;
/**
* The JSON schema for the cloned handoff input.
*/
inputJsonSchema?: JsonObjectSchema<any>;
/**
* Whether the cloned handoff input schema is strict.
*/
strictJsonSchema?: boolean;
/**
* A function that filters the inputs that are passed to the cloned handoff's agent.
*/
inputFilter?: HandoffInputFilter;
/** See {@link Handoff.errorFunction}. */
errorFunction?: HandoffErrorFunction<TContext>;
/**
* Determines whether the cloned handoff should be available for the current run.
*/
isEnabled?: HandoffEnabledFunction<TContext>;
};
export declare class Handoff<TContext = UnknownContext, TOutput extends AgentOutputType = TextOutput> {
/**
* The name of the tool that represents the handoff.
*/
toolName: string;
/**
* The description of the tool that represents the handoff.
*/
toolDescription: string;
/**
* The JSON schema for the handoff input. Can be empty if the handoff does not take an input
*/
inputJsonSchema: JsonObjectSchema<any>;
/**
* Whether the input JSON schema is in strict mode. We **strongly** recommend setting this to
* true, as it increases the likelihood of correct JSON input.
*/
strictJsonSchema: boolean;
/**
* The function that invokes the handoff. The parameters passed are:
* 1. The handoff run context
* 2. The arguments from the LLM, as a JSON string. Empty string if inputJsonSchema is empty.
*
* Must return an agent
*/
onInvokeHandoff: (context: RunContext<TContext>, args: string) => Promise<Agent<TContext, TOutput>> | Agent<TContext, TOutput>;
/**
* The name of the agent that is being handed off to.
*/
agentName: string;
/**
* A function that filters the inputs that are passed to the next agent. By default, the new agent
* sees the entire conversation history. In some cases, you may want to filter inputs e.g. to
* remove older inputs, or remove tools from existing inputs.
*
* The function will receive the entire conversation history so far, including the input item
* that triggered the handoff and a tool call output item representing the handoff tool's output.
*
* You are free to modify the input history or new items as you see fit. The next agent that runs
* will receive `handoffInputData.allItems`.
* Filtered handoffs cannot use `conversationId` or `previousResponseId`, including no-op filters.
* Use client-managed history or a Session without either continuation option instead.
*/
inputFilter?: HandoffInputFilter;
/**
* Lets Runner continue on the source agent after a failed invocation. Return only
* application-approved feedback for the model, or throw to propagate the failure.
* Omitting this callback propagates invocation errors. Cancellation, transfer hooks,
* input filters and Realtime handoffs retain their existing behavior. Recovery
* preserves any external effects already performed by the invocation.
*/
errorFunction?: HandoffErrorFunction<TContext>;
/**
* The agent that is being handed off to.
*/
agent: Agent<TContext, TOutput>;
/**
* Returns a function tool definition that can be used to invoke the handoff.
*/
getHandoffAsFunctionTool(): {
type: "function";
name: string;
description: string;
parameters: JsonObjectSchema<any>;
strict: boolean;
};
/**
* Makes a copy of this handoff, with the given fields changed.
*
* Tool name and description default to the original handoff's values so adapters can replace
* the runtime target without changing the model-facing tool contract.
*/
clone(overrides?: HandoffCloneOptions<TContext, TOutput>): Handoff<TContext, TOutput>;
isEnabled: HandoffEnabledFunction<TContext>;
constructor(agent: Agent<TContext, TOutput>, onInvokeHandoff: (context: RunContext<TContext>, args: string) => Promise<Agent<TContext, TOutput>> | Agent<TContext, TOutput>);
}
/**
* A function that runs when the handoff is invoked.
*/
export type OnHandoffCallback<TInputType extends ToolInputParameters> = (context: RunContext<any>, input?: ResolveParsedToolParameters<TInputType>) => Promise<void> | void;
/**
* Configuration for a handoff.
*/
export type HandoffConfig<TInputType extends ToolInputParameters, TContext = UnknownContext> = {
/**
* Optional override for the name of the tool that represents the handoff.
*/
toolNameOverride?: string;
/**
* Optional override for the description of the tool that represents the handoff.
*/
toolDescriptionOverride?: string;
/**
* A function that runs when the handoff is invoked
*/
onHandoff?: OnHandoffCallback<TInputType>;
/**
* The type of the input to the handoff. If provided as a validation schema, the input will be
* validated against this type. Only relevant if you pass a function that takes an input.
*/
inputType?: TInputType;
/**
* A function that filters the inputs that are passed to the next agent.
* Cannot be combined with `conversationId` or `previousResponseId`; see `Handoff.inputFilter`.
*/
inputFilter?: HandoffInputFilter;
/** See {@link Handoff.errorFunction}. */
errorFunction?: HandoffErrorFunction<TContext>;
/**
* Determines whether the handoff should be available to the model for the current run.
*/
isEnabled?: HandoffEnabledOption<TContext>;
};
/**
* Creates a handoff from an agent. Handoffs are automatically created when you pass an agent
* into the `handoffs` option of the `Agent` constructor. Alternatively, you can use this function
* to create a handoff manually, giving you more control over configuration.
*
* @template TContext The context of the handoff
* @template TOutput The output type of the handoff
* @template TInputType The input type of the handoff
*/
export declare function handoff<TContext = UnknownContext, TOutput extends AgentOutputType = TextOutput, TInputType extends ToolInputParameters = ToolInputParameters>(agent: Agent<TContext, TOutput>, config?: HandoffConfig<TInputType, TContext>): Handoff<TContext, TOutput>;
/**
* Returns a handoff for the given agent. If the agent is already wrapped into a handoff,
* it will be returned as is. Otherwise, a new handoff instance will be created.
*
* @template TContext The context of the handoff
* @template TOutput The output type of the handoff
*/
export declare function getHandoff<TContext, TOutput extends AgentOutputType>(agent: Agent<TContext, TOutput> | Handoff<TContext, TOutput>): Handoff<TContext, TOutput>;
export {};