agents

type Agent struct {
	// The name of the agent.
	Name string

	// Optional instructions for the agent. Will be used as the "system prompt" when this agent is
	// invoked. Describes what the agent should do, and how it responds.
	Instructions InstructionsGetter

	// Optional Prompter object. Prompts allow you to dynamically configure the instructions,
	// tools and other config for an agent outside your code.
	// Only usable with OpenAI models, using the Responses API.
	Prompt Prompter

	// Optional description of the agent. This is used when the agent is used as a handoff, so that an
	// LLM knows what it does and when to invoke it.
	HandoffDescription string

	// Handoffs are sub-agents that the agent can delegate to. You can provide a list of handoffs,
	// and the agent can choose to delegate to them if relevant. Allows for separation of concerns and
	// modularity.
	//
	// Here you can provide a list of Handoff objects. In order to use Agent objects as
	// handoffs, add them to AgentHandoffs.
	Handoffs []Handoff

	// List of Agent objects to be used as handoffs. They will be converted to Handoff objects
	// before use. If you already have a Handoff, add it to Handoffs.
	AgentHandoffs []*Agent

	// The model implementation to use when invoking the LLM.
	Model param.Opt[AgentModel]

	// Configures model-specific tuning parameters (e.g. temperature, top_p).
	ModelSettings modelsettings.ModelSettings

	// A list of tools that the agent can use.
	Tools []Tool

	// Optional list of Model Context Protocol (https://modelcontextprotocol.io) servers that
	// the agent can use. Every time the agent runs, it will include tools from these servers in the
	// list of available tools.
	//
	// NOTE: You are expected to manage the lifecycle of these servers. Specifically, you must call
	// `MCPServer.Connect()` before passing it to the agent, and `MCPServer.Cleanup()` when the server is no
	// longer needed.
	MCPServers []MCPServer

	// Optional configuration for MCP servers.
	MCPConfig MCPConfig

	// A list of checks that run in parallel to the agent's execution, before generating a
	// response. Runs only if the agent is the first agent in the chain.
	InputGuardrails []InputGuardrail

	// A list of checks that run on the final output of the agent, after generating a response.
	// Runs only if the agent produces a final output.
	OutputGuardrails []OutputGuardrail

	// Optional output type describing the output. If not provided, the output will be a simple string.
	OutputType OutputTypeInterface

	// Optional object that receives callbacks on various lifecycle events for this agent.
	Hooks AgentHooks

	// Optional property which lets you configure how tool use is handled.
	// - RunLLMAgain: The default behavior. Tools are run, and then the LLM receives the results
	//   and gets to respond.
	// - StopOnFirstTool: The output from the first tool call is treated as the final result.
	//   In other words, it isn’t sent back to the LLM for further processing but is used directly
	//   as the final output.
	// - StopAtTools: The agent will stop running if any of the tools in the list are called.
	//   The final output will be the output of the first matching tool call. The LLM does not
	//   process the result of the tool call.
	// - ToolsToFinalOutputFunction: If you pass a function, it will be called with the run context and the list of
	//   tool results. It must return a `ToolsToFinalOutputResult`, which determines whether the tool
	//   calls result in a final output.
	//
	// NOTE: This configuration is specific to function tools. Hosted tools, such as file search,
	// web search, etc. are always processed by the LLM.
	ToolUseBehavior ToolUseBehavior

	// Whether to reset the tool choice to the default value after a tool has been called.
	// Defaults to true.
	// This ensures that the agent doesn't enter an infinite loop of tool usage.
	ResetToolChoice param.Opt[bool]
}

type AgentAsToolInput struct {
	Input string `json:"input"`
}

type AgentAsToolParams struct {
	// Optional name of the tool. If not provided, the agent's name will be used.
	ToolName string

	// Optional description of the tool, which should indicate what it does and when to use it.
	ToolDescription string

	// Optional function that extracts the output from the agent.
	// If not provided, the last message from the agent will be used.
	CustomOutputExtractor func(context.Context, RunResult) (string, error)

	// Optional approval policy for this agent tool.
	NeedsApproval FunctionToolNeedsApproval

	// Optional static or dynamic flag reporting whether the tool is enabled.
	// If omitted, the tool is enabled by default.
	IsEnabled FunctionToolEnabler
}

type AgentCloneOption func(*Agent)

type AgentHooks interface {
	// OnStart is called before the agent is invoked. Called each time the running agent is changed to this agent.
	OnStart(ctx context.Context, agent *Agent) error

	// OnEnd is called when the agent produces a final output.
	OnEnd(ctx context.Context, agent *Agent, output any) error

	// OnHandoff is called when the agent is being handed off to.
	// The `source` is the agent that is handing off to this agent.
	OnHandoff(ctx context.Context, agent, source *Agent) error

	// OnToolStart is called concurrently with tool invocation.
	OnToolStart(ctx context.Context, agent *Agent, tool Tool, arguments any) error

	// OnToolEnd is called after a tool is invoked.
	OnToolEnd(ctx context.Context, agent *Agent, tool Tool, result any) error

	// OnLLMStart is called immediately before the agent issues an LLM call.
	OnLLMStart(ctx context.Context, agent *Agent, systemPrompt param.Opt[string], inputItems []TResponseInputItem) error

	// OnLLMEnd is called immediately after the agent receives the LLM response.
	OnLLMEnd(ctx context.Context, agent *Agent, response ModelResponse) error
}

