feat: Add Agno framework integration

[ryoppippi]

Summary

This PR adds comprehensive integration support for Agno, a high-performance multi-agent AI system framework.

🔗 About Agno

• GitHub: https://github.com/agno-agi/agno
• Documentation: https://docs.agno.com
• Website: https://www.agno.com

Changes Made

• Core Integration: Added to_agno() methods to both StackOneTool and Tools classes
• Example Implementation: Created agno_integration.py with both sync and async usage examples
• Comprehensive Testing: Added full test coverage for Agno integration with proper mocking
• Documentation Updates: Updated README, CLAUDE.md, and mkdocs navigation
• Dependency Management: Added Agno as an optional dependency with version constraint

Key Features

• Individual Tool Conversion: Convert single StackOne tools to Agno format
• Batch Conversion: Convert entire tool collections to Agno agents
• Async Support: Full async/await support for high-performance applications
• Error Handling: Proper ImportError handling when Agno is not installed
• Type Safety: MyPy configuration for optional dependency handling

Integration Example

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from stackone_ai import StackOneToolSet

# Initialize StackOne tools
toolset = StackOneToolSet()
tools = toolset.get_tools(["hris_get_employee"], account_id="your-account-id")

# Convert to Agno format  
agno_tools = tools.to_agno()

# Create Agno agent
agent = Agent(
    name="HR Assistant",
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=agno_tools,
    instructions=["You are a helpful HR assistant."]
)

# Use the agent
response = agent.run("Get employee information for ID 123")

Test Coverage

• Import error handling when Agno is not installed
• Tool conversion functionality with proper mocking
• Batch conversion for multiple tools
• Metadata preservation during conversion
• Integration with existing StackOne tool execution

Agno Compatibility

This integration is built for Agno v1.7.11 and uses the current function-based tool architecture:

• Uses @tool decorator instead of class-based tools
• Compatible with Agno's high-performance agent system
• Follows Agno's latest API patterns

Test Plan

• All existing tests continue to pass
• New Agno integration tests pass
• Example can be run with proper dependencies
• MyPy type checking passes
• Linting and formatting checks pass
• Documentation builds correctly
• GitHub Actions CI/CD passes

[cubic-dev-ai]

2 issues found across 9 files

_{React with 👍 or 👎 to teach cubic. You can also tag @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

[cubic-dev-ai]

Avoid hard-coding potentially sensitive account and employee identifiers; read them from environment variables or user input instead.

Prompt for AI agents

Address the following comment on examples/agno_integration.py at line 20:

<comment>Avoid hard-coding potentially sensitive account and employee identifiers; read them from environment variables or user input instead.</comment>

<file context>
@@ -0,0 +1,119 @@
+&quot;&quot;&quot;
+This example demonstrates how to use StackOne tools with Agno agents.
+
+This example is runnable with the following command:
+```bash
+uv run examples/agno_integration.py
+```
+
+You can find out more about Agno framework at https://docs.agno.com
</file context>

[cubic-dev-ai]

MagicMock instance used as base class stub—should pass a class, e.g. MagicMock(spec=type) or type('MockTool',(object,),{})

Prompt for AI agents

Address the following comment on tests/test_agno_integration.py at line 58:

<comment>MagicMock instance used as base class stub—should pass a class, e.g. MagicMock(spec=type) or type(&#39;MockTool&#39;,(object,),{})</comment>

<file context>
@@ -0,0 +1,164 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from stackone_ai.models import (
+    ExecuteConfig,
+    StackOneTool,
+    ToolParameters,
+    Tools,
</file context>