utils directory

Author: rm-openai

examples/basic/hello_world_jupyter.py

@@ -3,7 +3,7 @@
 agent = Agent(name="Assistant", instructions="You are a helpful assistant")
 
 # Intended for Jupyter notebooks where there's an existing event loop
-result = await Runner.run(agent, "Write a haiku about recursion in programming.") # type: ignore[top-level-await] # noqa: F704
+result = await Runner.run(agent, "Write a haiku about recursion in programming.")  # type: ignore[top-level-await] # noqa: F704
 print(result.final_output)
 
 # Code within code loops,

src/agents/_run_impl.py

@@ -25,7 +25,6 @@
 from openai.types.responses.response_input_param import ComputerCallOutput
 from openai.types.responses.response_reasoning_item import ResponseReasoningItem
 
-from . import _utils
 from .agent import Agent
 from .agent_output import AgentOutputSchema
 from .computer import AsyncComputer, Computer
@@ -59,6 +58,7 @@
  handoff_span,
  trace,
 )
+from .util import _coro, _error_tracing
 
 if TYPE_CHECKING:
  from .run import RunConfig
@@ -293,7 +293,7 @@ def process_model_response(
  elif isinstance(output, ResponseComputerToolCall):
  items.append(ToolCallItem(raw_item=output, agent=agent))
  if not computer_tool:
- _utils.attach_error_to_current_span(
+ _error_tracing.attach_error_to_current_span(
  SpanError(
  message="Computer tool not found",
  data={},
@@ -324,7 +324,7 @@ def process_model_response(
  # Regular function tool call
  else:
  if output.name not in function_map:
- _utils.attach_error_to_current_span(
+ _error_tracing.attach_error_to_current_span(
  SpanError(
  message="Tool not found",
  data={"tool_name": output.name},
@@ -368,7 +368,7 @@ async def run_single_tool(
  (
  agent.hooks.on_tool_start(context_wrapper, agent, func_tool)
  if agent.hooks
- else _utils.noop_coroutine()
+ else _coro.noop_coroutine()
  ),
  func_tool.on_invoke_tool(context_wrapper, tool_call.arguments),
  )
@@ -378,11 +378,11 @@ async def run_single_tool(
  (
  agent.hooks.on_tool_end(context_wrapper, agent, func_tool, result)
  if agent.hooks
- else _utils.noop_coroutine()
+ else _coro.noop_coroutine()
  ),
  )
  except Exception as e:
- _utils.attach_error_to_current_span(
+ _error_tracing.attach_error_to_current_span(
  SpanError(
  message="Error running tool",
  data={"tool_name": func_tool.name, "error": str(e)},
@@ -502,7 +502,7 @@ async def execute_handoffs(
  source=agent,
  )
  if agent.hooks
- else _utils.noop_coroutine()
+ else _coro.noop_coroutine()
  ),
  )
 
@@ -520,7 +520,7 @@ async def execute_handoffs(
  new_items=tuple(new_step_items),
  )
  if not callable(input_filter):
- _utils.attach_error_to_span(
+ _error_tracing.attach_error_to_span(
  span_handoff,
  SpanError(
  message="Invalid input filter",
@@ -530,7 +530,7 @@ async def execute_handoffs(
  raise UserError(f"Invalid input filter: {input_filter}")
  filtered = input_filter(handoff_input_data)
  if not isinstance(filtered, HandoffInputData):
- _utils.attach_error_to_span(
+ _error_tracing.attach_error_to_span(
  span_handoff,
  SpanError(
  message="Invalid input filter result",
@@ -591,7 +591,7 @@ async def run_final_output_hooks(
  hooks.on_agent_end(context_wrapper, agent, final_output),
  agent.hooks.on_end(context_wrapper, agent, final_output)
  if agent.hooks
- else _utils.noop_coroutine(),
+ else _coro.noop_coroutine(),
  )
 
  @classmethod
@@ -706,7 +706,7 @@ async def execute(
  (
  agent.hooks.on_tool_start(context_wrapper, agent, action.computer_tool)
  if agent.hooks
- else _utils.noop_coroutine()
+ else _coro.noop_coroutine()
  ),
  output_func,
  )
@@ -716,7 +716,7 @@ async def execute(
  (
  agent.hooks.on_tool_end(context_wrapper, agent, action.computer_tool, output)
  if agent.hooks
- else _utils.noop_coroutine()
+ else _coro.noop_coroutine()
  ),
  )
 

src/agents/_utils.py

@@ -6,8 +6,6 @@
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Callable, Generic, cast
 
-from . import _utils
-from ._utils import MaybeAwaitable
 from .guardrail import InputGuardrail, OutputGuardrail
 from .handoffs import Handoff
 from .items import ItemHelpers
@@ -16,6 +14,8 @@
 from .models.interface import Model
 from .run_context import RunContextWrapper, TContext
 from .tool import Tool, function_tool
+from .util import _transforms
+from .util._types import MaybeAwaitable
 
 if TYPE_CHECKING:
  from .lifecycle import AgentHooks
@@ -126,7 +126,7 @@ def as_tool(
  """
 
  @function_tool(
- name_override=tool_name or _utils.transform_string_function_style(self.name),
+ name_override=tool_name or _transforms.transform_string_function_style(self.name),
  description_override=tool_description or "",
  )
  async def run_agent(context: RunContextWrapper, input: str) -> str:

src/agents/agent.py

@@ -4,10 +4,10 @@
 from pydantic import BaseModel, TypeAdapter
 from typing_extensions import TypedDict, get_args, get_origin
 
-from . import _utils
 from .exceptions import ModelBehaviorError, UserError
 from .strict_schema import ensure_strict_json_schema
 from .tracing import SpanError
+from .util import _error_tracing, _json
 
 _WRAPPER_DICT_KEY = "response"
 
@@ -87,10 +87,10 @@ def validate_json(self, json_str: str, partial: bool = False) -> Any:
  """Validate a JSON string against the output type. Returns the validated object, or raises
  a `ModelBehaviorError` if the JSON is invalid.
  """
- validated = _utils.validate_json(json_str, self._type_adapter, partial)
+ validated = _json.validate_json(json_str, self._type_adapter, partial)
  if self._is_wrapped:
  if not isinstance(validated, dict):
- _utils.attach_error_to_current_span(
+ _error_tracing.attach_error_to_current_span(
  SpanError(
  message="Invalid JSON",
  data={"details": f"Expected a dict, got {type(validated)}"},
@@ -101,7 +101,7 @@ def validate_json(self, json_str: str, partial: bool = False) -> Any:
  )
 
  if _WRAPPER_DICT_KEY not in validated:
- _utils.attach_error_to_current_span(
+ _error_tracing.attach_error_to_current_span(
  SpanError(
  message="Invalid JSON",
  data={"details": f"Could not find key {_WRAPPER_DICT_KEY} in JSON"},

src/agents/agent_output.py

@@ -7,10 +7,10 @@
 
 from typing_extensions import TypeVar
 
-from ._utils import MaybeAwaitable
 from .exceptions import UserError
 from .items import TResponseInputItem
 from .run_context import RunContextWrapper, TContext
+from .util._types import MaybeAwaitable
 
 if TYPE_CHECKING:
  from .agent import Agent

src/agents/guardrail.py

@@ -8,12 +8,12 @@
 from pydantic import TypeAdapter
 from typing_extensions import TypeAlias, TypeVar
 
-from . import _utils
 from .exceptions import ModelBehaviorError, UserError
 from .items import RunItem, TResponseInputItem
 from .run_context import RunContextWrapper, TContext
 from .strict_schema import ensure_strict_json_schema
 from .tracing.spans import SpanError
+from .util import _error_tracing, _json, _transforms
 
 if TYPE_CHECKING:
  from .agent import Agent
@@ -104,7 +104,7 @@ def get_transfer_message(self, agent: Agent[Any]) -> str:
 
  @classmethod
  def default_tool_name(cls, agent: Agent[Any]) -> str:
- return _utils.transform_string_function_style(f"transfer_to_{agent.name}")
+ return _transforms.transform_string_function_style(f"transfer_to_{agent.name}")
 
  @classmethod
  def default_tool_description(cls, agent: Agent[Any]) -> str:
@@ -192,15 +192,15 @@ async def _invoke_handoff(
  ) -> Agent[Any]:
  if input_type is not None and type_adapter is not None:
  if input_json is None:
- _utils.attach_error_to_current_span(
+ _error_tracing.attach_error_to_current_span(
  SpanError(
  message="Handoff function expected non-null input, but got None",
  data={"details": "input_json is None"},
  )
  )
  raise ModelBehaviorError("Handoff function expected non-null input, but got None")
 
- validated_input = _utils.validate_json(
+ validated_input = _json.validate_json(
  json_str=input_json,
  type_adapter=type_adapter,
  partial=False,

src/agents/handoffs.py

@@ -7,7 +7,6 @@
 
 from openai.types.responses import ResponseCompletedEvent
 
-from . import Model, _utils
 from ._run_impl import (
  NextStepFinalOutput,
  NextStepHandoff,
@@ -33,14 +32,15 @@
 from .lifecycle import RunHooks
 from .logger import logger
 from .model_settings import ModelSettings
-from .models.interface import ModelProvider
+from .models.interface import Model, ModelProvider
 from .models.openai_provider import OpenAIProvider
 from .result import RunResult, RunResultStreaming
 from .run_context import RunContextWrapper, TContext
 from .stream_events import AgentUpdatedStreamEvent, RawResponsesStreamEvent
 from .tracing import Span, SpanError, agent_span, get_current_trace, trace
 from .tracing.span_data import AgentSpanData
 from .usage import Usage
+from .util import _coro, _error_tracing
 
 DEFAULT_MAX_TURNS = 10
 
@@ -193,7 +193,7 @@ async def run(
 
  current_turn += 1
  if current_turn > max_turns:
- _utils.attach_error_to_span(
+ _error_tracing.attach_error_to_span(
  current_span,
  SpanError(
  message="Max turns exceeded",
@@ -447,7 +447,7 @@ async def _run_input_guardrails_with_queue(
  for done in asyncio.as_completed(guardrail_tasks):
  result = await done
  if result.output.tripwire_triggered:
- _utils.attach_error_to_span(
+ _error_tracing.attach_error_to_span(
  parent_span,
  SpanError(
  message="Guardrail tripwire triggered",
@@ -511,7 +511,7 @@ async def _run_streamed_impl(
  streamed_result.current_turn = current_turn
 
  if current_turn > max_turns:
- _utils.attach_error_to_span(
+ _error_tracing.attach_error_to_span(
  current_span,
  SpanError(
  message="Max turns exceeded",
@@ -583,7 +583,7 @@ async def _run_streamed_impl(
  pass
  except Exception as e:
  if current_span:
- _utils.attach_error_to_span(
+ _error_tracing.attach_error_to_span(
  current_span,
  SpanError(
  message="Error in agent run",
@@ -615,7 +615,7 @@ async def _run_single_turn_streamed(
  (
  agent.hooks.on_start(context_wrapper, agent)
  if agent.hooks
- else _utils.noop_coroutine()
+ else _coro.noop_coroutine()
  ),
  )
 
@@ -705,7 +705,7 @@ async def _run_single_turn(
  (
  agent.hooks.on_start(context_wrapper, agent)
  if agent.hooks
- else _utils.noop_coroutine()
+ else _coro.noop_coroutine()
  ),
  )
 
@@ -796,7 +796,7 @@ async def _run_input_guardrails(
  # Cancel all guardrail tasks if a tripwire is triggered.
  for t in guardrail_tasks:
  t.cancel()
- _utils.attach_error_to_current_span(
+ _error_tracing.attach_error_to_current_span(
  SpanError(
  message="Guardrail tripwire triggered",
  data={"guardrail": result.guardrail.get_name()},
@@ -834,7 +834,7 @@ async def _run_output_guardrails(
  # Cancel all guardrail tasks if a tripwire is triggered.
  for t in guardrail_tasks:
  t.cancel()
- _utils.attach_error_to_current_span(
+ _error_tracing.attach_error_to_current_span(
  SpanError(
  message="Guardrail tripwire triggered",
  data={"guardrail": result.guardrail.get_name()},