type AgentModel struct {
	// contains filtered or unexported fields
}

type AgentToToolsItem struct {
	Agent     *Agent
	ToolNames []string
}

type AgentToolRunResult struct {
	Result *RunResult
	Output string
}

type AgentToolUseTracker struct {
	AgentToTools []AgentToToolsItem
	NameToTools  map[string][]string
}

type AgentUpdatedStreamEvent struct {
	// The new agent.
	NewAgent *Agent

	// Always `agent_updated_stream_event`.
	Type string
}

type AgentsError struct {
	Err     error
	RunData *RunErrorDetails
}

type ApplyDiffMode string

type ApplyPatchEditor interface {
	CreateFile(operation ApplyPatchOperation) (any, error)
	UpdateFile(operation ApplyPatchOperation) (any, error)
	DeleteFile(operation ApplyPatchOperation) (any, error)
}

type ApplyPatchNeedsApproval interface {
	NeedsApproval(
		ctx context.Context,
		runContext *RunContextWrapper[any],
		operation ApplyPatchOperation,
		callID string,
	) (bool, error)
}

type ApplyPatchNeedsApprovalFlag struct {
	// contains filtered or unexported fields
}

type ApplyPatchNeedsApprovalFunc func(
	ctx context.Context,
	runContext *RunContextWrapper[any],
	operation ApplyPatchOperation,
	callID string,
) (bool, error)

type ApplyPatchOnApprovalFunc func(
	ctx *RunContextWrapper[any],
	approvalItem ToolApprovalItem,
) (any, error)

type ApplyPatchOperation struct {
	Type       ApplyPatchOperationType
	Path       string
	Diff       string
	CtxWrapper any
}

type ApplyPatchOperationType string

type ApplyPatchResult struct {
	Status ApplyPatchResultStatus
	Output string
}

type ApplyPatchResultStatus string

type ApplyPatchTool struct {
	Editor ApplyPatchEditor
	Name   string

	// Optional approval policy for apply_patch tool calls.
	NeedsApproval ApplyPatchNeedsApproval

	// Optional handler to auto-approve or reject when approval is required.
	OnApproval ApplyPatchOnApprovalFunc
}

type ApplyPatchToolCallRawItem map[string]any

type AudioData interface {
	Len() int
	Bytes() []byte
	Int16() AudioDataInt16
	Int() []int
}

type AudioDataFloat32 []float32

type AudioDataInt16 []int16

type AudioDataType byte

type AudioFile struct {
	Filename    string
	ContentType string
	Content     []byte
}

type AudioInput struct {
	// A buffer containing the audio data for the agent.
	Buffer AudioData

	// Optional sample rate of the audio data. Defaults to DefaultAudioSampleRate.
	SampleRate int

	// Optional sample width of the audio data. Defaults to DefaultAudioSampleWidth.
	SampleWidth int

	// Optional number of channels in the audio data. Defaults to DefaultAudioChannels.
	Channels int
}

type CallModelData struct {
	ModelData ModelInputData
	Agent     *Agent
}

type CallModelInputFilter = func(context.Context, CallModelData) (*ModelInputData, error)

type CancelMode string

type CodeInterpreterTool struct {
	// The tool config, which includes the container and other settings.
	ToolConfig responses.ToolCodeInterpreterParam
}

type CompactionItem struct {
	// The agent whose run caused this item to be generated.
	Agent *Agent

	// The raw compaction item payload.
	RawItem CompactionItemRawItem

	// Always `compaction_item`.
	Type string
}

type CompactionItemRawItem map[string]any

type ComputerCreateFunc func(context.Context, *RunContextWrapper[any]) (computer.Computer, error)

type ComputerDisposeFunc func(context.Context, *RunContextWrapper[any], computer.Computer) error

type ComputerProvider struct {
	Create  ComputerCreateFunc
	Dispose ComputerDisposeFunc
}

type ComputerTool struct {
	// The Computer implementation, which describes the environment and
	// dimensions of the computer, as well as implements the computer actions
	// like click, screenshot, etc.
	Computer computer.Computer

	// Optional factory that creates a computer instance for each run context.
	ComputerFactory ComputerCreateFunc

	// Optional lifecycle provider that creates and disposes computer instances
	// per run context. If set, it takes precedence over ComputerFactory.
	ComputerProvider *ComputerProvider

	// Optional callback to acknowledge computer tool safety checks.
	OnSafetyCheck func(context.Context, ComputerToolSafetyCheckData) (bool, error)
	// contains filtered or unexported fields
}

type ComputerToolSafetyCheckData struct {
	// The agent performing the computer action.
	Agent *Agent

	// The computer tool call.
	ToolCall responses.ResponseComputerToolCall

	// The pending safety check to acknowledge.
	SafetyCheck responses.ResponseComputerToolCallPendingSafetyCheck
}

