Use Arcade with OpenAI Agents

In this guide, let’s explore how to integrate Arcade tools into your OpenAI application. Follow the step-by-step instructions below.

Prerequisites

Obtain an Arcade API key

Set up your environment

Install the required packages, and ensure your environment variables are set with your Arcade :

Python

Terminal


pip install agents-arcade arcadepy

Configure API keys

Provide your Arcade . You can store it in environment variables or directly in your code:

Need an Arcade ? Visit the Get an API key page to create one.

Python


import os
 
os.environ["ARCADE_API_KEY"] = "YOUR_ARCADE_API_KEY"
# Or set it directly when initializing the client

Create and manage Arcade tools

Python

Use the get_arcade_tools function to retrieve tools from specific Servers:

Python


from arcadepy import AsyncArcade
from agents_arcade import get_arcade_tools
 
# Initialize the Arcade client
client = AsyncArcade()
 
# Get all tools from the "Gmail" MCP Server
tools = await get_arcade_tools(client, toolkits=["gmail"])
 
# You can request multiple MCP Servers at once
tools = await get_arcade_tools(client, toolkits=["gmail", "github", "linkedin"])
 
# You can request specific tools
tools = await get_arcade_tools(client, tools=["Gmail_ListEmails", "Slack_ListUsers", "Slack_SendDmToUser"])

Set up the agent with Arcade tools

Create an and provide it with the Arcade :

Python


from agents import Agent, Runner
 
# Create an agent with Gmail tools
google_agent = Agent(
    name="Gmail agent",
    instructions="You are a helpful assistant that can assist with Google API calls.",
    model="gpt-4o-mini",
    tools=tools,
)

Run the agent

Python

Run the , providing a user_id for authorization:

Python


try:
    result = await Runner.run(
        starting_agent=google_agent,
        input="What are my latest emails?",
        context={"user_id": "{arcade_user_id}"},
    )
    print("Final output:\n\n", result.final_output)
except AuthorizationError as e:
    print("Please Login to Google:", e)

Handle authentication

Python

If a requires authorization, an AuthorizationError will be raised with an authorization URL:

Python


from agents_arcade.errors import AuthorizationError
 
try:
    # Run agent code from earlier examples
    # ...
except AuthorizationError as e:
    print(f"Please visit this URL to authorize: {e}")
    # The URL contained in the error will take the user to the authorization page

Complete example

Here’s a complete example putting everything together:

Python


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, toolkits=["gmail"])
 
    google_agent = Agent(
        name="Google agent",
        instructions="You are a helpful assistant that can assist with Google API calls.",
        model="gpt-4o-mini",
        tools=tools,
    )
 
    try:
        result = await Runner.run(
            starting_agent=google_agent,
            input="What are my latest emails?",
            context={"user_id": "{arcade_user_id}"},
        )
        print("Final output:\n\n", result.final_output)
    except AuthorizationError as e:
        print("Please Login to Google:", e)
 
 
if __name__ == "__main__":
    import asyncio
 
    asyncio.run(main())

Tips for selecting tools

Relevance: Pick only the you need. Avoid using all tools at once.
identification: Always provide a unique and consistent user_id for each user. Use your internal or database user ID, not something entered by the user.

Next steps

Now that you have integrated Arcade tools into your OpenAI application, you can:

Experiment with different Servers, such as “Github” or “LinkedIn”
Customize the ’s instructions for specific tasks
Try out multi- systems using different Arcade
Build your own custom tools with the Arcade SDK

Enjoy exploring Arcade and building powerful AI-enabled Python applications!