sovara-openai-agents 0.1.0__tar.gz

sovara_openai_agents-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sovara Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sovara_openai_agents-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: sovara-openai-agents
+Version: 0.1.0
+Summary: Sovara recording for the OpenAI Agents SDK
+License-Expression: MIT
+Project-URL: Documentation, https://docs.sovara-labs.com/integrations/openai-agents
+Project-URL: Repository, https://github.com/SovaraLabs/sovara-openai-agents/tree/main/python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sovara<0.11,>=0.10
+Requires-Dist: openai-agents<0.14,>=0.13.6
+Dynamic: license-file
+
+# Sovara for the OpenAI Agents SDK (Python)
+
+Record OpenAI Agents tool calls in Sovara traces.
+
+```bash
+uv add sovara-openai-agents
+# or: pip install sovara-openai-agents
+```
+
+```python
+import sovara
+import sovara_openai_agents
+
+sovara.auto_instrument()  # model calls, through the HTTP client
+sovara_openai_agents.instrument()  # function tools as tool steps, agent tools as child traces
+```
+
+Call both once at startup, before creating agents. Inside a Sovara trace, function tools are
+recorded as tool steps and agent tools (`agent.as_tool()`) open a child trace with their input
+and output. Outside a trace, tools run unrecorded. Requires `openai-agents` 0.13.6 (the supported 0.13 series).
+
+## License
+
+MIT.

sovara_openai_agents-0.1.0/README.md

@@ -0,0 +1,24 @@
+# Sovara for the OpenAI Agents SDK (Python)
+
+Record OpenAI Agents tool calls in Sovara traces.
+
+```bash
+uv add sovara-openai-agents
+# or: pip install sovara-openai-agents
+```
+
+```python
+import sovara
+import sovara_openai_agents
+
+sovara.auto_instrument()  # model calls, through the HTTP client
+sovara_openai_agents.instrument()  # function tools as tool steps, agent tools as child traces
+```
+
+Call both once at startup, before creating agents. Inside a Sovara trace, function tools are
+recorded as tool steps and agent tools (`agent.as_tool()`) open a child trace with their input
+and output. Outside a trace, tools run unrecorded. Requires `openai-agents` 0.13.6 (the supported 0.13 series).
+
+## License
+
+MIT.