type ConvertedTools struct {
	Tools    []responses.ToolUnionParam
	Includes []responses.ResponseIncludable
}

type DocstringStyle string

type DynamicPromptFunction func(context.Context, *Agent) (Prompt, error)

type EventSeqResult struct {
	Seq iter.Seq[StreamEvent]
	Err error
}

type FileSearchTool struct {
	// The IDs of the vector stores to search.
	VectorStoreIDs []string

	// The maximum number of results to return.
	MaxNumResults param.Opt[int64]

	// Whether to include the search results in the output produced by the LLM.
	IncludeSearchResults bool

	// Optional ranking options for search.
	RankingOptions responses.FileSearchToolRankingOptionsParam

	// Optional filter to apply based on file attributes.
	Filters responses.FileSearchToolFiltersUnionParam
}

type FuncDocumentation struct {
	Name              string
	Description       string
	ParamDescriptions map[string]string
}

type FunctionTool struct {
	// The name of the tool, as shown to the LLM. Generally the name of the function.
	Name string

	// A description of the tool, as shown to the LLM.
	Description string

	// The JSON schema for the tool's parameters.
	ParamsJSONSchema map[string]any

	// A function that invokes the tool with the given context and parameters.
	//
	// The params passed are:
	// 	1. The tool run context.
	// 	2. The arguments from the LLM, as a JSON string.
	//
	// You must return a string representation of the tool output.
	// In case of errors, you can either return an error (which will cause the run to fail) or
	// return a string error message (which will be sent back to the LLM).
	OnInvokeTool func(ctx context.Context, arguments string) (any, error)

	// Optional error handling function. When the tool invocation returns an error,
	// this function is called with the original error and its return value is sent
	// back to the LLM. If not set, a default function returning a generic error
	// message is used. To disable error handling and propagate the original error,
	// explicitly set this to a pointer to a nil ToolErrorFunction.
	FailureErrorFunction *ToolErrorFunction

	// Whether the JSON schema is in strict mode.
	// We **strongly** recommend setting this to True, as it increases the likelihood of correct JSON input.
	// Defaults to true if omitted.
	StrictJSONSchema param.Opt[bool]

	// Optional flag reporting whether the tool is enabled.
	// It can be either a boolean or a function which allows you to dynamically
	// enable/disable a tool based on your context/state.
	// Default value, if omitted: true.
	IsEnabled FunctionToolEnabler

	// Optional list of input guardrails to run before invoking this tool.
	ToolInputGuardrails []ToolInputGuardrail

	// Optional list of output guardrails to run after invoking this tool.
	ToolOutputGuardrails []ToolOutputGuardrail

	// Optional approval policy for this tool in realtime sessions.
	// If set and returns true, the tool call will pause until explicitly approved.
	NeedsApproval FunctionToolNeedsApproval

	// Optional agent reference when this tool wraps an agent.
	AgentTool *Agent

	// Internal marker used for codex-tool specific runtime validation.
	// Regular tools should leave this as false.
	IsCodexTool bool
}

type FunctionToolEnabledFlag struct {
	// contains filtered or unexported fields
}

type FunctionToolEnabler interface {
	IsEnabled(ctx context.Context, agent *Agent) (bool, error)
}

type FunctionToolEnablerFunc func(ctx context.Context, agent *Agent) (bool, error)

type FunctionToolNeedsApproval interface {
	NeedsApproval(
		ctx context.Context,
		runContext *RunContextWrapper[any],
		tool FunctionTool,
		arguments map[string]any,
		callID string,
	) (bool, error)
}

type FunctionToolNeedsApprovalFlag struct {
	// contains filtered or unexported fields
}

type FunctionToolNeedsApprovalFunc func(
	ctx context.Context,
	runContext *RunContextWrapper[any],
	tool FunctionTool,
	arguments map[string]any,
	callID string,
) (bool, error)

type FunctionToolResult struct {
	// The tool that was run.
	Tool FunctionTool

	// The output of the tool.
	Output any

	// The run item that was produced as a result of the tool call.
	RunItem RunItem
}

type GuardrailFunctionOutput struct {
	// Optional information about the guardrail's output. For example, the guardrail could include
	// information about the checks it performed and granular results.
	OutputInfo any

	// Whether the tripwire was triggered. If triggered, the agent's execution will be halted.
	TripwireTriggered bool
}

type GuardrailFunctionOutputState struct {
	OutputInfo        any  `json:"output_info,omitempty"`
	TripwireTriggered bool `json:"tripwire_triggered"`
}

type GuardrailResultState struct {
	Name   string                       `json:"name"`
	Output GuardrailFunctionOutputState `json:"output"`
}

