Class References
Function References
- text
- textOptions
- combineStrategies
- convertMessagesToModelMessages
- convertZodToJsonSchema
- createReplayStream
- embedding
- generateMessageId
- maxIterations
- messages
- modelMessageToUIMessage
- modelMessagesToUIMessages
- normalizeToUIMessage
- parsePartialJSON
- summarize
- toServerSentEventsStream
- toServerSentEventsResponse
- toolDefinition
- uiMessageToModelMessages
- realtimeToken
- untilFinishReason
Interface References
- AIAdapter
- AIAdapterConfig
- AgentLoopState
- AudioPart
- AudioVisualization
- BaseStreamChunk
- TextCompletionChunk
- TextOptions
- ChunkRecording
- ChunkStrategy
- ClientTool
- ContentPartSource
- ContentStreamChunk
- DefaultMessageMetadataByModality
- DocumentPart
- DoneStreamChunk
- EmbeddingOptions
- EmbeddingResult
- ErrorStreamChunk
- ImagePart
- InternalToolCallState
- JSONParser
- ModelMessage
- ProcessorResult
- ProcessorState
- RealtimeAdapter
- RealtimeClientOptions
- RealtimeConnection
- RealtimeMessage
- RealtimeSessionConfig
- RealtimeToken
- RealtimeTokenAdapter
- RealtimeTokenOptions
- ResponseFormat
- ServerTool
- StreamProcessorEvents
- StreamProcessorHandlers
- StreamProcessorOptions
- SummarizationOptions
- SummarizationResult
- TextPart
- ThinkingPart
- ThinkingStreamChunk
- Tool
- ToolCall
- ToolCallPart
- ToolCallStreamChunk
- ToolConfig
- ToolDefinition
- ToolDefinitionConfig
- ToolDefinitionInstance
- ToolInputAvailableStreamChunk
- ToolResultPart
- ToolResultStreamChunk
- UIMessage
- VideoPart
Type Alias References
- AgentLoopStrategy
- AnyClientTool
- TextStreamOptionsForModel
- TextStreamOptionsUnion
- ConstrainedContent
- ConstrainedModelMessage
- ContentPart
- ContentPartForModalities
- ExtractModalitiesForModel
- ExtractModelsFromAdapter
- InferToolInput
- InferToolName
- InferToolOutput
- MessagePart
- RealtimeEvent
- RealtimeMessagePart
- RealtimeMode
- RealtimeStatus
- ModalitiesArrayToUnion
- Modality
- StreamChunk
- ToolCallState
- ToolResultState
Variable References
ToolDefinition
Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:269
Tool definition builder that allows creating server or client tools from a shared definition
Extends#
- ToolDefinitionInstance<TInput, TOutput, TName, unknown, TNeedsApproval, TApprovalSchema, TResultMetadataSchema>
Type Parameters#
TInput#
TInput extends SchemaInput | undefined = undefined
TOutput#
TOutput extends SchemaInput | undefined = undefined
TName#
TName extends string = string
TNeedsApproval#
TNeedsApproval extends boolean = false
TApprovalSchema#
TApprovalSchema extends | ApprovalSchemaConfig | undefined = undefined
TResultMetadataSchema#
TResultMetadataSchema extends SchemaInput | undefined = SchemaInput | undefined
Properties#
__toolSide#
__toolSide: "definition";Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:169
Inherited from#
ToolDefinitionInstance.__toolSide
[toolApprovalCapability]?#
readonly optional [toolApprovalCapability]?: object;Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:177
approvalSchema#
approvalSchema: TApprovalSchema;needsApproval#
needsApproval: TNeedsApproval;Inherited from#
ToolDefinitionInstance.[toolApprovalCapability]
approvalSchema#
approvalSchema: TApprovalSchema;Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:175
Inherited from#
ToolDefinitionInstance.approvalSchema
client#
client: <TContext>(execute?) => ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval, TApprovalSchema, TResultMetadataSchema> & BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema>;Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:313
Create a client-side tool with optional execute function. Carries the definition's needsApproval literal through to the client tool so the tool-call part's approval field stays gated on it.
Type Parameters#
TContext#
TContext = unknown
Parameters#
execute?#
ToolExecuteFunction<TInput, TOutput, TContext, never>
Returns#
ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval, TApprovalSchema, TResultMetadataSchema> & BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema>
description#
description: string;Defined in: packages/ai/src/types.ts:1098
Clear description of what the tool does.
This is crucial - the model uses this to decide when to call the tool. Be specific about what the tool does, what parameters it needs, and what it returns.
Example#
"Get the current weather in a given location. Returns temperature, conditions, and forecast."Inherited from#
ToolDefinitionInstance.description
execute?#
optional execute?: (args, context?) =>
| InferSchemaType<TOutput>
| Promise<InferSchemaType<TOutput>>;Defined in: packages/ai/src/types.ts:1186
Optional function to execute when the model calls this tool.
If provided, the SDK will automatically execute the function with the model's arguments and feed the result back to the model. This enables autonomous tool use loops.
Can return any value - will be automatically stringified if needed.
Parameters#
args#
InferSchemaType<TInput>
The arguments parsed from the model's tool call (validated against inputSchema)
context?#
ToolExecutionContext<unknown, ResultMetadataFromSchema<TResultMetadataSchema>>
Returns#
| InferSchemaType<TOutput> | Promise<InferSchemaType<TOutput>>
Result to send back to the model (validated against outputSchema if provided)
Example#
execute: async (args) => {
const weather = await fetchWeather(args.location);
return weather; // Can return object or string
}Inherited from#
ToolDefinitionInstance.execute
execution?#
optional execution?: "task";Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:176
Inherited from#
ToolDefinitionInstance.execution
inputSchema#
inputSchema: TInput;Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:172
Schema describing the tool's input parameters.
Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object. Defines the structure and types of arguments the tool accepts. The model will generate arguments matching this schema. Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.
See#
- https://standardschema.dev/json-schema
- https://json-schema.org/
Examples#
// Using Zod v4+ schema (natively supports Standard JSON Schema)
import { z } from 'zod';
z.object({
location: z.string().describe("City name or coordinates"),
unit: z.enum(["celsius", "fahrenheit"]).optional()
})// Using ArkType (natively supports Standard JSON Schema)
import { type } from 'arktype';
type({
location: 'string',
unit: "'celsius' | 'fahrenheit'"
})// Using plain JSON Schema
{
type: 'object',
properties: {
location: { type: 'string', description: 'City name or coordinates' },
unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
},
required: ['location']
}Inherited from#
ToolDefinitionInstance.inputSchema
lazy?#
optional lazy?: boolean;Defined in: packages/ai/src/types.ts:1194
If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools).
Inherited from#
metadata?#
optional metadata?: Record<string, any>;Defined in: packages/ai/src/types.ts:1205
Additional metadata for adapters or custom extensions
Inherited from#
ToolDefinitionInstance.metadata
name#
name: TName;Defined in: packages/ai/src/types.ts:1088
Unique name of the tool (used by the model to call it).
Should be descriptive and follow naming conventions (e.g., snake_case or camelCase). Must be unique within the tools array.
Example#
"get_weather", "search_database", "sendEmail"Inherited from#
needsApproval?#
optional needsApproval?: TNeedsApproval;Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:174
If true, tool execution requires user approval before running. Works with both server and client tools.
Inherited from#
ToolDefinitionInstance.needsApproval
outputSchema#
outputSchema: TOutput;Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:173
Optional schema for validating tool output.
Can be any Standard JSON Schema compliant schema or a plain JSON Schema object. If provided with a Standard Schema compliant schema, tool results will be validated against this schema before being sent back to the model. This catches bugs in tool implementations and ensures consistent output formatting.
Note: This is client-side validation only - not sent to LLM providers. Note: Plain JSON Schema output validation is not performed at runtime.
Example#
// Using Zod
z.object({
temperature: z.number(),
conditions: z.string(),
forecast: z.array(z.string()).optional()
})Inherited from#
ToolDefinitionInstance.outputSchema
replay?#
optional replay?: "safe" | "never";Defined in: packages/ai/src/types.ts:1202
Whether a host may run this tool again after a crash cut the run between the call and its result. 'safe' runs it again. Omit the field, or set 'never', when a second run is not safe. The host writes the model note. chat() does not read this field.
Inherited from#
resultMetadataSchema?#
optional resultMetadataSchema?: TResultMetadataSchema;Defined in: packages/ai/src/types.ts:1167
Optional schema for the app-only result metadata that the tool sets with context.setResultMetadata. It accepts the same schemas as outputSchema. It types the setter and the client part.resultMetadata. The model never sees the metadata.
Inherited from#
ToolDefinitionInstance.resultMetadataSchema
server#
server: <TContext>(execute) => ServerTool<TInput, TOutput, TName, TContext, TNeedsApproval, TApprovalSchema, TResultMetadataSchema> & BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema>;Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:290
Create a server-side tool with execute function
Type Parameters#
TContext#
TContext = unknown
Parameters#
execute#
ToolExecuteFunction<TInput, TOutput, TContext, TResultMetadataSchema>
Returns#
ServerTool<TInput, TOutput, TName, TContext, TNeedsApproval, TApprovalSchema, TResultMetadataSchema> & BuiltToolSchemaFields<TInput, TOutput, TApprovalSchema>