pydantic-ai-arcade 0.2.0

Arcade integration for Pydantic AI

Arcade.dev Integration for Pydantic AI

pydantic-ai-arcade is a lightweight integration layer that connects Arcade.dev MCP tools with Pydantic AI, enabling agents to securely interact with external services (Gmail, Slack, GitHub, and more) using type-safe interfaces.

Installation

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.

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

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

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.

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

Resources

• Arcade.dev Documentation
• Pydantic AI