Pica ToolKit

Build AI agents that can interact with 200+ third-party integrations. ToolKit provides a unified interface across Vercel AI SDK, LangChain, OpenAI Agents, and MCP.

Overview

ToolKit gives your AI agents access to:

• 25,000+ actions across 200+ platforms (Gmail, Slack, HubSpot, Stripe, etc.)
• Built-in authentication and token management
• Rate limiting, retries, and error handling
• Schema validation via Pica's knowledge base

Prerequisites

• Pica API key from https://app.picaos.com/settings/api-keys
• At least one connected integration in the Pica dashboard
• LLM provider API key (OpenAI, Anthropic, Google, etc.)

Framework Selection

Choose your framework:

Vercel AI SDK

Installation

npm install @picahq/toolkit ai @ai-sdk/openai

Environment

PICA_SECRET_KEY=your_pica_secret_key
OPENAI_API_KEY=your_openai_key

Basic Usage

import { Pica } from "@picahq/toolkit";
import { openai } from "@ai-sdk/openai";
import { streamText } from "ai";

// Initialize Pica
const pica = new Pica(process.env.PICA_SECRET_KEY!, {
  connectors: ["*"],  // All connections, or specific keys
  actions: ["*"],     // All actions, or specific IDs
});

// Create streaming response
const result = streamText({
  model: openai("gpt-4o"),
  messages: [{ role: "user", content: "Send an email to team@example.com" }],
  tools: pica.tools(),
  system: pica.systemPrompt,
});

Configuration Options

const pica = new Pica(process.env.PICA_SECRET_KEY!, {
  // Connection filtering
  connectors: ["*"],                    // All, or ["live::gmail::default::abc123"]
  actions: ["*"],                       // All, or ["gmail-send-email"]

  // Permissions
  permissions: "admin",                 // "read" | "write" | "admin"

  // Multi-tenant
  identity: userId,                     // Filter by user/team/org
  identityType: "user",                 // "user" | "team" | "organization" | "project"

  // AuthKit (prompt users to connect)
  authkit: true,

  // Advanced
  serverUrl: "https://api.picaos.com",  // Custom server
  headers: {},                          // Additional headers
});

Permission Levels

Available Tools

When you call pica.tools(), these tools are available to the agent:

• listPicaConnections - List user's connected integrations
• searchPlatformActions - Find actions for a platform
• getActionsKnowledge - Get schema and parameters for an action
• execute - Execute an action on a connected platform
• promptToConnectIntegration - Prompt user to connect (with AuthKit)

Full API Route Example

import { Pica } from "@picahq/toolkit";
import { openai } from "@ai-sdk/openai";
import { streamText } from "ai";

export async function POST(req: Request) {
  const { messages } = await req.json();
  const userId = req.headers.get("x-user-id");

  if (!userId) {
    return new Response("Unauthorized", { status: 401 });
  }

  const pica = new Pica(process.env.PICA_SECRET_KEY!, {
    connectors: ["*"],
    actions: ["*"],
    permissions: "admin",
    identity: userId,
    identityType: "user",
    authkit: true,
  });

  const customPrompt = "You help users automate tasks across their connected tools.";

  const result = streamText({
    model: openai("gpt-4o"),
    messages,
    tools: pica.tools(),
    system: pica.generateSystemPrompt(customPrompt),
    maxSteps: 25,  // Prevent infinite loops
  });

  return result.toDataStreamResponse();
}

Custom System Prompt

// Combine your prompt with Pica's
const systemPrompt = pica.generateSystemPrompt(
  "You are a sales automation assistant.",
  "\n\n"  // Separator
);

// Or access Pica's prompt directly
console.log(pica.systemPrompt);

LangChain (Python)

Installation

pip install pica-langchain langchain-openai

Environment

export PICA_SECRET=your_pica_secret_key
export OPENAI_API_KEY=your_openai_key

Basic Usage

import os
from pica_langchain import PicaClient, create_pica_agent
from langchain_openai import ChatOpenAI
from langchain.agents import AgentType

# Initialize client
pica_client = PicaClient(secret=os.environ["PICA_SECRET"])
pica_client.initialize()

# Create agent
agent = create_pica_agent(
    client=pica_client,
    llm=ChatOpenAI(temperature=0, model="gpt-4o"),
    agent_type=AgentType.OPENAI_FUNCTIONS,
)

# Run
response = agent.invoke({"input": "List my Gmail labels"})
print(response["output"])

Configuration Options

from pica_langchain import PicaClient, PicaClientOptions

options = PicaClientOptions(
    connectors=["*"],           # All or specific connection keys
    permissions="admin",        # "read" | "write" | "admin"
    identity=user_id,           # Multi-tenant filtering
    identity_type="user",       # "user" | "team" | "organization" | "project"
    authkit=True,               # Enable connection prompts
    server_url=None,            # Custom server URL
)