type Handoff struct {
	// 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/nil if the handoff does not take an input.
	InputJSONSchema map[string]any

	// 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/nil.
	//
	// Must return an agent.
	OnInvokeHandoff func(context.Context, string) (*Agent, error)

	// The name of the agent that is being handed off to.
	AgentName string

	// Optional 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 all items from HandoffInputData.
	//
	// IMPORTANT: in streaming mode, we will not stream anything as a result of this function. The
	// items generated before will already have been streamed.
	InputFilter HandoffInputFilter

	// Optional override for the run-level NestHandoffHistory behavior.
	// If omitted, the RunConfig-level setting is used.
	NestHandoffHistory param.Opt[bool]

	// 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.
	// Defaults to true if omitted.
	StrictJSONSchema param.Opt[bool]

	// Optional flag reporting whether the handoff is enabled.
	// It can be either a boolean or a function which allows you to dynamically
	// enable/disable a handoff based on your context/state.
	// Default value, if omitted: true.
	IsEnabled HandoffEnabler
}

type HandoffCallItem struct {
	// The agent whose run caused this item to be generated.
	Agent *Agent

	// The raw response function tool call that represents the handoff.
	RawItem responses.ResponseFunctionToolCall

	// Always `handoff_call_item`.
	Type string
}

type HandoffEnabledFlag struct {
	// contains filtered or unexported fields
}

type HandoffEnabler interface {
	IsEnabled(ctx context.Context, agent *Agent) (bool, error)
}

type HandoffEnablerFunc func(ctx context.Context, agent *Agent) (bool, error)

type HandoffFromAgentParams struct {
	// The agent to hand off to.
	Agent *Agent

	// 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

	// Optional function that runs when the handoff is invoked.
	OnHandoff OnHandoff

	// Optional JSON schema describing the type of the input to the handoff.
	// If provided, the input will be validated against this type.
	// Only relevant if you pass a function that takes an input.
	InputJSONSchema map[string]any

	// Optional function that filters the inputs that are passed to the next agent.
	InputFilter HandoffInputFilter

	// Optional override for the run-level NestHandoffHistory behavior.
	NestHandoffHistory param.Opt[bool]

	// Optional flag reporting whether the tool is enabled.
	// It can be either a boolean or a function which allows you to dynamically
	// enable/disable a tool based on your context/state.
	// Disabled handoffs are hidden from the LLM at runtime.
	// Default value, if omitted: true.
	IsEnabled HandoffEnabler
}

type HandoffHistoryMapper = func([]TResponseInputItem) []TResponseInputItem

type HandoffInputData struct {
	// The input history before `Runner.Run()` was called.
	InputHistory Input

	// 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

	// Items to include in the next agent's input. When set, these items are used instead of
	// NewItems for building the input to the next agent. This allows filtering duplicates
	// from model input while preserving all items in NewItems for session history.
	InputItems []RunItem

	// The run context at the time the handoff was invoked (optional).
	RunContext *RunContextWrapper[any]
}

type HandoffInputFilter = func(context.Context, HandoffInputData) (HandoffInputData, error)

type HandoffOutputItem struct {
	// The agent whose run caused this item to be generated.
	Agent *Agent

	// The raw input item that represents the handoff taking place.
	RawItem TResponseInputItem

	// The agent that made the handoff.
	SourceAgent *Agent

	// The agent that is being handed off to.
	TargetAgent *Agent

	// Always `handoff_output_item`.
	Type string
}

type HeadersOverrideToken struct {
	// contains filtered or unexported fields
}

type HeadersOverrideVar struct {
	// contains filtered or unexported fields
}

type HostedMCPTool struct {
	// The MCP tool config, which includes the server URL and other settings.
	ToolConfig responses.ToolMcpParam

	// An optional function that will be called if approval is requested for an MCP tool.
	// If not provided, you will need to manually add approvals/rejections to the input and call
	// `Run(...)` again.
	OnApprovalRequest MCPToolApprovalFunction
}

type ImageGenerationTool struct {
	// The tool config, which image generation settings.
	ToolConfig responses.ToolImageGenerationParam
}

type Input interface {
	// contains filtered or unexported methods
}

type InputGuardrail struct {
	// A function that receives the agent input and the context, and returns a
	// GuardrailFunctionOutput. The result marks whether the tripwire was
	// triggered, and can optionally include information about the guardrail's output.
	GuardrailFunction InputGuardrailFunction

	// The name of the guardrail, used for tracing.
	Name string
}

type InputGuardrailFunction = func(context.Context, *Agent, Input) (GuardrailFunctionOutput, error)

type InputGuardrailResult struct {
	// The guardrail that was run.
	Guardrail InputGuardrail

	// The output of the guardrail function.
	Output GuardrailFunctionOutput
}

type InputGuardrailTripwireTriggeredError struct {
	*AgentsError
	// The result data of the guardrail that was triggered.
	GuardrailResult InputGuardrailResult
}

type InputItems []TResponseInputItem

type InputString string

type InstructionsFunc func(context.Context, *Agent) (string, error)

type InstructionsGetter interface {
	GetInstructions(context.Context, *Agent) (string, error)
}

type InstructionsStr string

type ItemsToMessagesOption func(*itemsToMessagesOptions)

type LiteLLMProvider struct {
	// contains filtered or unexported fields
}

