Skills
▥NYC
skills/smithery/ai/toolkit

toolkit

SKILL.md

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

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

Weekly Installs
1
Repository
smithery/ai
First Seen
1 day ago
Installed on
claude-code1