Authorized Tool Calling

Arcade provides an authorization system that handles OAuth 2.0, API keys, and user tokens needed by AI agents to access external services through tools. This means your AI agents can now act on behalf of users securely and privately.

With Arcade, developers can now create agents that can as as the end user of their application to perform tasks like:

Creating a new Zoom meeting
Sending or reading email
Answering questions about files in Google Drive.

Arcade also allows for actions (tools) to be authorized directly. For example, to access a user’s Gmail account, you can utilize the following guide.

Initialize the client

Import the Arcade client in a Python/Javascript script. The client automatically finds API keys set by arcade login.

from arcadepy import Arcade
 
client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable

Authorize a tool directly

Many tools require authorization. For example, the Google.ListEmails tool requires authorization with Google.

This authorization must be approved by the user. By approving, the user allows your agent or app to access only the data they’ve approved.

# As the developer, you must identify the user you're authorizing
# and pass a unique identifier for them (e.g. an email or user ID) to Arcade:
THE_USER_ID = "[email protected]"
 
# Request access to the user's Gmail account
auth_response = client.tools.authorize(
  tool_name="Google.ListEmails",
  user_id=THE_USER_ID,
)
 
print(f"Click this link to authorize: {auth_response.url}")

This will print a URL that the user must visit to approve the authorization.

Check for authorization status

It may take a few minutes for the user to approve the authorization.

You can wait for the authorization to complete using the following methods:

auth_status = client.auth.wait_for_completion(auth_response)

Call the tool with authorization

Once the user has approved the action, you can run the tool. You only need to pass the user_id:

emails_response = client.tools.execute(
    tool_name="Google.ListEmails",
    user_id=THE_USER_ID,
)
print(emails_response)

Arcade remembers the user’s authorization tokens, so you don’t have to! Next time the user runs the same tool, they won’t have to go through the authorization process again until the auth expires or is revoked.

How it works

When you call a tool with client.tools.execute(), Arcade:

Checks for authorization.
Routes the request to the tool’s provider.
Returns the tool’s response.

With client.tools.authorize(), you can also authorize tools for later use.

These APIs give you programmatic control over tool calling. If you just want to integrate tools into a language model workflow, see Call tools with models.

Next steps

Once you’ve mastered tool calling, see how you can build your own tools to integrate any custom functionality or API to your AI workflows.

How Arcade helps Generic authorization