type LiteLLMProviderParams struct {
	// API key used to call LiteLLM's OpenAI-compatible endpoint.
	// When omitted, this resolves from LITELLM_API_KEY, then OPENAI_API_KEY,
	// and finally falls back to "dummy-key".
	APIKey param.Opt[string]

	// Base URL for LiteLLM's OpenAI-compatible endpoint.
	// When omitted, this resolves from LITELLM_BASE_URL and then defaults to
	// "http://localhost:4000".
	BaseURL param.Opt[string]

	// Optional OpenAI client override. When set, APIKey/BaseURL are ignored.
	OpenaiClient *OpenaiClient

	// Default model name used when GetModel receives an empty model name.
	// When omitted, this resolves from OPENAI_DEFAULT_MODEL and then defaults
	// to "gpt-4.1".
	DefaultModel param.Opt[string]
}

type LocalShellCommandRequest struct {
	// The data from the local shell tool call.
	Data responses.ResponseOutputItemLocalShellCall
}

type LocalShellExecutor = func(context.Context, LocalShellCommandRequest) (string, error)

type LocalShellTool struct {
	// A function that executes a command on a shell.
	Executor LocalShellExecutor
}

type MCPApprovalRequestItem struct {
	// The agent whose run caused this item to be generated.
	Agent *Agent

	// The raw MCP approval request.
	RawItem responses.ResponseOutputItemMcpApprovalRequest

	// Always `mcp_approval_request_item`.
	Type string
}

type MCPApprovalResponseItem struct {
	// The agent whose run caused this item to be generated.
	Agent *Agent

	// The raw MCP approval response.
	RawItem responses.ResponseInputItemMcpApprovalResponseParam

	// Always `mcp_approval_response_item`.
	Type string
}

type MCPConfig struct {
	// If true, we will attempt to convert the MCP schemas to strict-mode schemas.
	// This is a best-effort conversion, so some schemas may not be convertible.
	// Defaults to false.
	ConvertSchemasToStrict bool

	// Optional error handling function for MCP tool invocation failures.
	// If FailureErrorFunctionSet is true and FailureErrorFunction is nil,
	// MCP tool errors are propagated (no fallback formatting).
	FailureErrorFunction *ToolErrorFunction

	// Whether FailureErrorFunction is explicitly configured.
	FailureErrorFunctionSet bool
}

type MCPListToolsItem struct {
	// The agent whose run caused this item to be generated.
	Agent *Agent

	// The raw MCP list tools call.
	RawItem responses.ResponseOutputItemMcpListTools

	// Always `mcp_list_tools_item`.
	Type string
}

type MCPRequireApprovalFunc func(
	ctx context.Context,
	runContext *RunContextWrapper[any],
	agent *Agent,
	tool *mcp.Tool,
) (bool, error)

type MCPRequireApprovalObject struct {
	Always *MCPRequireApprovalToolList
	Never  *MCPRequireApprovalToolList
}

type MCPRequireApprovalToolList struct {
	ToolNames []string
}

type MCPServer interface {
	// Connect to the server.
	//
	// For example, this might mean spawning a subprocess or opening a network connection.
	// The server is expected to remain connected until Cleanup is called.
	Connect(context.Context) error

	// Cleanup the server.
	//
	// For example, this might mean closing a subprocess or closing a network connection.
	Cleanup(context.Context) error

	// Name returns a readable name for the server.
	Name() string

	// UseStructuredContent reports  whether to use a tool result's
	// `StructuredContent` when calling an MCP tool.
	UseStructuredContent() bool

	// ListTools lists the tools available on the server.
	ListTools(context.Context, *Agent) ([]*mcp.Tool, error)

	// CallTool invokes a tool on the server.
	CallTool(ctx context.Context, toolName string, arguments map[string]any, meta map[string]any) (*mcp.CallToolResult, error)

	// ListPrompts lists the prompts available on the server.
	ListPrompts(ctx context.Context) (*mcp.ListPromptsResult, error)

	// GetPrompt returns a specific prompt from the server.
	GetPrompt(ctx context.Context, name string, arguments map[string]string) (*mcp.GetPromptResult, error)
}

type MCPServerManager struct {
	// contains filtered or unexported fields
}

type MCPServerManagerParams struct {
	ConnectTimeout time.Duration
	CleanupTimeout time.Duration

	DropFailedServers    bool
	DropFailedServersSet bool

	Strict bool

	SuppressCancelledError    bool
	SuppressCancelledErrorSet bool

	ConnectInParallel bool
}

