feat: add OpenAI Agents SDK integration example and tests

Add comprehensive example showing how to use StackOne tools with OpenAI Agents SDK

Include tests for tool conversion and integration functionality

Demonstrate Agent and Runner usage with HRIS tools

Author: ryoppippi

examples/openai_agents_integration.py

@@ -0,0 +1,54 @@
+"""
+This example demonstrates how to use StackOne tools with OpenAI Agents SDK.
+
+```bash
+uv run examples/openai_agents_integration.py
+```
+"""
+
+from agents import Agent, Runner
+from dotenv import load_dotenv
+
+from stackone_ai import StackOneToolSet
+
+load_dotenv()
+
+account_id = "45072196112816593343"
+employee_id = "c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA"
+
+
+def openai_agents_integration() -> None:
+    """Example of using StackOne tools with OpenAI Agents SDK"""
+    # Initialize StackOne toolset
+    toolset = StackOneToolSet()
+    tools = toolset.get_tools("hris_*", account_id=account_id)
+
+    # Convert to OpenAI Agents format
+    openai_agents_tools = tools.to_openai_agents()
+    assert len(openai_agents_tools) > 0, "Expected at least one OpenAI Agents tool"
+
+    # Create an OpenAI Agent with StackOne tools
+    agent = Agent(
+        name="HR Assistant",
+        instructions="You are an HR assistant that can help with employee information using HRIS tools.",
+        tools=openai_agents_tools,
+    )
+
+    # Test the integration
+    result = Runner.run_sync(
+        agent,
+        f"Can you get me information about employee with ID: {employee_id}? Use the HRIS tools available to you.",
+    )
+
+    print("Agent response:", result.final_output)
+
+    # Verify tool usage
+    assert result.messages, "Expected messages from the agent"
+    tool_calls_made = any(
+        hasattr(msg, "tool_calls") and msg.tool_calls for msg in result.messages if hasattr(msg, "tool_calls")
+    )
+    print(f"Tool calls were made: {tool_calls_made}")
+
+
+if __name__ == "__main__":
+    openai_agents_integration()

tests/test_openai_agents.py

@@ -0,0 +1,93 @@
+"""Tests for OpenAI Agents SDK integration"""
+
+from collections.abc import Callable
+
+import pytest
+
+from stackone_ai import StackOneToolSet
+
+
+@pytest.fixture
+def toolset() -> StackOneToolSet:
+    """Create a toolset for testing"""
+    return StackOneToolSet(api_key="test-key")
+
+
+def test_single_tool_openai_agents_conversion(toolset: StackOneToolSet) -> None:
+    """Test converting a single tool to OpenAI Agents format"""
+    tools = toolset.get_tools("hris_get_employee")
+
+    if not tools.tools:
+        pytest.skip("No tools found for testing")
+
+    tool = tools.tools[0]
+    openai_agents_tool = tool.to_openai_agents()
+
+    # Verify it's a callable function tool
+    assert callable(openai_agents_tool)
+    assert isinstance(openai_agents_tool, Callable)
+
+
+def test_tools_openai_agents_conversion(toolset: StackOneToolSet) -> None:
+    """Test converting all tools to OpenAI Agents format"""
+    tools = toolset.get_tools("hris_*")
+
+    if not tools.tools:
+        pytest.skip("No tools found for testing")
+
+    openai_agents_tools = tools.to_openai_agents()
+
+    # Verify conversion
+    assert len(openai_agents_tools) == len(tools.tools)
+    assert all(callable(tool) for tool in openai_agents_tools)
+    assert all(isinstance(tool, Callable) for tool in openai_agents_tools)
+
+
+@pytest.mark.asyncio
+async def test_openai_agents_tool_execution(toolset: StackOneToolSet) -> None:
+    """Test that OpenAI Agents tools can be executed"""
+    tools = toolset.get_tools("hris_get_employee")
+
+    if not tools.tools:
+        pytest.skip("No tools found for testing")
+
+    tool = tools.tools[0]
+    openai_agents_tool = tool.to_openai_agents()
+
+    # Test that the tool function exists and is callable
+    assert callable(openai_agents_tool)
+    assert callable(openai_agents_tool)
+
+
+def test_openai_agents_tool_attributes(toolset: StackOneToolSet) -> None:
+    """Test that OpenAI Agents tools have proper attributes"""
+    tools = toolset.get_tools("hris_get_employee")
+
+    if not tools.tools:
+        pytest.skip("No tools found for testing")
+
+    tool = tools.tools[0]
+    openai_agents_tool = tool.to_openai_agents()
+
+    # Verify the tool has required attributes for function_tool
+    assert callable(openai_agents_tool)
+    # The function_tool decorator should preserve the original function properties
+    assert hasattr(openai_agents_tool, "__name__") or hasattr(openai_agents_tool, "__qualname__")
+
+
+def test_openai_agents_tool_naming(toolset: StackOneToolSet) -> None:
+    """Test that OpenAI Agents tools preserve naming"""
+    tools = toolset.get_tools("hris_get_employee")
+
+    if not tools.tools:
+        pytest.skip("No tools found for testing")
+
+    tool = tools.tools[0]
+    openai_agents_tool = tool.to_openai_agents()
+
+    # Verify function tool exists and is properly named
+    assert callable(openai_agents_tool)
+    # The function should be a decorated function with proper metadata
+    original_name = tool.name
+    assert original_name is not None
+    assert len(original_name) > 0