Add comprehensive MkDocs documentation

.github/workflows/docs-check.yml

@@ -0,0 +1,35 @@
+name: Documentation Check
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs*.yml"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[dev]"
+
+      - name: Build documentation
+        run: mkdocs build --strict 2>&1 | tee build-log.txt
+
+      - name: Check for warnings
+        run: |
+          if grep -q "WARNING" build-log.txt; then
+            echo "Documentation build produced warnings:"
+            cat build-log.txt | grep "WARNING"
+            exit 1
+          else
+            echo "Documentation build completed successfully without warnings."
+          fi

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch: # Allow manual triggering
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[dev]"
+
+      - name: Deploy documentation
+        run: mkdocs gh-deploy --force

README.md

@@ -5,7 +5,7 @@
   >
 </h3>
 <div align="center">
-  <h3>Arcade Integration for OpenAI Agents</h3>
+  <h3>Arcade Library for OpenAI Agents</h3>
     <a href="https://github.com/your-organization/agents-arcade/blob/main/LICENSE">
   <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
 </a>
@@ -16,14 +16,16 @@
 
 <p align="center">
     <a href="https://docs.arcade.dev" target="_blank">Arcade Documentation</a> •
-    <a href="https://docs.arcade.dev/toolkits" target="_blank">Toolkits</a> •
+    <a href="https://docs.arcade.dev/toolkits" target="_blank">Integrations</a> •
     <a href="https://github.com/ArcadeAI/arcade-py" target="_blank">Arcade Python Client</a> •
     <a href="https://platform.openai.com/docs/guides/agents" target="_blank">OpenAI Agents</a>
 </p>
 
 # agents-arcade
 
