toolkit

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:

Framework	Package	Best For
Vercel AI SDK	@picahq/toolkit	Next.js apps, streaming UIs
LangChain	pica-langchain	Python agents, chains
OpenAI Agents	@picahq/mcp	OpenAI's Agents SDK
MCP Server	@picahq/mcp	Claude Desktop, any MCP client

---

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

Level	HTTP Methods	Use Case
read	GET only	Customer-facing read access
write	GET, POST, PUT, PATCH	Standard operations
admin	All including DELETE	Full automation

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

Issue	Cause	Solution
No connections available	Missing connections or wrong filter	Check dashboard, verify connectors config
Actions won't execute	Permission denied or bad params	Check permissions level, verify action schema
System prompt too long	Too many connections/actions	Specify exact connections, use smaller action set
Authentication errors	Invalid or expired credentials	Verify API key, reconnect integration in dashboard
MCP server won't start	Node.js issue or missing env	Verify npx works, check PICA_SECRET is set
Rate limit errors	Too many requests	Implement backoff, reduce request frequency

---

API Reference

Pica Constructor

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

PicaOptions

Option	Type	Default	Description
connectors	string[]	["*"]	Connection keys to enable
actions	string[]	["*"]	Action IDs to enable
permissions	string	"admin"	"read" / "write" / "admin"
identity	string	-	User/team/org ID for filtering
identityType	string	-	"user" / "team" / "organization" / "project"
authkit	boolean	false	Enable connection prompts
serverUrl	string	https://api.picaos.com	Custom API server
headers	Record<string, string>	{}	Additional HTTP headers

Pica Methods

Method	Returns	Description
tools()	ToolSet	Tools for Vercel AI SDK
systemPrompt	string	Generated system prompt
generateSystemPrompt(custom?, separator?)	string	Combined prompt
getConnectedIntegrations()	Promise<Connection[]>	User's connections
getAvailableConnectors()	Promise<Connector[]>	All 200+ platforms
getAvailableActions(platform)	Promise<Action[]>	Platform actions

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