From 4c63ddf3c9d7094c720f8cffc4266ff0d3079224 Mon Sep 17 00:00:00 2001 From: Kazuhiro Sera Date: Fri, 22 May 2026 09:37:22 +0900 Subject: [PATCH] docs: changes for #3487 feature addition --- docs/guardrails.md | 1 + docs/realtime/guide.md | 4 +++- docs/realtime/quickstart.md | 2 +- docs/running_agents.md | 9 +++++++-- 4 files changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/guardrails.md b/docs/guardrails.md index 0965a417f1..ac7b0bcc72 100644 --- a/docs/guardrails.md +++ b/docs/guardrails.md @@ -57,6 +57,7 @@ Tool guardrails wrap **function tools** and let you validate or block tool calls - Input tool guardrails run before the tool executes and can skip the call, replace the output with a message, or raise a tripwire. - Output tool guardrails run after the tool executes and can replace the output or raise a tripwire. +- If a function tool requires approval, input tool guardrails normally run after approval and immediately before execution. Set [`RunConfig.tool_execution`][agents.run.RunConfig.tool_execution] to [`ToolExecutionConfig(pre_approval_tool_input_guardrails=True)`][agents.run.ToolExecutionConfig] when you want those input checks to run before the pending approval interruption is emitted. Calls that pass this pre-approval check are still checked again after approval before the tool executes. - Tool guardrails apply only to function tools created with [`function_tool`][agents.tool.function_tool]. Handoffs run through the SDK's handoff pipeline rather than the normal function-tool pipeline, so tool guardrails do not apply to the handoff call itself. Hosted tools (`WebSearchTool`, `FileSearchTool`, `HostedMCPTool`, `CodeInterpreterTool`, `ImageGenerationTool`) and built-in execution tools (`ComputerTool`, `ShellTool`, `ApplyPatchTool`, `LocalShellTool`) also do not use this guardrail pipeline, and [`Agent.as_tool()`][agents.agent.Agent.as_tool] does not currently expose tool-guardrail options directly. See the code snippet below for details. diff --git a/docs/realtime/guide.md b/docs/realtime/guide.md index a04ba9832a..7ba0904749 100644 --- a/docs/realtime/guide.md +++ b/docs/realtime/guide.md @@ -210,6 +210,8 @@ agent = RealtimeAgent( Function tools can require human approval before execution. When that happens, the session emits `tool_approval_required` and pauses the tool run until you call `approve_tool_call()` or `reject_tool_call()`. +If the tool also has input guardrails, those guardrails run immediately before execution after approval. To run them before the approval event is emitted, set `run_config={"tool_execution": {"pre_approval_tool_input_guardrails": True}}` when creating the session. Calls that pass this pre-approval check are still checked again after approval before execution. + ```python async for event in session: if event.type == "tool_approval_required": @@ -241,7 +243,7 @@ Bare `RealtimeAgent` handoffs are auto-wrapped, and `realtime_handoff(...)` lets ### Guardrails -Only output guardrails are supported for realtime agents. They run on debounced transcript accumulation rather than on every partial token, and they emit `guardrail_tripped` instead of raising an exception. +Realtime agents support output guardrails on agent responses and input guardrails on function-tool calls. Output guardrails run on debounced transcript accumulation rather than on every partial token, and they emit `guardrail_tripped` instead of raising an exception. ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail diff --git a/docs/realtime/quickstart.md b/docs/realtime/quickstart.md index 0223d78b84..8482ace31d 100644 --- a/docs/realtime/quickstart.md +++ b/docs/realtime/quickstart.md @@ -118,7 +118,7 @@ Once the basic session works, the settings most people reach for next are: - `audio.input.turn_detection` for automatic turn detection - `audio.output.voice` - `tool_choice`, `prompt`, `tracing` -- `async_tool_calls`, `guardrails_settings.debounce_text_length`, `tool_error_formatter` +- `async_tool_calls`, `tool_execution.pre_approval_tool_input_guardrails`, `guardrails_settings.debounce_text_length`, `tool_error_formatter` The older flat aliases such as `input_audio_format`, `output_audio_format`, `input_audio_transcription`, and `turn_detection` still work, but nested `audio` settings are preferred for new code. diff --git a/docs/running_agents.md b/docs/running_agents.md index ba6d395c99..f176c28c13 100644 --- a/docs/running_agents.md +++ b/docs/running_agents.md @@ -163,7 +163,7 @@ Nested handoffs are available as an opt-in beta. Enable the collapsed-transcript ##### `tool_execution` -Use `tool_execution` when you want the SDK to limit local function-tool concurrency for a run. +Use `tool_execution` when you want to configure SDK-side behavior for local function tools, such as limiting local function-tool concurrency for a run. ```python from agents import Agent, RunConfig, Runner, ToolExecutionConfig @@ -174,7 +174,10 @@ result = await Runner.run( agent, "Run the required tool calls.", run_config=RunConfig( - tool_execution=ToolExecutionConfig(max_function_tool_concurrency=2), + tool_execution=ToolExecutionConfig( + max_function_tool_concurrency=2, + pre_approval_tool_input_guardrails=True, + ), ), ) ``` @@ -183,6 +186,8 @@ result = await Runner.run( This is separate from provider-side [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls]. `parallel_tool_calls` controls whether the model is allowed to emit multiple tool calls in a single response. `tool_execution.max_function_tool_concurrency` controls how the SDK executes local function tool calls after the model has emitted them. +`pre_approval_tool_input_guardrails=False` preserves the default approval flow: if a function tool needs approval, the run pauses first and the tool input guardrails run only after approval, immediately before execution. Set it to `True` when you want function-tool input guardrails to run before the pending approval interruption is emitted. Calls that pass this pre-approval check still run the same input guardrails again after approval, so time-sensitive checks are revalidated before execution. + ##### `tool_error_formatter` Use `tool_error_formatter` to customize the message that is returned to the model when a tool call is rejected in an approval flow.