pica_client = PicaClient(
    secret=os.environ["PICA_SECRET"],
    options=options,
)
pica_client.initialize()

Streaming

from langchain.callbacks import StreamingStdOutCallbackHandler

agent = create_pica_agent(
    client=pica_client,
    llm=ChatOpenAI(
        temperature=0,
        model="gpt-4o",
        streaming=True,
        callbacks=[StreamingStdOutCallbackHandler()],
    ),
    agent_type=AgentType.OPENAI_FUNCTIONS,
)

Adding Custom Tools

from langchain.tools import Tool

custom_tool = Tool(
    name="calculator",
    func=lambda x: eval(x),
    description="Evaluate math expressions",
)

agent = create_pica_agent(
    client=pica_client,
    llm=llm,
    agent_type=AgentType.OPENAI_FUNCTIONS,
    extra_tools=[custom_tool],
)

OpenAI Agents SDK

Installation

pip install openai-agents
npm install -g @picahq/mcp

Environment

export PICA_SECRET=your_pica_secret_key
export OPENAI_API_KEY=your_openai_key

Basic Usage

from agents import Agent, Runner
from agents.extensions.mcp import MCPServerManager
import os

# Initialize MCP server
mcp = MCPServerManager()
mcp.add_server(
    name="pica",
    command="npx",
    args=["@picahq/mcp"],
    env={"PICA_SECRET": os.getenv("PICA_SECRET")},
)

# Create agent with Pica tools
async with mcp:
    tools = await mcp.list_tools()

    agent = Agent(
        name="Assistant",
        instructions="""You help users with their connected integrations.

        Workflow:
        1. Use list_pica_integrations to see connections
        2. Use get_pica_platform_actions to find actions
        3. Use get_pica_action_knowledge for parameters
        4. Use execute_pica_action to run actions
        """,
        tools=tools,
    )

    result = await Runner.run(agent, "Send a Slack message to #general")
    print(result.final_output)

Available MCP Tools

• list_pica_integrations - View connected platforms
• get_pica_platform_actions - Discover available actions
• get_pica_action_knowledge - Get parameter schemas
• execute_pica_action - Execute an action

Agent Handoffs

# Specialist agent for integrations
integration_agent = Agent(
    name="Integration Specialist",
    instructions="Handle all third-party integration tasks.",
    tools=pica_tools,
)

# Main agent that can hand off
main_agent = Agent(
    name="Assistant",
    instructions="Route integration tasks to the specialist.",
    handoffs=[integration_agent],
)

Guardrails

from agents import GuardrailFunctionOutput, input_guardrail

@input_guardrail
async def block_sensitive_emails(ctx, agent, input_data):
    if "ceo@" in input_data.lower():
        return GuardrailFunctionOutput(
            output_info={"blocked": True},
            tripwire_triggered=True,
        )
    return GuardrailFunctionOutput(output_info={"blocked": False})

agent = Agent(
    name="Assistant",
    input_guardrails=[block_sensitive_emails],
    tools=tools,
)

MCP Server (Claude Desktop)

Installation

npm install -g @picahq/mcp

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pica": {
      "command": "npx",
      "args": ["@picahq/mcp"],
      "env": {
        "PICA_SECRET": "your_pica_secret_key"
      }
    }
  }
}

Available Tools in Claude

Once configured, Claude Desktop has access to:

• list_pica_integrations - "What integrations do I have connected?"
• get_pica_platform_actions - "What can I do with Gmail?"
• get_pica_action_knowledge - "How do I send an email?"
• execute_pica_action - "Send an email to john@example.com"

Best Practices

1. Specify Connections in Production

// Development - convenient
connectors: ["*"]

// Production - faster, more secure
connectors: ["live::gmail::default::abc123", "live::slack::default::xyz789"]

2. Use Appropriate Permissions

// Customer-facing: read-only
permissions: "read"

// Standard operations
permissions: "write"

// Internal automation only
permissions: "admin"

3. Always Filter by Identity in Multi-Tenant Apps

const pica = new Pica(secretKey, {
  identity: userId,
  identityType: "user",
});

4. Set Step Limits

// Vercel AI SDK
streamText({
  maxSteps: 25,  // Prevent infinite loops
});

5. Handle Errors Gracefully

try {
  const result = await streamText({ ... });
} catch (error) {
  if (error.message.includes("rate limit")) {
    // Retry with backoff
  }
}

Troubleshooting

API Reference

Pica Constructor

new Pica(secretKey: string, options?: PicaOptions)

PicaOptions

Pica Methods

Links

• Demo: https://github.com/picahq/toolkit-demo
• Actions Browser: https://app.picaos.com/tools
• Documentation: https://docs.picaos.com
• AuthKit: See authkit skill for OAuth widget setup