feat: Add OpenAI Agents SDK adapter

[omkartike]

Summary

Resolves #3 . This PR introduces a new adapter to natively support the OpenAI Agents SDK, converting its lifecycle hooks into AgentWatch Universal Events for full observability.

What Changed

• Created agentwatch/adapters/openai_agents.py with AgentWatchOpenAIAgentsAdapter.
• Mapped OpenAI Agent SDK hooks (on_agent_start, on_agent_end, on_tool_call, on_tool_result, on_handoff) to AgentWatch AgentEvent structures.
• Created unit tests in tests/test_openai_agents_adapter.py validating session lifecycle, tool execution, handoff, and argument parsing error resilience.
• Updated README.md and docs/getting-started.md with installation commands and example usage for the new OpenAI Agents integration.

Validation

• tested locally
• ran tests (all 5 tests passed via pytest)

Summary by CodeRabbit

• New Features

  • Added integration to track OpenAI Agents sessions, tool calls, tool results, and agent handoffs via event-driven reporting.

• Documentation

  • README “How It Works” updated to show OpenAI Agents in the feature grid.
  • Getting-started guide now includes installation and usage steps for the OpenAI Agents integration.

• Tests

  • Added tests covering session lifecycle, tool execution/results, handoffs, and argument parsing/error handling.

[coderabbitai]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Walkthrough

Adds AgentWatchOpenAIAgentsAdapter to convert OpenAI Agents SDK lifecycle hooks into AgentWatch events (session start/end, tool call/result, planner handoff), with argument normalization and truncated outputs, plus tests and docs showing installation and usage.

Changes

OpenAI Agents SDK Adapter Support

Layer / File(s)	Summary
Adapter implementation and event emission agentwatch/adapters/openai_agents.py	AgentWatchOpenAIAgentsAdapter initializes per-session state (session_id, agent_id, step counter, run-id map) and implements lifecycle methods: on_agent_start/on_agent_end (SESSION_START/SESSION_END with agent_name and status), on_tool_call (TOOL_CALL with extracted tool_name and normalized arguments, JSON-string parsing with fallback to {"raw": ...}), on_tool_result (TOOL_RESULT with success and truncated stringified output), and on_handoff (PLANNER_OUTPUT with handoff source/target).
Comprehensive test suite tests/test_openai_agents_adapter.py	Async pytest fixtures inject a MagicMock EventBus and construct the adapter. Tests verify session lifecycle events, tool call and result emissions, handoff metadata, JSON-string argument parsing, and invalid-JSON fallback behavior.
README and Getting-Started updates README.md, docs/getting-started.md	README replaces prior text with a feature grid adding "OpenAI Agents" to the Universal integrations list. Getting Started adds an "OpenAI Agents" subsection with pip install openai-agents and an example creating AgentWatchOpenAIAgentsAdapter(session_id="my-first-session") for OpenAI Agents hooks.

Sequence Diagram(s)

sequenceDiagram
  participant OpenAISDK as OpenAI Agents SDK
  participant Adapter as AgentWatchOpenAIAgentsAdapter
  participant EventBus as EventBus
  OpenAISDK->>Adapter: on_agent_start(agent)
  Adapter->>Adapter: _base() construct AgentEvent
  Adapter->>EventBus: emit SESSION_START with agent_name
  OpenAISDK->>Adapter: on_tool_call(tool_call)
  Adapter->>Adapter: extract tool_name, parse arguments
  Adapter->>EventBus: emit TOOL_CALL with ToolCallData
  OpenAISDK->>Adapter: on_tool_result(result)
  Adapter->>EventBus: emit TOOL_RESULT with output
  OpenAISDK->>Adapter: on_handoff(source, target)
  Adapter->>EventBus: emit PLANNER_OUTPUT with metadata
  OpenAISDK->>Adapter: on_agent_end(agent)
  Adapter->>EventBus: emit SESSION_END with status

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

level: intermediate, level2

Suggested reviewers

• sreerevanth

Poem

