Interface GenerateOptions<O, CustomOptions>

interface GenerateOptions<
    O extends ZodTypeAny = ZodTypeAny,
    CustomOptions extends ZodTypeAny = ZodTypeAny,
> {
    config?: TypeOf<CustomOptions>;
    context?: ActionContext;
    docs?: {
        content: (
            | { media?: undefined; text: string }
            | { media: { contentType?: string; url: string }; text?: undefined }
        )[];
        metadata?: Record<string, any>;
    }[];
    maxTurns?: number;
    messages?: (
        {
            content: (
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text: string;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media: { contentType?: string; url: string };
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest: { input?: unknown; name: string; ref?: string };
                    toolResponse?: undefined;
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse: { name: string; output?: unknown; ref?: string };
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
                | {
                    custom: Record<string, any>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
            )[];
            metadata?: Record<string, unknown>;
            role: "user" | "model" | "tool" | "system";
        } & {
            content: | string
            | (
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text: string;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media: { contentType?: string; url: string };
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest: { input?: unknown; name: string; ref?: string };
                    toolResponse?: undefined;
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse: { name: string; output?: unknown; ref?: string };
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
                | {
                    custom: Record<string, any>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
            )[]
            | (
                | string
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text: string;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media: { contentType?: string; url: string };
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest: { input?: unknown; name: string; ref?: string };
                    toolResponse?: undefined;
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse: { name: string; output?: unknown; ref?: string };
                }
                | {
                    custom?: Record<string, unknown>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
                | {
                    custom: Record<string, any>;
                    data?: unknown;
                    media?: undefined;
                    metadata?: Record<string, unknown>;
                    text?: undefined;
                    toolRequest?: undefined;
                    toolResponse?: undefined;
                }
            )[];
        }
    )[];
    model?: ModelArgument<CustomOptions>;
    onChunk?: StreamingCallback<GenerateResponseChunk<unknown>>;
    output?: OutputOptions<O>;
    prompt?:
        | string
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text: string;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media: { contentType?: string; url: string };
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest: { input?: unknown; name: string; ref?: string };
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse: { name: string; output?: unknown; ref?: string };
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom: Record<string, any>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | (
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text: string;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media: { contentType?: string; url: string };
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest: { input?: unknown; name: string; ref?: string };
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse: { name: string; output?: unknown; ref?: string };
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom: Record<string, any>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
        )[];
    resume?: ResumeOptions;
    returnToolRequests?: boolean;
    streamingCallback?: StreamingCallback<GenerateResponseChunk<unknown>>;
    system?:
        | string
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text: string;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media: { contentType?: string; url: string };
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest: { input?: unknown; name: string; ref?: string };
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse: { name: string; output?: unknown; ref?: string };
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom: Record<string, any>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | (
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text: string;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media: { contentType?: string; url: string };
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest: { input?: unknown; name: string; ref?: string };
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse: { name: string; output?: unknown; ref?: string };
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom: Record<string, any>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
        )[];
    toolChoice?: ToolChoice;
    tools?: ToolArgument<ZodTypeAny, ZodTypeAny>[];
    use?: ModelMiddleware[];
}

Type Parameters

Properties

Configuration for the generation request.

context?: ActionContext

Additional context (data, like e.g. auth) to be passed down to tools, prompts and other sub actions.

docs?: {
    content: (
        | { media?: undefined; text: string }
        | { media: { contentType?: string; url: string }; text?: undefined }
    )[];
    metadata?: Record<string, any>;
}[]

Retrieved documents to be used as context for this generation.

maxTurns?: number

Maximum number of tool call iterations that can be performed in a single generate call (default 5).

messages?: (
    {
        content: (
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text: string;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media: { contentType?: string; url: string };
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest: { input?: unknown; name: string; ref?: string };
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse: { name: string; output?: unknown; ref?: string };
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom: Record<string, any>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
        )[];
        metadata?: Record<string, unknown>;
        role: "user" | "model" | "tool" | "system";
    } & {
        content: | string
        | (
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text: string;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media: { contentType?: string; url: string };
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest: { input?: unknown; name: string; ref?: string };
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse: { name: string; output?: unknown; ref?: string };
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom: Record<string, any>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
        )[]
        | (
            | string
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text: string;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media: { contentType?: string; url: string };
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest: { input?: unknown; name: string; ref?: string };
                toolResponse?: undefined;
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse: { name: string; output?: unknown; ref?: string };
            }
            | {
                custom?: Record<string, unknown>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
            | {
                custom: Record<string, any>;
                data?: unknown;
                media?: undefined;
                metadata?: Record<string, unknown>;
                text?: undefined;
                toolRequest?: undefined;
                toolResponse?: undefined;
            }
        )[];
    }
)[]

Conversation messages (history) for multi-turn prompting when supported by the underlying model.

A model name (e.g. vertexai/gemini-1.0-pro) or reference.

onChunk?: StreamingCallback<GenerateResponseChunk<unknown>>

When provided, models supporting streaming will call the provided callback with chunks as generation progresses.

output?: OutputOptions<O>

Configuration for the desired output of the request. Defaults to the model's default output if unspecified.

prompt?:
    | string
    | {
        custom?: Record<string, unknown>;
        data?: unknown;
        media?: undefined;
        metadata?: Record<string, unknown>;
        text: string;
        toolRequest?: undefined;
        toolResponse?: undefined;
    }
    | {
        custom?: Record<string, unknown>;
        data?: unknown;
        media: { contentType?: string; url: string };
        metadata?: Record<string, unknown>;
        text?: undefined;
        toolRequest?: undefined;
        toolResponse?: undefined;
    }
    | {
        custom?: Record<string, unknown>;
        data?: unknown;
        media?: undefined;
        metadata?: Record<string, unknown>;
        text?: undefined;
        toolRequest: { input?: unknown; name: string; ref?: string };
        toolResponse?: undefined;
    }
    | {
        custom?: Record<string, unknown>;
        data?: unknown;
        media?: undefined;
        metadata?: Record<string, unknown>;
        text?: undefined;
        toolRequest?: undefined;
        toolResponse: { name: string; output?: unknown; ref?: string };
    }
    | {
        custom?: Record<string, unknown>;
        data?: unknown;
        media?: undefined;
        metadata?: Record<string, unknown>;
        text?: undefined;
        toolRequest?: undefined;
        toolResponse?: undefined;
    }
    | {
        custom: Record<string, any>;
        data?: unknown;
        media?: undefined;
        metadata?: Record<string, unknown>;
        text?: undefined;
        toolRequest?: undefined;
        toolResponse?: undefined;
    }
    | (
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text: string;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media: { contentType?: string; url: string };
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest: { input?: unknown; name: string; ref?: string };
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse: { name: string; output?: unknown; ref?: string };
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom: Record<string, any>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
    )[]

The prompt for which to generate a response. Can be a string for a simple text prompt or one or more parts for multi-modal prompts.

resume?: ResumeOptions

resume provides convenient capabilities for continuing generation after an interrupt is triggered. Example:

const myInterrupt = ai.defineInterrupt({...});

const response = await ai.generate({
tools: [myInterrupt],
prompt: "Call myInterrupt",
});

const interrupt = response.interrupts[0];

const resumedResponse = await ai.generate({
messages: response.messages,
resume: myInterrupt.reply(interrupt, {note: "this is the reply data"}),
});
returnToolRequests?: boolean

When true, return tool calls for manual processing instead of automatically resolving them.

streamingCallback?: StreamingCallback<GenerateResponseChunk<unknown>>

When provided, models supporting streaming will call the provided callback with chunks as generation progresses.

use onChunk instead.

system?:
    | string
    | {
        custom?: Record<string, unknown>;
        data?: unknown;
        media?: undefined;
        metadata?: Record<string, unknown>;
        text: string;
        toolRequest?: undefined;
        toolResponse?: undefined;
    }
    | {
        custom?: Record<string, unknown>;
        data?: unknown;
        media: { contentType?: string; url: string };
        metadata?: Record<string, unknown>;
        text?: undefined;
        toolRequest?: undefined;
        toolResponse?: undefined;
    }
    | {
        custom?: Record<string, unknown>;
        data?: unknown;
        media?: undefined;
        metadata?: Record<string, unknown>;
        text?: undefined;
        toolRequest: { input?: unknown; name: string; ref?: string };
        toolResponse?: undefined;
    }
    | {
        custom?: Record<string, unknown>;
        data?: unknown;
        media?: undefined;
        metadata?: Record<string, unknown>;
        text?: undefined;
        toolRequest?: undefined;
        toolResponse: { name: string; output?: unknown; ref?: string };
    }
    | {
        custom?: Record<string, unknown>;
        data?: unknown;
        media?: undefined;
        metadata?: Record<string, unknown>;
        text?: undefined;
        toolRequest?: undefined;
        toolResponse?: undefined;
    }
    | {
        custom: Record<string, any>;
        data?: unknown;
        media?: undefined;
        metadata?: Record<string, unknown>;
        text?: undefined;
        toolRequest?: undefined;
        toolResponse?: undefined;
    }
    | (
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text: string;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media: { contentType?: string; url: string };
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest: { input?: unknown; name: string; ref?: string };
            toolResponse?: undefined;
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse: { name: string; output?: unknown; ref?: string };
        }
        | {
            custom?: Record<string, unknown>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
        | {
            custom: Record<string, any>;
            data?: unknown;
            media?: undefined;
            metadata?: Record<string, unknown>;
            text?: undefined;
            toolRequest?: undefined;
            toolResponse?: undefined;
        }
    )[]

The system prompt to be included in the generate request. Can be a string for a simple text prompt or one or more parts for multi-modal prompts (subject to model support).

toolChoice?: ToolChoice

Specifies how tools should be called by the model.

List of registered tool names or actions to treat as a tool for this generation if supported by the underlying model.

Middleware to be used with this model call.