-`agents-arcade` provides an integration between [Arcade](https://docs.arcade.dev) and the [OpenAI Agents Library](https://github.com/openai/openai-python). This allows you to enhance your AI agents with Arcade's extensive toolkit ecosystem, including tools that reqwuire authorization like Google Mail, Linkedin, X, and more.
+`agents-arcade` provides an integration between [Arcade](https://docs.arcade.dev) and the [OpenAI Agents Library](https://github.com/openai/openai-python). This allows you to enhance your AI agents with Arcade tools like Google Mail, Linkedin, X, or ones you build yourself with the [Tool SDK](https://github.com/ArcadeAI/arcade-ai).
+
+For a list of all hosted tools and auth providers you can use to build your own, see the [Arcade Integrations](https://docs.arcade.dev/toolkits) documentation.
 
 ## Installation
 
@@ -33,30 +35,42 @@ pip install agents-arcade
 
 ## Basic Usage
 
+Below shows a basic example of how to use the `agents-arcade` library to create an agent that can use the
+GitHub toolkit hosted in Arcade Cloud. You can use other hosted tools like Google, or you can build your own
+and host them to the agents library with the [Tool SDK](https://github.com/ArcadeAI/arcade-ai).
+
 ```python
-from agents import Agent, RunConfig, Runner
+from agents import Agent, Runner
 from arcadepy import AsyncArcade
 
 from agents_arcade import get_arcade_tools
+from agents_arcade.errors import AuthorizationError
 
 
 async def main():
     client = AsyncArcade()
-    tools = await get_arcade_tools(client, ["google"])
-
-    google_agent = Agent(
-        name="Google agent",
-        instructions="You are a helpful assistant that can assist with Google API calls.",
+    # Use the "github" toolkit for this example
+    # You can use other toolkits like "google", "linkedin", "x", etc.
+    tools = await get_arcade_tools(client, ["github"])
+
+    # Create an agent that can use the github toolkit
+    github_agent = Agent(
+        name="GitHub agent",
+        instructions="You are a helpful assistant that can assist with GitHub API calls.",
         model="gpt-4o-mini",
         tools=tools,
     )
 
-    result = await Runner.run(
-        starting_agent=google_agent,
-        input="What are my latest emails?",
-        context={"user_id": "[email protected]"},
-    )
-    print("Final output:\n\n", result.final_output)
+    try:
+        result = await Runner.run(
+            starting_agent=github_agent,
+            input="Star the arcadeai/arcade-ai repo",
+            # make sure you pass a UNIQUE user_id for auth
+            context={"user_id": "[email protected]"},
+        )
+        print("Final output:\n\n", result.final_output)
+    except AuthorizationError as e:
+        print("Please Login to Github:", e)
 
 
 if __name__ == "__main__":
@@ -65,32 +79,62 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+If you haven't auth'd Arcade with GitHub yet, you'll see a message similar to this:
+
+```bash
+> python examples/github.py
+Please Login to Github: Authorization required: https://github.com/login/oauth/authorize...
+```
+
+You can then visit the URL in your browser to auth'd Arcade with GitHub and run the script again.
+
+```bash
+> python examples/github.py
+The repository **arcadeai/arcade-ai** has been successfully starred! If you need any more assistance, feel free to ask.
+```
+
+You can also wait for authorization to complete before running the script using the helper
+methods in arcadepy.
+
+Once you have auth'd Arcade with a tool, you can use the tool in your agent by passing the `user_id`
+and never having to worry about auth'ing for that specific tool again.
+
 ## Key Features
 
 -   **Easy Integration**: Simple API (one function) to connect Arcade tools with OpenAI Agents
 -   **Extensive Toolkit Support**: Access to all Arcade toolkits including Gmail, Google Drive, Search, and more
 -   **Asynchronous Support**: Built with async/await for compatibility with OpenAI's Agent framework
 -   **Authentication Handling**: Manages authorization for tools requiring user permissions like Google, LinkedIn, etc
 
-## Available Toolkits
-
-Arcade provides many toolkits including:
-
--   **Google**: Gmail, Google Drive, Google Calendar
--   **Search**: Google search, Bing search
--   **Web**: Crawling, scraping, etc
--   **Github**: Repository operations
--   **Slack**: Sending messages to Slack
--   **LinkedIn**: Posting to LinkedIn
--   **X**: Posting and reading tweets on X
--   And many more
-
-For a complete list, see the [Arcade Toolkits documentation](https://docs.arcade.dev/toolkits).
-
 ## Authentication
 
 Many Arcade tools require user authentication. The authentication flow is managed by Arcade and can be triggered by providing a `user_id` in the context when running your agent. Refer to the Arcade documentation for more details on managing tool authentication.
 
 ## License
 
 This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Documentation
+
+The project documentation is available at [docs.arcadeai.dev/agents-arcade](https://docs.arcadeai.dev/agents-arcade/) and includes:
+
+-   Installation instructions
+-   Quickstart guides
+-   API reference
+-   Advanced usage patterns
+-   Toolkit guides
+-   Examples
+
+To build and serve the documentation locally:
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Serve the documentation
+make serve-docs
+# or
+mkdocs serve
+```
+
+Then visit `http://localhost:8000` in your browser.

agents_arcade/_utils.py

@@ -1,19 +1,22 @@
 import asyncio
 import json
+import os
 from typing import Any
 
 from arcadepy import AsyncArcade
 
 
-def convert_output_to_json(output: Any) -> str:
-    if isinstance(output, dict) or isinstance(output, list):
-        return json.dumps(output)
-    else:
-        return str(output)
-
-
-async def get_arcade_client() -> AsyncArcade:
-    return AsyncArcade()
+def get_arcade_client(
+    base_url: str = "https://api.arcade.dev",
+    api_key: str = os.getenv("ARCADE_API_KEY", None),
+    **kwargs: dict[str, Any],
+) -> AsyncArcade:
+    """
+    Returns an AsyncArcade client.
+    """
+    if api_key is None:
+        raise ValueError("ARCADE_API_KEY is not set")
+    return AsyncArcade(base_url=base_url, api_key=api_key, **kwargs)
 
 
 async def _get_arcade_tool_definitions(
@@ -53,3 +56,10 @@ async def _get_arcade_tool_definitions(
             tool_auth_requirements[tool_name] = requires_auth
 
     return tool_auth_requirements
+
+
+def convert_output_to_json(output: Any) -> str:
+    if isinstance(output, dict) or isinstance(output, list):
+        return json.dumps(output)
+    else:
+        return str(output)

agents_arcade/tools.py

@@ -1,5 +1,6 @@
 import json
 from functools import partial
+from typing import Any
 
 from agents.run_context import RunContextWrapper
 from agents.tool import FunctionTool
@@ -26,10 +27,12 @@ async def _authorize_tool(client: AsyncArcade, context: RunContextWrapper, tool_
 
 
 async def _async_invoke_arcade_tool(
-    context: RunContextWrapper, tool_args: str, tool_name: str, requires_auth: bool
+    context: RunContextWrapper,
+    tool_args: str,
+    tool_name: str,
+    requires_auth: bool,
+    client: AsyncArcade,
 ):
-    client = await get_arcade_client()
-
     args = json.loads(tool_args)
     if requires_auth:
         await _authorize_tool(client, context, tool_name)
@@ -47,8 +50,14 @@ async def _async_invoke_arcade_tool(
 
 
 async def get_arcade_tools(
-    client: AsyncArcade, toolkits: list[str], tools: list[str] | None = None
+    client: AsyncArcade | None = None,
+    toolkits: list[str] | None = None,
+    tools: list[str] | None = None,
+    **kwargs: dict[str, Any],
 ) -> list[FunctionTool]:
+    if not client:
+        client = get_arcade_client(**kwargs)
+
     tool_formats = await client.tools.formatted.list(toolkit=toolkits, format="openai")
     auth_spec = await _get_arcade_tool_definitions(client, toolkits, tools)
 
@@ -66,6 +75,7 @@ async def get_arcade_tools(
                 _async_invoke_arcade_tool,
                 tool_name=tool_name,
                 requires_auth=requires_auth,
+                client=client,
             ),
             strict_json_schema=False,
         )

build_docs.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+set -e  # Exit on first error
+
+# Check if virtual environment exists, if not create one
+if [ ! -d ".venv" ]; then
+    echo "Creating virtual environment..."
+    python -m venv .venv
+fi
+
+# Activate virtual environment
+if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+    source .venv/Scripts/activate
+else
+    source .venv/bin/activate
+fi
+
+# Install dependencies
+echo "Installing dependencies..."
+pip install -e ".[dev]"
+
+# Build the documentation
+echo "Building documentation..."
+mkdocs build
+
+# Optional: Serve the documentation locally
+if [[ "$1" == "--serve" ]]; then
+    echo "Serving documentation locally at http://localhost:8000"
+    mkdocs serve
+fi
+
+# Optional: Deploy to GitHub Pages
+if [[ "$1" == "--deploy" ]]; then
+    echo "Deploying documentation to GitHub Pages..."
+    mkdocs gh-deploy --force
+fi
+
+echo "Documentation build complete! Find the built site in the 'site' directory."