From 69dce1c34d88f693fc0c94195d260653e879e382 Mon Sep 17 00:00:00 2001 From: Wania Kazmi <112770629+Wania-Kazmi@users.noreply.github.com> Date: Thu, 15 May 2025 17:40:09 +0500 Subject: [PATCH 1/2] docs: clarify input and output guardrails in agent documentation + Correct Output guardrail first step. Enhanced the documentation for input and output guardrails by specifying that input guardrails apply only to the first agent in a sequence, while output guardrails apply only to the last agent. This clarification improves understanding of how guardrails function in agent chains. --- docs/guardrails.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guardrails.md b/docs/guardrails.md index 2f0be0f2..849f3465 100644 --- a/docs/guardrails.md +++ b/docs/guardrails.md @@ -17,19 +17,19 @@ Input guardrails run in 3 steps: !!! Note - Input guardrails are intended to run on user input, so an agent's guardrails only run if the agent is the *first* agent. You might wonder, why is the `guardrails` property on the agent instead of passed to `Runner.run`? It's because guardrails tend to be related to the actual Agent - you'd run different guardrails for different agents, so colocating the code is useful for readability. + Input guardrails are intended to run on user input, so an agent's guardrails only run if the agent is the *first* agent. **In a sequence or chain of agents, the 'first agent' is the entry point – the agent that directly receives the initial user's input. Therefore, input guardrails only check this agent’s input.** You might wonder, why is the `guardrails` property on the agent instead of passed to `Runner.run`? It's because guardrails tend to be related to the actual Agent - you'd run different guardrails for different agents, so colocating the code is useful for readability. ## Output guardrails Output guardrails run in 3 steps: -1. First, the guardrail receives the same input passed to the agent. +1. First, the guardrail receives the same output passed to the agent. 2. Next, the guardrail function runs to produce a [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput], which is then wrapped in an [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] 3. Finally, we check if [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] is true. If true, an [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] exception is raised, so you can appropriately respond to the user or handle the exception. !!! Note - Output guardrails are intended to run on the final agent output, so an agent's guardrails only run if the agent is the *last* agent. Similar to the input guardrails, we do this because guardrails tend to be related to the actual Agent - you'd run different guardrails for different agents, so colocating the code is useful for readability. + Output guardrails are intended to run on the final agent output, so an agent's guardrails only run if the agent is the *last* agent. **In a sequence or chain of agents, the 'last agent' is the one that produces the final output returned to the user. Therefore, output guardrails only check this agent’s output.** Similar to the input guardrails, we do this because guardrails tend to be related to the actual Agent - you'd run different guardrails for different agents, so colocating the code is useful for readability. ## Tripwires From 54d53622a186b87d0281cb605712bd839831962c Mon Sep 17 00:00:00 2001 From: Wania Kazmi <112770629+Wania-Kazmi@users.noreply.github.com> Date: Thu, 15 May 2025 18:56:36 +0500 Subject: [PATCH 2/2] docs: improve clarity in context usage example Updated the documentation in context.md to enhance clarity by modifying the example of passing context to the run methods. The change specifies the syntax more clearly, improving understanding for users. --- docs/context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/context.md b/docs/context.md index 4176ec51..b5d654a5 100644 --- a/docs/context.md +++ b/docs/context.md @@ -10,7 +10,7 @@ Context is an overloaded term. There are two main classes of context you might c This is represented via the [`RunContextWrapper`][agents.run_context.RunContextWrapper] class and the [`context`][agents.run_context.RunContextWrapper.context] property within it. The way this works is: 1. You create any Python object you want. A common pattern is to use a dataclass or a Pydantic object. -2. You pass that object to the various run methods (e.g. `Runner.run(..., **context=whatever**))`. +2. You pass that object to the various run methods (e.g., `Runner.run(..., context=your_context_object)`). 3. All your tool calls, lifecycle hooks etc will be passed a wrapper object, `RunContextWrapper[T]`, where `T` represents your context object type which you can access via `wrapper.context`. The **most important** thing to be aware of: every agent, tool function, lifecycle etc for a given agent run must use the same _type_ of context.