type MCPServerSSEParams struct {
	BaseURL       string
	TransportOpts *mcp.SSEClientTransport

	// Optional client options, including MCP message handlers.
	ClientOptions *mcp.ClientOptions

	// Optional per-request timeout used for MCP client session calls.
	ClientSessionTimeout time.Duration

	// Whether to cache the tools list. If `true`, the tools list will be
	// cached and only fetched from the server once. If `false`, the tools list will be
	// fetched from the server on each call to `ListTools()`. The cache can be
	// invalidated by calling `InvalidateToolsCache()`. You should set this to `true`
	// if you know the server will not change its tools list, because it can drastically
	// improve latency (by avoiding a round-trip to the server every time).
	CacheToolsList bool

	// A readable name for the server. If not provided, we'll create one from the base URL.
	Name string

	// Optional tool filter to use for filtering tools
	ToolFilter MCPToolFilter

	// Whether to use `StructuredContent` when calling an MCP tool.
	// Defaults to false for backwards compatibility - most MCP servers still include
	// the structured content in `Content`, and using it by default will cause duplicate
	// content. You can set this to true if you know the server will not duplicate
	// the structured content in `Content`.
	UseStructuredContent bool

	// Maximum number of retry attempts for ListTools/CallTool. Use -1 for unlimited retries.
	MaxRetryAttempts int

	// Base delay for exponential backoff between retries.
	RetryBackoffBase time.Duration

	// Optional approval policy for MCP tools on this server.
	RequireApproval any

	// Optional resolver for MCP request metadata (`_meta`) on tool calls.
	ToolMetaResolver MCPToolMetaResolver

	// Optional per-server override for MCP tool failure handling.
	FailureErrorFunction    *ToolErrorFunction
	FailureErrorFunctionSet bool
}

type MCPServerStdio struct {
	*MCPServerWithClientSession
}

type MCPServerStdioParams struct {
	// The command to run to start the server.
	Command *exec.Cmd

	// Optional client options, including MCP message handlers.
	ClientOptions *mcp.ClientOptions

	// Optional per-request timeout used for MCP client session calls.
	ClientSessionTimeout time.Duration

	// Whether to cache the tools list. If `true`, the tools list will be
	// cached and only fetched from the server once. If `false`, the tools list will be
	// fetched from the server on each call to `ListTools()`. The cache can be
	// invalidated by calling `InvalidateToolsCache()`. You should set this to `true`
	// if you know the server will not change its tools list, because it can drastically
	// improve latency (by avoiding a round-trip to the server every time).
	CacheToolsList bool

	// A readable name for the server. If not provided, we'll create one from the command.
	Name string

	// Optional tool filter to use for filtering tools
	ToolFilter MCPToolFilter

	// Whether to use `StructuredContent` when calling an MCP tool.
	// Defaults to false for backwards compatibility - most MCP servers still include
	// the structured content in `Content`, and using it by default will cause duplicate
	// content. You can set this to true if you know the server will not duplicate
	// the structured content in `Content`.
	UseStructuredContent bool

	// Maximum number of retry attempts for ListTools/CallTool. Use -1 for unlimited retries.
	MaxRetryAttempts int

	// Base delay for exponential backoff between retries.
	RetryBackoffBase time.Duration

	// Optional approval policy for MCP tools on this server.
	RequireApproval any

	// Optional resolver for MCP request metadata (`_meta`) on tool calls.
	ToolMetaResolver MCPToolMetaResolver

	// Optional per-server override for MCP tool failure handling.
	FailureErrorFunction    *ToolErrorFunction
	FailureErrorFunctionSet bool
}

type MCPServerStreamableHTTP struct {
	*MCPServerWithClientSession
	// contains filtered or unexported fields
}

type MCPServerStreamableHTTPParams struct {
	URL           string
	TransportOpts *mcp.StreamableClientTransport
	// Optional factory to build an HTTP client for Streamable HTTP transport.
	HTTPClientFactory func() *http.Client

	// Optional factory receiving resolved headers/timeout configuration.
	HTTPClientFactoryWithConfig func(headers map[string]string, timeout time.Duration) *http.Client

	// Optional static headers to attach to every Streamable HTTP request.
	Headers map[string]string

	// Optional request timeout for Streamable HTTP transport.
	// Defaults to 5 seconds.
	Timeout time.Duration

	// Optional SSE read timeout setting for parity with Python configuration.
	// Currently stored for observability; Go MCP transport does not expose a direct field.
	SSEReadTimeout time.Duration

	// Optional terminate-on-close behavior for parity with Python configuration.
	// Currently stored for observability; Go MCP transport does not expose a direct field.
	TerminateOnClose *bool

	// Optional client options, including MCP message handlers.
	ClientOptions *mcp.ClientOptions

	// Optional per-request timeout used for MCP client session calls.
	ClientSessionTimeout time.Duration

	// Whether to cache the tools list. If `true`, the tools list will be
	// cached and only fetched from the server once. If `false`, the tools list will be
	// fetched from the server on each call to `ListTools()`. The cache can be
	// invalidated by calling `InvalidateToolsCache()`. You should set this to `true`
	// if you know the server will not change its tools list, because it can drastically
	// improve latency (by avoiding a round-trip to the server every time).
	CacheToolsList bool

	// A readable name for the server. If not provided, we'll create one from the URL.
	Name string

	// Optional tool filter to use for filtering tools
	ToolFilter MCPToolFilter

	// Whether to use `StructuredContent` when calling an MCP tool.
	// Defaults to false for backwards compatibility - most MCP servers still include
	// the structured content in `Content`, and using it by default will cause duplicate
	// content. You can set this to true if you know the server will not duplicate
	// the structured content in `Content`.
	UseStructuredContent bool

	// Maximum number of retry attempts for ListTools/CallTool. Use -1 for unlimited retries.
	MaxRetryAttempts int

	// Base delay for exponential backoff between retries.
	RetryBackoffBase time.Duration

	// Optional approval policy for MCP tools on this server.
	RequireApproval any

	// Optional resolver for MCP request metadata (`_meta`) on tool calls.
	ToolMetaResolver MCPToolMetaResolver

	// Optional per-server override for MCP tool failure handling.
	FailureErrorFunction    *ToolErrorFunction
	FailureErrorFunctionSet bool
}

