pydantic-ai-arcade 0.2.0
Arcade integration for Pydantic AI
Requires Python: >=3.10
Keywords: arcade, pydantic-ai, mcp, tool-calling, agents

# Arcade.dev Integration for Pydantic AI

<p>
  <a href="https://pypi.python.org/pypi/pydantic-ai-arcade">
    <img src="https://img.shields.io/pypi/v/pydantic-ai-arcade.svg" alt="PyPI">
  </a>
  <a href="https://codeberg.org/naiwaaa/pydantic-ai-arcade">
    <img src="https://img.shields.io/pypi/pyversions/pydantic-ai-arcade.svg" alt="versions">
  </a>
  <a href="https://codeberg.org/naiwaaa/pydantic-ai-arcade/src/branch/main/LICENSE">
    <img src="https://img.shields.io/pypi/l/pydantic-ai-arcade.svg" alt="license">
  </a>
</p>

`pydantic-ai-arcade` is a lightweight integration layer that connects
[Arcade.dev](https://arcade.dev) MCP tools with [Pydantic AI](https://ai.pydantic.dev),
enabling agents to securely interact with external services (Gmail, Slack, GitHub, and
[more](https://docs.arcade.dev/en/resources/integrations)) using type-safe interfaces.

## Installation

```bash
pip install pydantic-ai-arcade
```

## Features

- **Easy Integration:** one call to fetch tools and wire them into Pydantic AI agents.
- **Extensive Toolkits:** Gmail, Google Drive, GitHub, Slack, LinkedIn, X, and more.
- **Async-first:** built with async/await for modern agent runtimes.
- **Authorization Handling:** supports Arcade MCP tools that require user consent
  (OAuth-style flows).

## Usage

### 1. Set your API key

Arcade uses an API key for tool discovery and execution.

```bash
export ARCADE_API_KEY="YOUR_ARCADE_API_KEY"
```

### 2. Define a user-aware run context

Authorization is scoped per user. Provide a stable, unique user identifier (e.g., your
internal user ID or email used for Arcade).

```py
from pydantic_ai_arcade import ToolRunContext


class AgentContext(ToolRunContext):
  def get_user_id(self, tool_name: str | None = None) -> str:
    # Use a unique ID for each user
    return "user_123"
```

### 3. Create tools and run a Pydantic AI agent

```py
import asyncio

from arcadepy import AsyncArcade
from pydantic_ai import Agent
from pydantic_ai_arcade import get_arcade_client, get_arcade_tools


async def main() -> None:
  client = AsyncArcade()
  ctx = AgentContext()
  tools = await get_arcade_tools(
    client,
    tools=["Gmail.ListEmails", "Gmail.SendEmail"],
    toolkits=["Slack"],
  )

  # authorize the tools
  for tool in tools:
    result = await client.tools.authorize(tool_name=tool.name, user_id=ctx.get_user_id())
    if result.status != "completed":
      print(f"Click this link to authorize {tool.name}:\n{result.url}")
    await client.auth.wait_for_completion(result)

  # create the agent
  agent = Agent(
    model="gpt-4o-mini",
    deps_type=AgentContext,
    tools=tools,
    system_prompt="You are a helpful assistant that can use Gmail and Slack tools.",
  )

  result = await agent.run(
    "Summarize my latest 3 emails and send the summary to #general.",
    deps=AgentContext(),
  )

  print(result.output)


if __name__ == "__main__":
  asyncio.run(main())
```

### Notes

#### Authorization behavior

- Tools that require user authorization will return a message containing the authorization
  URL. Once the user authorizes, re-run the request with the same `user_id`.
- Use a consistent `user_id` per user; Arcade persists authorization per tool and user.

#### Selecting tools and toolkits

Pick only the tools you need to keep the agent focused. You can request specific tools or
entire toolkits.

```py
tools = await get_arcade_tools(
  client,
  tools=["Gmail.ListEmails", "Gmail.SendEmail"],
  toolkits=["Slack"],
)
```

## Resources

- [Arcade.dev Documentation](https://docs.arcade.dev/en/home)
- [Pydantic AI](https://ai.pydantic.dev/)