콘텐츠로 이동

FunctionTool

이 콘텐츠는 아직 번역되지 않았습니다.

type FunctionTool<Context, TParameters, Result> = object;

Exposes a function to the agent as a tool to be called

Type Parameter Default type Description

Context

UnknownContext

The context of the tool

TParameters extends ToolInputParameters

undefined

‐

Result

unknown

The result of the tool

allowedCallers?: ToolAllowedCallers;

Responses API only. Controls which execution contexts can invoke the tool. When omitted, the Responses API defaults to direct calls only.


customDataExtractor?: FunctionToolCustomDataExtractor<Context, TParameters, Result>;

Optional callback that attaches SDK-only custom data to the emitted tool output item.


deferLoading?: boolean;

Responses API only. Hides a top-level function tool definition until tool search loads it.


description: string;

The description of the tool that helps the model to understand when to use the tool


errorFunction?: ToolErrorFunction<Context, string | Result> | null;

Optional model-visible fallback for execution errors and pre-execution failures. Structured tools use this to preserve their output contract.


inputGuardrails?: ToolInputGuardrailDefinition<Context>[];

Guardrails that run before the tool executes.


invoke: (runContext, input, details?) => Promise<string | Result>;

The function to invoke when the tool is called.

Parameter Type

runContext

RunContext<Context>

input

string

details?

ToolCallDetails

Promise<string | Result>


isEnabled: ToolEnabledFunction<Context>;

Determines whether the tool should be made available to the model for the current run.


name: string;

The name of the tool.


needsApproval: ToolApprovalFunction<TParameters>;

Whether the tool needs human approval before it can be called. If this is true, the run will result in an interruption that the program has to resolve by approving or rejecting the tool call.


outputGuardrails?: ToolOutputGuardrailDefinition<Context>[];

Guardrails that run after the tool executes.


outputSchema?: JsonObjectSchema<any>;

Responses API only. Describes the JSON value encoded in string outputs. Zod schemas also validate the tool result at runtime.


parameters: JsonObjectSchema<any>;

A JSON schema describing the parameters of the tool.


providerData?: Record<string, any>;

Additional provider-specific metadata forwarded with the function tool definition.


strict: boolean;

Whether the tool is strict. If true, the model must try to strictly follow the schema (might result in slower response times).


timeoutBehavior?: FunctionToolTimeoutBehavior;

Defines how timeout errors are handled.

  • error_as_result: return a model-visible timeout message.
  • raise_exception: raise ToolTimeoutError and fail the run.

Tools created with an output schema default to raise_exception; other function tools default to error_as_result.


timeoutErrorFunction?: ToolTimeoutErrorFunction<Context, Result>;

Optional formatter for timeout errors when timeoutBehavior is error_as_result.


timeoutMs?: number;

Optional timeout in milliseconds for each tool invocation.


type: "function";