type MCPServerWithClientSession struct {
	// contains filtered or unexported fields
}

type MCPServerWithClientSessionParams struct {
	Name      string
	Transport mcp.Transport
	// Optional client options, including MCP message handlers.
	ClientOptions *mcp.ClientOptions

	// Optional per-request timeout used for MCP client session calls.
	// Applies to ListTools/CallTool/ListPrompts/GetPrompt.
	ClientSessionTimeout time.Duration

	// Whether to cache the tools list. If `true`, the tools list will be
	// cached and only fetched from the server once. If `false`, the tools list will be
	// fetched from the server on each call to `ListTools()`. The cache can be invalidated
	// by calling `InvalidateToolsCache()`. You should set this to `true` if you know the
	// server will not change its tools list, because it can drastically improve latency
	// (by avoiding a round-trip to the server every time).
	CacheToolsList bool

	// The tool filter to use for filtering tools.
	ToolFilter MCPToolFilter

	// Whether to use `StructuredContent` when calling an MCP tool.
	// Defaults to false for backwards compatibility - most MCP servers still include
	// the structured content in `Content`, and using it by default will cause duplicate
	// content. You can set this to true if you know the server will not duplicate
	// the structured content in `Content`.
	UseStructuredContent bool

	// Maximum number of retry attempts for ListTools/CallTool. Use -1 for unlimited retries.
	MaxRetryAttempts int

	// Base delay for exponential backoff between retries.
	RetryBackoffBase time.Duration

	// Optional approval policy for tools in this MCP server.
	// Supported forms:
	// - bool
	// - "always"/"never"
	// - map[string]bool
	// - map[string]string where values are "always"/"never"
	// - MCPRequireApprovalObject
	// - map[string]any using TS-style {always:{tool_names:[...]}, never:{tool_names:[...]}}
	RequireApproval any

	// Optional resolver for MCP request metadata (`_meta`) on tool calls.
	ToolMetaResolver MCPToolMetaResolver

	// Optional per-server override for MCP tool failure handling.
	// Set FailureErrorFunctionSet=true with nil FailureErrorFunction to re-raise errors.
	FailureErrorFunction    *ToolErrorFunction
	FailureErrorFunctionSet bool
}

type MCPToolApprovalFunction = func(context.Context, responses.ResponseOutputItemMcpApprovalRequest) (MCPToolApprovalFunctionResult, error)

type MCPToolApprovalFunctionResult struct {
	// Whether to approve the tool call.
	Approve bool

	// An optional reason, if rejected.
	Reason string
}

type MCPToolFilter interface {
	// FilterMCPTool determines whether a tool should be available (true) or
	// filtered out (false).
	FilterMCPTool(context.Context, MCPToolFilterContext, *mcp.Tool) (bool, error)
}

type MCPToolFilterContext struct {
	// The agent that is requesting the tool list.
	Agent *Agent

	// The name of the MCP server.
	ServerName string
}

type MCPToolFilterFunc func(context.Context, MCPToolFilterContext, *mcp.Tool) (bool, error)

type MCPToolFilterStatic struct {
	// Optional list of tool names to allow (whitelist).
	// If set (not nil), only these tools will be available.
	AllowedToolNames []string

	// Optional list of tool names to exclude (blacklist).
	// If set (not nil), these tools will be filtered out.
	BlockedToolNames []string
}

type MCPToolMetaContext struct {
	RunContext *RunContextWrapper[any]
	ServerName string
	ToolName   string
	Arguments  map[string]any
}

type MCPToolMetaResolver func(context.Context, MCPToolMetaContext) (map[string]any, error)

type MaxTurnsExceededError struct {
	*AgentsError
}

type MessageOutputItem struct {
	// The agent whose run caused this item to be generated.
	Agent *Agent

	// The raw response output message.
	RawItem responses.ResponseOutputMessage

	// Always `message_output_item`.
	Type string
}

type Model interface {
	// GetResponse returns the full model response from the model.
	GetResponse(context.Context, ModelResponseParams) (*ModelResponse, error)

	// StreamResponse streams a response from the model.
	StreamResponse(context.Context, ModelResponseParams, ModelStreamResponseCallback) error
}

type ModelBehaviorError struct {
	*AgentsError
}

type ModelCloser interface {
	Close() error
}