🐰 Whiskers twitch with delight—
A new adapter greets the light.
Agents call, tools reply,
Events hop by and by,
Rabbit applauds the tracing sight!

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR implements most core requirements: adapter class, required event mapping, unit tests, and documentation updates. However, the agent_name is hardcoded instead of dynamic, failing a reviewer-requested requirement.	Make AgentEvent.agent_name dynamic using getattr(agent, 'name', 'openai_agents') instead of hardcoding 'openai_agents' to meet the issue requirement of proper session tracking.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: Add OpenAI Agents SDK adapter' accurately and concisely describes the main change—implementing a new adapter for OpenAI Agents SDK support.
Out of Scope Changes check	✅ Passed	All changes are directly related to the OpenAI Agents SDK adapter requirement: adapter implementation, tests, README update, and getting-started documentation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d67ef46a-0f7f-4d9d-8e73-e410c59f8535

📥 Commits

Reviewing files that changed from the base of the PR and between 87507c0 and 9f280c0.

📒 Files selected for processing (4)

• README.md
• agentwatch/adapters/openai_agents.py
• docs/getting-started.md
• tests/test_openai_agents_adapter.py

[sreerevanth]

Great work on this 🚀

Before merge, please address the CodeRabbit note regarding agent_name.

The top-level AgentEvent.agent_name should reflect the actual runtime agent name rather than the static "openai_agents" value, since downstream consumers may rely on it for filtering/display.

Once that’s updated, this should be good to merge.

[sreerevanth]

Tests pass ✅ (5/5 — session lifecycle, tool call/result, handoff, string args, bad JSON args all green).

One change needed before merge:

agent_name should be dynamic, not hardcoded

In agentwatch/adapters/openai_agents.py, the AgentEvent is constructed with agent_name="openai_agents" (static string). The repo owner has asked that it reflect the actual runtime agent name so downstream consumers can filter/display by it.

Fix in _base():

def _base(self, event_type: EventType, run_id: str | None = None, agent: Any = None) -> AgentEvent:
    event = AgentEvent(
        session_id=self.session_id,
        agent_id=self.agent_id,
        agent_name=getattr(agent, 'name', None) or 'openai_agents',  # dynamic
        framework=AgentFramework.OPENAI_AGENTS,
        event_type=event_type,
        step_number=self._step_up(),
    )

Then pass agent=agent from each on_* callback. Once updated, this is ready to merge.

[sreerevanth]

Thanks @omkartike! Rebased locally onto current main (README conflicts resolved cleanly) and pytest reports 210 passed, 2 skipped — your 3 new tests for the OpenAI Agents adapter pass.

However, the maintainer's earlier change-request is still open. agentwatch/adapters/openai_agents.py:57 still uses the static value:

agent_name="openai_agents",

while lines 71 and 77 already extract the real runtime name into event.metadata["agent_name"]. Per the review, the top-level AgentEvent.agent_name should reflect the runtime name so downstream consumers can filter/display correctly.

Please update line 57 to something like:

agent_name=getattr(agent, "name", "openai_agents"),

(and probably do the same for the other AgentEvent(...) construction sites in that file, if any).

Also: please rebase onto current main. The PR's current diff against main shows ~6118 deletions of unrelated files (the branch is far behind):

git fetch upstream
git checkout add-openai-agents-adapter
git rebase upstream/main
# fix line 57 and re-amend if needed
git push --force-with-lease

Holding off on merge until those land. The adapter itself is solid, just need this last cleanup.

Label: level: advanced | NSoC 26'

[omkartike]

@sreerevanth fixed the issues can you review and let me know if there's anything needed to be add/update

[sreerevanth]

❌ Tests pass but merge is blocked by a pending review request. Please fix the following before this can be merged:

Issue (from repo owner @sreerevanth): In agentwatch/adapters/openai_agents.py, the AgentEvent.agent_name field is set to the static string "openai_agents" instead of the actual runtime agent name.

What needs fixing:

• Pass the real agent name (e.g. from the agent's name attribute) into agent_name when constructing AgentEvent objects in on_agent_start, on_agent_end, etc.
• Downstream consumers rely on this field for filtering/display, so a static value breaks that use case.

Once this is addressed, all 5 adapter tests still pass and the PR will be ready to merge.