Metadata-Version: 2.4
Name: pydantic-ai-arcade
Version: 0.2.0
Summary: Arcade integration for Pydantic AI
Keywords: arcade,pydantic-ai,mcp,tool-calling,agents
Author: Tho Nguyen
Author-email: Tho Nguyen <contact@naiwaaa.simplelogin.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: arcadepy>=1.5.0
Requires-Dist: pydantic-ai-slim>=1.45.0
Requires-Python: >=3.10
Project-URL: Homepage, https://codeberg.org/naiwaaa/pydantic-ai-arcade
Project-URL: Documentation, https://codeberg.org/naiwaaa/pydantic-ai-arcade
Project-URL: Repository, https://codeberg.org/naiwaaa/pydantic-ai-arcade
Project-URL: Issues, https://codeberg.org/naiwaaa/pydantic-ai-arcade/issues
Description-Content-Type: text/markdown

# 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/)