sovara_openai_agents-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sovara-openai-agents"
+version = "0.1.0"
+description = "Sovara recording for the OpenAI Agents SDK"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "sovara>=0.10,<0.11",
+    # Function-tool capture needs 0.13+. Tested with 0.13.6; see the dev group.
+    "openai-agents>=0.13.6,<0.14",
+]
+
+[project.urls]
+Documentation = "https://docs.sovara-labs.com/integrations/openai-agents"
+Repository = "https://github.com/SovaraLabs/sovara-openai-agents/tree/main/python"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["sovara_openai_agents*"]
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "ruff==0.17.2",
+    # The versions the contract tests target; openai-agents 0.24 changed the tool executor.
+    "openai==2.30.0",
+    "openai-agents==0.13.6",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E4", "E7", "E9", "F", "I", "UP", "B",
+    "D100", "D101", "D102", "D103", "D104", "D106", "D107",
+    "D200", "D205", "D400", "D401", "D419",
+    "ERA001", "PGH004", "RUF100",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D1"]
+
+[tool.ruff.lint.isort]
+# Sovara's own packages sort together, as in the sovara repository.
+known-first-party = ["sovara", "sovara_common", "sovara_openai_agents", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sovara_openai_agents-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sovara_openai_agents-0.1.0/src/sovara_openai_agents/__init__.py

@@ -0,0 +1,17 @@
+"""Record OpenAI Agents SDK tool calls in Sovara traces.
+
+Call ``instrument()`` once at startup, after importing ``agents``. Function tools are recorded as
+tool steps; agent tools open a child trace. Model calls are recorded by ``sovara.auto_instrument()``
+through the HTTP client.
+"""
+
+from __future__ import annotations
+
+__all__ = ["instrument"]
+
+
+def instrument() -> None:
+    """Record OpenAI Agents function and agent tools inside Sovara traces; idempotent."""
+    from sovara_openai_agents._patch import openai_agents_patch
+
+    openai_agents_patch()

sovara_openai_agents-0.1.0/src/sovara_openai_agents/_patch.py

@@ -0,0 +1,231 @@
+"""Record OpenAI Agents function tools and nested agent-tool traces."""
+
+from __future__ import annotations
+
+import json
+import logging
+from functools import wraps
+from typing import Any, Literal
+
+from sovara import Step, ToolCall
+from sovara import integration as instrumentation
+from sovara.integration import json_value, subtrace
+
+logger = logging.getLogger("sovara_openai_agents")
+
+_STEP_ATTR = "_sovara_openai_agents_step"
+
+
+def _is_agent_tool(func_tool: Any) -> bool:
+    return bool(getattr(func_tool, "_is_agent_tool", False))
+
+
+def _agent_tool_name(func_tool: Any) -> str:
+    agent_name = getattr(getattr(func_tool, "_agent_instance", None), "name", None)
+    return str(agent_name or func_tool.name)
+
+
+def _agent_tool_input(arguments: str) -> str:
+    parsed, parse_error = _parse_tool_arguments(arguments)
+    if parse_error is None and parsed is not None:
+        input_value = parsed.get("input")
+        if set(parsed) == {"input"} and isinstance(input_value, str):
+            return input_value
+    return arguments
+
+
+def _trace_io_text(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    return json.dumps(json_value(value), ensure_ascii=False, sort_keys=True)
+
+
+def _tool_namespace(tool_call: Any, func_tool: Any) -> str | None:
+    namespace = getattr(tool_call, "namespace", None) or getattr(func_tool, "_tool_namespace", None)
+    return namespace if isinstance(namespace, str) and namespace else None
+
+
+def _qualified_tool_name(tool_name: str, namespace: str | None) -> str:
+    return f"{namespace}.{tool_name}" if namespace else tool_name
+
+
+def _parse_tool_arguments(arguments: str) -> tuple[dict[str, Any] | None, str | None]:
+    if not arguments:
+        return {}, None
+
+    try:
+        parsed = json.loads(arguments)
+    except Exception as exc:
+        return None, f"Invalid JSON arguments: {exc}"
+
+    if not isinstance(parsed, dict):
+        return None, "Tool arguments must decode to a JSON object."
+
+    return parsed, None
+
+
+def _tool_call(func_tool: Any, tool_call: Any) -> ToolCall:
+    tool_name = str(func_tool.name)
+    namespace = _tool_namespace(tool_call, func_tool)
+    arguments = str(getattr(tool_call, "arguments", "") or "")
+    parsed_input, parse_error = _parse_tool_arguments(arguments)
+    metadata: dict[str, Any] = {
+        "tool_class": func_tool.__class__.__name__,
+        "strict_json_schema": bool(getattr(func_tool, "strict_json_schema", False)),
+        "is_agent_tool": bool(getattr(func_tool, "_is_agent_tool", False)),
+        "defer_loading": bool(getattr(func_tool, "defer_loading", False)),
+    }
+    if namespace:
+        metadata["tool_namespace"] = namespace
+    if parse_error is not None:
+        metadata["tool_arguments_raw"] = arguments
+        metadata["arguments_error"] = parse_error
+    return ToolCall(
+        name=_qualified_tool_name(tool_name, namespace),
+        arguments=json_value(parsed_input),
+        call_id=str(getattr(tool_call, "call_id", "") or "").strip() or None,
+        metadata=metadata,
+    )
+
+
+def _step_of(task_state: Any) -> Step | None:
+    return getattr(task_state, _STEP_ATTR, None)
+
+
+async def _log_trace_io(kind: Literal["input", "output"], text: str) -> None:
+    await instrumentation.alog_trace_io(kind, text)
+
+
+def openai_agents_patch() -> None:
+    """Install OpenAI Agents function-tool and agent-tool instrumentation once.
+
+    Missing agents support is a no-op. Wrap the batch executor and supported invoker
+    variant; capture is gated by the recording and tracing flag. Agent tools use child
+    traces; ordinary function tools are recorded as tool steps. Tool arguments and
+    results pass through unchanged.
+    """
+    try:
+        from agents.run_internal import tool_execution
+    except ImportError:
+        logger.info("openai-agents not installed, skipping openai-agents patches")
+        return
+
+    batch_executor_cls = tool_execution._FunctionToolBatchExecutor
+    if getattr(batch_executor_cls, "__sovara_openai_agents_patched__", False):
+        return
+
+    original_execute_single_tool_body = batch_executor_cls._execute_single_tool_body
+    original_invoke_tool_and_run_post_invoke = batch_executor_cls._invoke_tool_and_run_post_invoke
+    invoker_name = (
+        "_invoke_function_tool_with_metadata"
+        if hasattr(tool_execution, "_invoke_function_tool_with_metadata")
+        else "invoke_function_tool"
+    )
+    original_invoke_function_tool = getattr(tool_execution, invoker_name)
+    invoker_returns_metadata = invoker_name == "_invoke_function_tool_with_metadata"
+
+    @wraps(original_invoke_function_tool)
+    async def patched_invoke_function_tool(*, function_tool, context, arguments):
+        if not instrumentation.capture_active() or not _is_agent_tool(function_tool):
+            return await original_invoke_function_tool(
+                function_tool=function_tool,
+                context=context,
+                arguments=arguments,
+            )
+
+        async with subtrace(_agent_tool_name(function_tool)) as child_trace_id:
+            if child_trace_id:
+                await _log_trace_io("input", _agent_tool_input(arguments))
+            result = await original_invoke_function_tool(
+                function_tool=function_tool,
+                context=context,
+                arguments=arguments,
+            )
+            output = result.output if invoker_returns_metadata else result
+            if child_trace_id and output is not None:
+                await _log_trace_io("output", _trace_io_text(output))
+            return result
+
+    @wraps(original_execute_single_tool_body)
+    async def patched_execute_single_tool_body(
+        self,
+        *,
+        outer_task,
+        task_state,
+        func_tool,
+        tool_call,
+        tool_context,
+        agent_hooks,
+    ):
+        if not instrumentation.capture_active() or _is_agent_tool(func_tool):
+            return await original_execute_single_tool_body(
+                self,
+                outer_task=outer_task,
+                task_state=task_state,
+                func_tool=func_tool,
+                tool_call=tool_call,
+                tool_context=tool_context,
+                agent_hooks=agent_hooks,
+            )
+
+        step = await instrumentation.abegin(_tool_call(func_tool, tool_call))
+        if step is not None:
+            setattr(task_state, _STEP_ATTR, step)
+
+        return await original_execute_single_tool_body(
+            self,
+            outer_task=outer_task,
+            task_state=task_state,
+            func_tool=func_tool,
+            tool_call=tool_call,
+            tool_context=tool_context,
+            agent_hooks=agent_hooks,
+        )
+
+    @wraps(original_invoke_tool_and_run_post_invoke)
+    async def patched_invoke_tool_and_run_post_invoke(
+        self,
+        *,
+        outer_task,
+        task_state,
+        func_tool,
+        tool_call,
+        tool_context,
+        agent_hooks,
+    ):
+        step = _step_of(task_state)
+        if step is None:
+            return await original_invoke_tool_and_run_post_invoke(
+                self,
+                outer_task=outer_task,
+                task_state=task_state,
+                func_tool=func_tool,
+                tool_call=tool_call,
+                tool_context=tool_context,
+                agent_hooks=agent_hooks,
+            )
+
+        try:
+            final_result = await original_invoke_tool_and_run_post_invoke(
+                self,
+                outer_task=outer_task,
+                task_state=task_state,
+                func_tool=func_tool,
+                tool_call=tool_call,
+                tool_context=tool_context,
+                agent_hooks=agent_hooks,
+            )
+        except Exception as exc:
+            await instrumentation.areport(step, "fail", exc, propagating=True)
+            raise
+        except BaseException as exc:
+            instrumentation.report_in_background(step, "cancel", exc.__class__.__name__)
+            raise
+        await instrumentation.areport(step, "finish", json_value(final_result))
+        return final_result
+
+    batch_executor_cls._execute_single_tool_body = patched_execute_single_tool_body
+    batch_executor_cls._invoke_tool_and_run_post_invoke = patched_invoke_tool_and_run_post_invoke
+    setattr(tool_execution, invoker_name, patched_invoke_function_tool)
+    batch_executor_cls.__sovara_openai_agents_patched__ = True
+    logger.info("openai-agents patches applied")

sovara_openai_agents-0.1.0/src/sovara_openai_agents.egg-info/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: sovara-openai-agents
+Version: 0.1.0
+Summary: Sovara recording for the OpenAI Agents SDK
+License-Expression: MIT
+Project-URL: Documentation, https://docs.sovara-labs.com/integrations/openai-agents
+Project-URL: Repository, https://github.com/SovaraLabs/sovara-openai-agents/tree/main/python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sovara<0.11,>=0.10
+Requires-Dist: openai-agents<0.14,>=0.13.6
+Dynamic: license-file
+
+# Sovara for the OpenAI Agents SDK (Python)
+
+Record OpenAI Agents tool calls in Sovara traces.
+
+```bash
+uv add sovara-openai-agents
+# or: pip install sovara-openai-agents
+```
+
+```python
+import sovara
+import sovara_openai_agents
+
+sovara.auto_instrument()  # model calls, through the HTTP client
+sovara_openai_agents.instrument()  # function tools as tool steps, agent tools as child traces
+```
+
+Call both once at startup, before creating agents. Inside a Sovara trace, function tools are
+recorded as tool steps and agent tools (`agent.as_tool()`) open a child trace with their input
+and output. Outside a trace, tools run unrecorded. Requires `openai-agents` 0.13.6 (the supported 0.13 series).
+
+## License
+
+MIT.

sovara_openai_agents-0.1.0/src/sovara_openai_agents.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/sovara_openai_agents/__init__.py
+src/sovara_openai_agents/_patch.py
+src/sovara_openai_agents.egg-info/PKG-INFO
+src/sovara_openai_agents.egg-info/SOURCES.txt
+src/sovara_openai_agents.egg-info/dependency_links.txt
+src/sovara_openai_agents.egg-info/requires.txt
+src/sovara_openai_agents.egg-info/top_level.txt
+tests/test_contract.py
+tests/test_recording.py
+tests/test_sovara_openai_agents.py

sovara_openai_agents-0.1.0/src/sovara_openai_agents.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sovara_openai_agents-0.1.0/src/sovara_openai_agents.egg-info/requires.txt

@@ -0,0 +1,2 @@
+sovara<0.11,>=0.10
+openai-agents<0.14,>=0.13.6

sovara_openai_agents-0.1.0/src/sovara_openai_agents.egg-info/top_level.txt

@@ -0,0 +1 @@
+sovara_openai_agents

sovara_openai_agents-0.1.0/tests/test_contract.py

@@ -0,0 +1,222 @@
+import asyncio
+import json
+from contextlib import asynccontextmanager, contextmanager
+
+from sovara import _recording, _steps
+from sovara._recording import TraceWriteCredentials
+from sovara.runner import context_manager
+from sovara_openai_agents import _patch as openai_agents_patch_module
+
+
+def _sdk():
+    from agents import Agent, RunConfig, RunContextWrapper, function_tool
+    from agents.lifecycle import RunHooks
+    from agents.run_internal import tool_execution
+    from agents.run_internal.run_steps import ToolRunFunction
+    from openai.types.responses import ResponseFunctionToolCall
+
+    return {
+        "Agent": Agent,
+        "RunConfig": RunConfig,
+        "RunContextWrapper": RunContextWrapper,
+        "RunHooks": RunHooks,
+        "ToolRunFunction": ToolRunFunction,
+        "ResponseFunctionToolCall": ResponseFunctionToolCall,
+        "FunctionToolBatchExecutor": tool_execution._FunctionToolBatchExecutor,
+        "AgentBindings": getattr(tool_execution, "AgentBindings", None),
+        "function_tool": function_tool,
+    }
+
+
+def _build_executor(tool, tool_call):
+    sdk = _sdk()
+    agent = sdk["Agent"](
+        name="Tool runner",
+        instructions="Use the tool.",
+        model="gpt-4o-mini",
+        tools=[tool],
+    )
+    executor_args = dict(
+        tool_runs=[sdk["ToolRunFunction"](tool_call=tool_call, function_tool=tool)],
+        hooks=sdk["RunHooks"](),
+        context_wrapper=sdk["RunContextWrapper"](context=None),
+        config=sdk["RunConfig"](),
+        isolate_parallel_failures=True,
+    )
+    if sdk["AgentBindings"] is None:
+        executor_args["agent"] = agent
+    else:
+        executor_args["bindings"] = sdk["AgentBindings"](
+            public_agent=agent,
+            execution_agent=agent,
+        )
+    return sdk["FunctionToolBatchExecutor"](**executor_args)
+
+
+class _FakeStep:
+    recorded = True
+
+    def __init__(self, call):
+        self.call = call
+        self.reports = []
+
+    async def afinish(self, output=None, **kwargs):
+        self.reports.append(("finish", output, kwargs))
+
+    async def afail(self, error=None, **kwargs):
+        self.reports.append(("fail", error, kwargs))
+
+
+def _fake_steps(monkeypatch) -> list[_FakeStep]:
+    steps = []
+
+    async def astart_step(call, *, lessons=False, step_uuid=None):
+        del lessons, step_uuid
+        steps.append(_FakeStep(call))
+        return steps[-1]
+
+    monkeypatch.setattr(_steps, "astart_step", astart_step)
+    return steps
+
+
+@contextmanager
+def _recording_context(trace_id: str):
+    recording = context_manager.RecordingContext(
+        owner=object(),
+        credentials=TraceWriteCredentials(
+            trace_id=trace_id,
+            recording_id=trace_id,
+            _trace_write_token=f"token-{trace_id}",
+        ),
+        lesson_scope_paths=None,
+    )
+    with context_manager.bind_recording_context(recording):
+        yield
+
+
+def test_openai_agents_contract_sdk_surface_available():
+    sdk = _sdk()
+    agent_tool = sdk["Agent"](name="Researcher", instructions="Research.").as_tool(
+        tool_name="researcher",
+        tool_description="Research a topic.",
+    )
+
+    assert callable(sdk["function_tool"])
+    assert hasattr(sdk["FunctionToolBatchExecutor"], "_execute_single_tool_body")
+    assert hasattr(sdk["FunctionToolBatchExecutor"], "_invoke_tool_and_run_post_invoke")
+    assert agent_tool._is_agent_tool is True
+    assert agent_tool._agent_instance.name == "Researcher"
+
+
+def test_openai_agents_patch_bypasses_tracing_without_recording(monkeypatch):
+    sdk = _sdk()
+    captured = {}
+    steps = _fake_steps(monkeypatch)
+
+    @sdk["function_tool"]
+    async def get_weather(city: str) -> dict[str, str]:
+        captured["called_with"] = city
+        return {"city": city}
+
+    tool_call = sdk["ResponseFunctionToolCall"](
+        arguments='{"city":"Zurich"}',
+        call_id="call_bypass",
+        name="get_weather",
+        type="function_call",
+    )
+
+    openai_agents_patch_module.openai_agents_patch()
+
+    executor = _build_executor(get_weather, tool_call)
+    results, _, _ = asyncio.run(executor.execute())
+
+    assert captured["called_with"] == "Zurich"
+    assert results[0].output == {"city": "Zurich"}
+    assert json.loads(tool_call.arguments) == {"city": "Zurich"}
+    assert steps == []
+
+
+def test_openai_agents_patch_records_function_tool_execution(monkeypatch):
+    sdk = _sdk()
+    captured = {}
+
+    @sdk["function_tool"]
+    async def get_weather(city: str) -> dict[str, str]:
+        captured["called_with"] = city
+        return {"forecast": f"sunny in {city}"}
+
+    tool_call = sdk["ResponseFunctionToolCall"](
+        arguments='{"city":"Zurich"}',
+        call_id="call_1",
+        name="get_weather",
+        type="function_call",
+    )
+
+    steps = _fake_steps(monkeypatch)
+    openai_agents_patch_module.openai_agents_patch()
+
+    executor = _build_executor(get_weather, tool_call)
+    with _recording_context("trace-1"):
+        results, _, _ = asyncio.run(executor.execute())
+
+    assert captured["called_with"] == "Zurich"
+    assert steps[0].call.name == "get_weather" and steps[0].call.call_id == "call_1"
+    assert steps[0].call.arguments == {"city": "Zurich"}
+    assert steps[0].reports == [("finish", {"forecast": "sunny in Zurich"}, {})]
+    assert results[0].output == {"forecast": "sunny in Zurich"}
+
+
+def test_openai_agents_patch_records_agent_tool_as_subtrace(monkeypatch):
+    sdk = _sdk()
+    captured = {"subtraces": [], "io": []}
+    steps = _fake_steps(monkeypatch)
+    agent_tool = sdk["Agent"](name="Researcher", instructions="Research.").as_tool(
+        tool_name="researcher",
+        tool_description="Research a topic.",
+    )
+
+    async def run_researcher(_context, input_json):
+        captured["trace_id"] = context_manager.get_trace_id()
+        return f"researched {json.loads(input_json)['input']}"
+
+    agent_tool.on_invoke_tool = run_researcher
+    tool_call = sdk["ResponseFunctionToolCall"](
+        arguments='{"input":"Zurich"}',
+        call_id="call_agent",
+        name="researcher",
+        type="function_call",
+    )
+
+    @asynccontextmanager
+    async def fake_subtrace(name):
+        captured["subtraces"].append(name)
+        with _recording_context("child-trace"):
+            yield "child-trace"
+
+    async def fake_log_trace_io(recording, kind, value):
+        captured["io"].append((recording.trace_id, kind, value))
+
+    monkeypatch.setattr(openai_agents_patch_module, "subtrace", fake_subtrace)
+    monkeypatch.setattr(_recording, "alog_trace_io", fake_log_trace_io)
+
+    openai_agents_patch_module.openai_agents_patch()
+    executor = _build_executor(agent_tool, tool_call)
+
+    async def execute():
+        with _recording_context("parent-trace"):
+            results, _, _ = await executor.execute()
+            assert context_manager.get_trace_id() == "parent-trace"
+            return results
+
+    results = asyncio.run(execute())
+
+    assert captured == {
+        "subtraces": ["Researcher"],
+        "io": [
+            ("child-trace", "input", "Zurich"),
+            ("child-trace", "output", "researched Zurich"),
+        ],
+        "trace_id": "child-trace",
+    }
+    assert results[0].output == "researched Zurich"
+    assert steps == []

sovara_openai_agents-0.1.0/tests/test_recording.py

@@ -0,0 +1,268 @@
+import asyncio
+import json
+import sys
+import types
+from contextlib import asynccontextmanager
+from types import SimpleNamespace
+
+from sovara import _recording
+from sovara.runner import context_manager
+from sovara_openai_agents import _patch as openai_agents_patch_module
+from tests.fake_steps import fake_steps, recording_context
+
+
+class _FakeFunctionTool:
+    def __init__(
+        self,
+        func,
+        *,
+        name: str = "get_weather",
+        namespace: str | None = None,
+        strict_json_schema: bool = False,
+        is_agent_tool: bool = False,
+        agent_name: str = "Research Agent",
+        defer_loading: bool = False,
+    ):
+        self._func = func
+        self.name = name
+        self._tool_namespace = namespace
+        self.strict_json_schema = strict_json_schema
+        self._is_agent_tool = is_agent_tool
+        self._agent_instance = SimpleNamespace(name=agent_name) if is_agent_tool else None
+        self.defer_loading = defer_loading
+
+    async def invoke(self, **kwargs):
+        return await self._func(**kwargs)
+
+
+def _make_tool_call(
+    *,
+    arguments: str = '{"city":"Zurich"}',
+    call_id: str = "call_1",
+    namespace: str | None = None,
+):
+    return SimpleNamespace(
+        arguments=arguments,
+        call_id=call_id,
+        name="get_weather",
+        namespace=namespace,
+        type="function_call",
+    )
+
+
+def _decode_tool_input(arguments: str) -> dict[str, object] | None:
+    if not arguments:
+        return {}
+    try:
+        parsed = json.loads(arguments)
+    except Exception:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _install_fake_agents_sdk(monkeypatch):
+    tool_execution_module = types.ModuleType("agents.run_internal.tool_execution")
+
+    async def invoke_function_tool(*, function_tool, context, arguments):
+        tool_input = context.tool_input
+        if tool_input is None:
+            tool_input = _decode_tool_input(arguments) or {}
+        return await function_tool.invoke(**tool_input)
+
+    tool_execution_module.invoke_function_tool = invoke_function_tool
+
+    class FakeBatchExecutor:
+        def __init__(self, *, func_tool, tool_call):
+            self.agent = SimpleNamespace(name="Tool runner")
+            self.func_tool = func_tool
+            self.tool_call = tool_call
+
+        async def _execute_single_tool_body(
+            self,
+            *,
+            outer_task,
+            task_state,
+            func_tool,
+            tool_call,
+            tool_context,
+            agent_hooks,
+        ):
+            del outer_task, task_state, func_tool, tool_call, tool_context, agent_hooks
+            return None
+
+        async def _invoke_tool_and_run_post_invoke(
+            self,
+            *,
+            outer_task,
+            task_state,
+            func_tool,
+            tool_call,
+            tool_context,
+            agent_hooks,
+        ):
+            del outer_task, task_state, tool_call, agent_hooks
+            return await tool_execution_module.invoke_function_tool(
+                function_tool=func_tool,
+                context=tool_context,
+                arguments=tool_context.tool_arguments,
+            )
+
+        async def execute(self):
+            task_state = SimpleNamespace()
+            tool_context = SimpleNamespace(
+                tool_arguments=str(getattr(self.tool_call, "arguments", "") or ""),
+                tool_call=self.tool_call,
+                tool_input=_decode_tool_input(str(getattr(self.tool_call, "arguments", "") or "")),
+            )
+            await self._execute_single_tool_body(
+                outer_task=None,
+                task_state=task_state,
+                func_tool=self.func_tool,
+                tool_call=self.tool_call,
+                tool_context=tool_context,
+                agent_hooks=None,
+            )
+            final_result = await self._invoke_tool_and_run_post_invoke(
+                outer_task=None,
+                task_state=task_state,
+                func_tool=self.func_tool,
+                tool_call=self.tool_call,
+                tool_context=tool_context,
+                agent_hooks=None,
+            )
+            return [SimpleNamespace(output=final_result)], None, None
+
+    tool_execution_module._FunctionToolBatchExecutor = FakeBatchExecutor
+
+    agents_module = types.ModuleType("agents")
+    agents_module.__path__ = []
+    trace_internal_module = types.ModuleType("agents.run_internal")
+    trace_internal_module.__path__ = []
+    trace_internal_module.tool_execution = tool_execution_module
+    agents_module.run_internal = trace_internal_module
+
+    monkeypatch.setitem(sys.modules, "agents", agents_module)
+    monkeypatch.setitem(sys.modules, "agents.run_internal", trace_internal_module)
+    monkeypatch.setitem(sys.modules, "agents.run_internal.tool_execution", tool_execution_module)
+
+    if hasattr(FakeBatchExecutor, "__sovara_openai_agents_patched__"):
+        delattr(FakeBatchExecutor, "__sovara_openai_agents_patched__")
+
+    return FakeBatchExecutor
+
+
+def test_openai_agents_patch_bypasses_tracing_without_recording(monkeypatch):
+    BatchExecutor = _install_fake_agents_sdk(monkeypatch)
+    steps = fake_steps(monkeypatch)
+    captured = {}
+
+    async def get_weather(city: str):
+        captured["called_with"] = city
+        return {"city": city}
+
+    tool = _FakeFunctionTool(get_weather)
+    tool_call = _make_tool_call(call_id="call_bypass")
+    openai_agents_patch_module.openai_agents_patch()
+
+    executor = BatchExecutor(func_tool=tool, tool_call=tool_call)
+    results, _, _ = asyncio.run(executor.execute())
+
+    assert captured["called_with"] == "Zurich"
+    assert results[0].output == {"city": "Zurich"}
+    assert json.loads(tool_call.arguments) == {"city": "Zurich"}
+    assert steps == []
+
+
+def test_openai_agents_patch_records_function_tool_execution(monkeypatch):
+    BatchExecutor = _install_fake_agents_sdk(monkeypatch)
+    steps = fake_steps(monkeypatch)
+
+    async def get_weather(city: str):
+        return {"forecast": f"sunny in {city}"}
+
+    tool = _FakeFunctionTool(get_weather)
+    tool_call = _make_tool_call(call_id="call_1")
+    openai_agents_patch_module.openai_agents_patch()
+
+    executor = BatchExecutor(func_tool=tool, tool_call=tool_call)
+    with recording_context():
+        results, _, _ = asyncio.run(executor.execute())
+
+    assert results[0].output == {"forecast": "sunny in Zurich"}
+    assert steps[0].call.name == "get_weather" and steps[0].call.call_id == "call_1"
+    assert steps[0].call.arguments == {"city": "Zurich"}
+    assert (steps[0].ending, steps[0].output) == ("finish", {"forecast": "sunny in Zurich"})
+
+
+def test_openai_agents_patch_fails_the_step_when_the_tool_raises(monkeypatch):
+    BatchExecutor = _install_fake_agents_sdk(monkeypatch)
+    steps = fake_steps(monkeypatch)
+
+    async def get_weather(city: str):
+        raise ValueError(city)
+
+    openai_agents_patch_module.openai_agents_patch()
+    executor = BatchExecutor(func_tool=_FakeFunctionTool(get_weather), tool_call=_make_tool_call())
+    with recording_context():
+        try:
+            asyncio.run(executor.execute())
+        except ValueError:
+            pass
+
+    assert steps[0].ending == "fail"
+    assert isinstance(steps[0].reports[0][1], ValueError)
+
+
+def test_openai_agents_patch_records_agent_tool_as_subtrace(monkeypatch):
+    BatchExecutor = _install_fake_agents_sdk(monkeypatch)
+    steps = fake_steps(monkeypatch)
+    captured = {"subtraces": [], "io": []}
+
+    async def run_researcher(input: str):
+        captured["trace_id"] = context_manager.get_trace_id()
+        return f"researched {input}"
+
+    tool = _FakeFunctionTool(
+        run_researcher,
+        name="researcher",
+        is_agent_tool=True,
+        agent_name="Researcher",
+    )
+    tool_call = _make_tool_call(
+        arguments='{"input":"Zurich"}',
+        call_id="call_agent",
+    )
+
+    @asynccontextmanager
+    async def fake_subtrace(name):
+        captured["subtraces"].append(name)
+        with recording_context("child-trace"):
+            yield "child-trace"
+
+    async def fake_log_trace_io(recording, kind, value):
+        captured["io"].append((recording.trace_id, kind, value))
+
+    monkeypatch.setattr(openai_agents_patch_module, "subtrace", fake_subtrace)
+    monkeypatch.setattr(_recording, "alog_trace_io", fake_log_trace_io)
+
+    openai_agents_patch_module.openai_agents_patch()
+    executor = BatchExecutor(func_tool=tool, tool_call=tool_call)
+
+    async def execute():
+        with recording_context("parent-trace"):
+            results, _, _ = await executor.execute()
+            assert context_manager.get_trace_id() == "parent-trace"
+            return results
+
+    results = asyncio.run(execute())
+
+    assert captured == {
+        "subtraces": ["Researcher"],
+        "io": [
+            ("child-trace", "input", "Zurich"),
+            ("child-trace", "output", "researched Zurich"),
+        ],
+        "trace_id": "child-trace",
+    }
+    assert results[0].output == "researched Zurich"
+    assert steps == []

sovara_openai_agents-0.1.0/tests/test_sovara_openai_agents.py

@@ -0,0 +1,197 @@
+"""Package tests that need no Sovara server; recording tests live in the Sovara repository."""
+
+import asyncio
+import json
+import sys
+import types
+from types import SimpleNamespace
+
+from sovara_openai_agents import _patch as openai_agents_patch_module
+
+
+class _FakeFunctionTool:
+    def __init__(
+        self,
+        func,
+        *,
+        name: str = "get_weather",
+        namespace: str | None = None,
+        strict_json_schema: bool = False,
+        is_agent_tool: bool = False,
+        agent_name: str = "Research Agent",
+        defer_loading: bool = False,
+    ):
+        self._func = func
+        self.name = name
+        self._tool_namespace = namespace
+        self.strict_json_schema = strict_json_schema
+        self._is_agent_tool = is_agent_tool
+        self._agent_instance = SimpleNamespace(name=agent_name) if is_agent_tool else None
+        self.defer_loading = defer_loading
+
+    async def invoke(self, **kwargs):
+        return await self._func(**kwargs)
+
+
+def _make_tool_call(
+    *,
+    arguments: str = '{"city":"Zurich"}',
+    call_id: str = "call_1",
+    namespace: str | None = None,
+):
+    return SimpleNamespace(
+        arguments=arguments,
+        call_id=call_id,
+        name="get_weather",
+        namespace=namespace,
+        type="function_call",
+    )
+
+
+def _decode_tool_input(arguments: str) -> dict[str, object] | None:
+    if not arguments:
+        return {}
+    try:
+        parsed = json.loads(arguments)
+    except Exception:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _install_fake_agents_sdk(monkeypatch):
+    tool_execution_module = types.ModuleType("agents.run_internal.tool_execution")
+
+    async def invoke_function_tool(*, function_tool, context, arguments):
+        tool_input = context.tool_input
+        if tool_input is None:
+            tool_input = _decode_tool_input(arguments) or {}
+        return await function_tool.invoke(**tool_input)
+
+    tool_execution_module.invoke_function_tool = invoke_function_tool  # pyright: ignore[reportAttributeAccessIssue]
+
+    class FakeBatchExecutor:
+        def __init__(self, *, func_tool, tool_call):
+            self.agent = SimpleNamespace(name="Tool runner")
+            self.func_tool = func_tool
+            self.tool_call = tool_call
+
+        async def _execute_single_tool_body(
+            self,
+            *,
+            outer_task,
+            task_state,
+            func_tool,
+            tool_call,
+            tool_context,
+            agent_hooks,
+        ):
+            del outer_task, task_state, func_tool, tool_call, tool_context, agent_hooks
+            return None
+
+        async def _invoke_tool_and_run_post_invoke(
+            self,
+            *,
+            outer_task,
+            task_state,
+            func_tool,
+            tool_call,
+            tool_context,
+            agent_hooks,
+        ):
+            del outer_task, task_state, tool_call, agent_hooks
+            return await tool_execution_module.invoke_function_tool(
+                function_tool=func_tool,
+                context=tool_context,
+                arguments=tool_context.tool_arguments,
+            )
+
+        async def execute(self):
+            task_state = SimpleNamespace()
+            tool_context = SimpleNamespace(
+                tool_arguments=str(getattr(self.tool_call, "arguments", "") or ""),
+                tool_call=self.tool_call,
+                tool_input=_decode_tool_input(str(getattr(self.tool_call, "arguments", "") or "")),
+            )
+            await self._execute_single_tool_body(
+                outer_task=None,
+                task_state=task_state,
+                func_tool=self.func_tool,
+                tool_call=self.tool_call,
+                tool_context=tool_context,
+                agent_hooks=None,
+            )
+            final_result = await self._invoke_tool_and_run_post_invoke(
+                outer_task=None,
+                task_state=task_state,
+                func_tool=self.func_tool,
+                tool_call=self.tool_call,
+                tool_context=tool_context,
+                agent_hooks=None,
+            )
+            return [SimpleNamespace(output=final_result)], None, None
+
+    tool_execution_module._FunctionToolBatchExecutor = FakeBatchExecutor  # pyright: ignore[reportAttributeAccessIssue]
+
+    agents_module = types.ModuleType("agents")
+    agents_module.__path__ = []
+    trace_internal_module = types.ModuleType("agents.run_internal")
+    trace_internal_module.__path__ = []
+    trace_internal_module.tool_execution = tool_execution_module  # pyright: ignore[reportAttributeAccessIssue]
+    agents_module.run_internal = trace_internal_module  # pyright: ignore[reportAttributeAccessIssue]
+
+    monkeypatch.setitem(sys.modules, "agents", agents_module)
+    monkeypatch.setitem(sys.modules, "agents.run_internal", trace_internal_module)
+    monkeypatch.setitem(sys.modules, "agents.run_internal.tool_execution", tool_execution_module)
+
+    if hasattr(FakeBatchExecutor, "__sovara_openai_agents_patched__"):
+        delattr(FakeBatchExecutor, "__sovara_openai_agents_patched__")
+
+    return FakeBatchExecutor
+
+
+def test_tool_call_keeps_raw_arguments_when_not_json_object():
+    async def get_weather(**kwargs):
+        return kwargs
+
+    tool = _FakeFunctionTool(get_weather)
+    tool_call = _make_tool_call(arguments='["Zurich"]', call_id="call_invalid")
+
+    call = openai_agents_patch_module._tool_call(tool, tool_call)
+
+    assert (call.name, call.call_id, call.arguments) == ("get_weather", "call_invalid", None)
+    assert call.metadata["tool_arguments_raw"] == '["Zurich"]'
+    assert call.metadata["arguments_error"] == "Tool arguments must decode to a JSON object."
+
+
+def test_tool_call_uses_tool_namespace_for_qualified_tool_name():
+    async def get_weather(**kwargs):
+        return kwargs
+
+    tool = _FakeFunctionTool(get_weather, namespace="weather")
+    tool_call = _make_tool_call(call_id="call_namespaced")
+
+    call = openai_agents_patch_module._tool_call(tool, tool_call)
+
+    assert call.name == "weather.get_weather"
+    assert call.metadata["tool_namespace"] == "weather"
+    assert call.arguments == {"city": "Zurich"}
+
+
+def test_openai_agents_patch_bypasses_tracing_without_recording(monkeypatch):
+    BatchExecutor = _install_fake_agents_sdk(monkeypatch)
+    captured = {}
+
+    async def get_weather(city: str):
+        captured["called_with"] = city
+        return {"city": city}
+
+    tool = _FakeFunctionTool(get_weather)
+    tool_call = _make_tool_call(call_id="call_bypass")
+    openai_agents_patch_module.openai_agents_patch()
+
+    executor = BatchExecutor(func_tool=tool, tool_call=tool_call)
+    results, _, _ = asyncio.run(executor.execute())
+
+    assert captured["called_with"] == "Zurich"
+    assert results[0].output == {"city": "Zurich"}
+    assert json.loads(tool_call.arguments) == {"city": "Zurich"}