type ModelInputData struct {
	Input        []TResponseInputItem
	Instructions param.Opt[string]
}

type ModelProvider interface {
	// GetModel returns a model by name.
	GetModel(modelName string) (Model, error)
}

type ModelProviderCloser interface {
	Aclose(context.Context) error
}

type ModelResponse struct {
	// A list of outputs (messages, tool calls, etc.) generated by the model
	Output []TResponseOutputItem `json:"output,omitempty"`

	// The usage information for the response.
	Usage *usage.Usage `json:"usage,omitempty"`

	// Optional ID for the response which can be used to refer to the response in subsequent calls to the
	// model. Not supported by all model providers.
	// If using OpenAI models via the Responses API, this is the `ResponseID` parameter, and it can
	// be passed to `Runner.Run`.
	ResponseID string `json:"response_id,omitempty"`

	// Optional request identifier returned by the model provider (for transport-level diagnostics).
	RequestID string `json:"request_id,omitempty"`
}

type ModelResponseParams struct {
	// The system instructions to use.
	SystemInstructions param.Opt[string]

	// The input items to the model, in OpenAI Responses format.
	Input Input

	// The model settings to use.
	ModelSettings modelsettings.ModelSettings

	// The tools available to the model.
	Tools []Tool

	// Optional output type to use.
	OutputType OutputTypeInterface

	// The handoffs available to the model.
	Handoffs []Handoff

	// Tracing configuration.
	Tracing ModelTracing

	// Optional ID of the previous response. Generally not used by the model,
	// except for the OpenAI Responses API.
	PreviousResponseID string

	// Optional conversation ID for server-managed conversation state.
	ConversationID string

	// Optional prompt config to use for the model.
	Prompt responses.ResponsePromptParam
}

type ModelStreamResponseCallback = func(context.Context, TResponseStreamEvent) error

type ModelTracing uint8

type MultiProvider struct {
	// Optional provider map.
	ProviderMap    *MultiProviderMap
	OpenAIProvider *OpenAIProvider
	// contains filtered or unexported fields
}

type MultiProviderMap struct {
	// contains filtered or unexported fields
}

type NewMultiProviderParams struct {
	// Optional MultiProviderMap that maps prefixes to ModelProviders. If not provided,
	// we will use a default mapping. See the documentation for MultiProvider to see the
	// default mapping.
	ProviderMap *MultiProviderMap

	// The API key to use for the OpenAI provider. If not provided, we will use
	// the default API key.
	OpenaiAPIKey param.Opt[string]

	// The base URL to use for the OpenAI provider. If not provided, we will
	// use the default base URL.
	OpenaiBaseURL param.Opt[string]

	// Optional websocket base URL for OpenAI Responses websocket transport.
	OpenaiWebsocketBaseURL param.Opt[string]

	// Optional OpenAI client to use. If not provided, we will create a new
	// OpenAI client using the OpenaiAPIKey and OpenaiBaseURL.
	OpenaiClient *OpenaiClient

	// The organization to use for the OpenAI provider.
	OpenaiOrganization param.Opt[string]

	// The project to use for the OpenAI provider.
	OpenaiProject param.Opt[string]

	// Whether to use the OpenAI responses API.
	OpenaiUseResponses param.Opt[bool]

	// Whether to use websocket transport for OpenAI responses API.
	OpenaiUseResponsesWebsocket param.Opt[bool]
}

type NextStep interface {
	// contains filtered or unexported methods
}

type NextStepFinalOutput struct {
	Output any
}

type NextStepHandoff struct {
	NewAgent *Agent
}

type NextStepInterruption struct {
	Interruptions []ToolApprovalItem
}

type NextStepRunAgain struct{}

type NoOpRunHooks struct{}

type NoOpVoiceWorkflowBaseOnStartResult struct{}

type OnHandoff interface {
	// contains filtered or unexported methods
}

type OnHandoffWithInput func(ctx context.Context, jsonInput any) error

type OnHandoffWithoutInput func(context.Context) error

type OpenAIChatCompletionsModel struct {
	Model openai.ChatModel
	// contains filtered or unexported fields
}

type OpenAIProvider struct {
	// contains filtered or unexported fields
}

type OpenAIProviderParams struct {
	// The API key to use for the OpenAI client. If not provided, we will use the
	// default API key.
	APIKey param.Opt[string]

	// The base URL to use for the OpenAI client. If not provided, we will use the
	// default base URL.
	BaseURL param.Opt[string]

	// Optional websocket base URL used by the Responses websocket transport.
	WebsocketBaseURL param.Opt[string]

	// An optional OpenAI client to use. If not provided, we will create a new
	// OpenAI client using the APIKey and BaseURL.
	OpenaiClient *OpenaiClient

	// The organization to use for the OpenAI client.
	Organization param.Opt[string]

	// The project to use for the OpenAI client.
	Project param.Opt[string]

	// Whether to use the OpenAI responses API.
	UseResponses param.Opt[bool]

	// Whether to use websocket transport for the OpenAI responses API.
	UseResponsesWebsocket param.Opt[bool]
}