Arcade Library for OpenAI Agents

Arcade Documentation • Integrations • Arcade Python Client • OpenAI Agents

agents-arcade

agents-arcade provides an integration between Arcade and the OpenAI Agents Library. 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.

For a list of all hosted tools and auth providers you can use to build your own, see the Arcade Integrations documentation.

Installation

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.

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()
    # Use the "github" toolkit for this example
    # You can use other toolkits like "google", "linkedin", "x", etc.
    tools = await get_arcade_tools(client, toolkits=["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,
    )

    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": "user@example.com"},
        )
        print("Final output:\n\n", result.final_output)
    except AuthorizationError as e:
        print("Please Login to GitHub:", e)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

If you haven't auth'd Arcade with GitHub yet, you'll see a message similar to this:

> 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.

> 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

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 and includes:

• Installation instructions
• Quickstart guides
• API reference
• Advanced usage patterns
• Toolkit guides
• Examples

To build and serve the documentation locally:

# Install development dependencies
pip install -e ".[dev]"

# Serve the documentation
make serve-docs
# or
mkdocs serve

Then visit http://localhost:8000 in your browser.