Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.picaos.com/llms.txt

Use this file to discover all available pages before exploring further.

npm version
Pica Mastra Banner
Pica’s ToolKit works seamlessly with Mastra agents and workflows. Since Mastra uses the Vercel AI SDK under the hood, you can give your Mastra agents access to 200+ integrations with intelligent action execution powered by Pica’s knowledge base.
For complete configuration options (connectors, actions, permissions, identity scoping), see the Vercel AI SDK integration documentation. This page focuses on Mastra-specific usage patterns.

​
Prerequisites

  1. Pica Account - Free account for managing integrations
  2. Pica API Key - API key from your Pica dashboard
  3. Mastra - Already installed and configured in your project
  4. LLM Provider - API key from your chosen provider

​
Installation

npm install @picahq/toolkit

​
Quick Start

Create a Mastra agent with Pica tools: 
import { Agent } from '@mastra/core';
import { Pica } from '@picahq/toolkit';

// Initialize Pica ToolKit
const pica = new Pica(process.env.PICA_SECRET_KEY!, {
  connectors: ["*"], // Access all connected integrations
  actions: ["*"]     // Access all available actions
});

// Create a Mastra agent with Pica tools
const integrationAgent = new Agent({
  name: 'integration-assistant',
  instructions: pica.systemPrompt, // Use Pica's system prompt
  model: {
    provider: 'openai',
    name: 'gpt-5'
  },
  tools: pica.tools() // Load Pica tools
});

// Generate a response
const result = await integrationAgent.generate(
  'Send an email summary of today\'s meetings to the team'
);

console.log(result.text);

​
Usage Patterns

​
Basic Agent with Tools

The simplest setup - an agent with full access to integrations:
Example
import { Agent } from '@mastra/core';
import { Pica } from '@picahq/toolkit';

const pica = new Pica(process.env.PICA_SECRET_KEY!, {
  connectors: ["*"],
  actions: ["*"],
  permissions: "admin" // Full access
});

const agent = new Agent({
  name: 'automation-agent',
  instructions: pica.systemPrompt,
  model: { provider: 'openai', name: 'gpt-5' },
  tools: pica.tools()
});

// Use the agent
const response = await agent.generate(
  'Create a new lead in Salesforce for John Doe at Acme Corp'
);

​
Agent with Memory and Tools

Combine Pica tools with Mastra’s memory capabilities:
Example
import { Agent } from '@mastra/core';
import { Pica } from '@picahq/toolkit';

const pica = new Pica(process.env.PICA_SECRET_KEY!, {
  connectors: ["*"],
  actions: ["*"]
});

const agent = new Agent({
  name: 'context-aware-agent',
  instructions: pica.generateSystemPrompt(
    'You are a helpful assistant with access to user integrations. Remember context from previous conversations.'
  ),
  model: { provider: 'anthropic', name: 'claude-3-5-sonnet-20241022' },
  tools: pica.tools(),
  enableMemory: true // Enable Mastra memory
});

// Agent remembers previous context
await agent.generate('What integrations do I have connected?', {
  threadId: 'user-123'
});

await agent.generate('Send an email using the last one mentioned', {
  threadId: 'user-123' // Same thread for context
});

​
Read-Only Agent

Restrict the agent to read-only operations:
Example
const pica = new Pica(process.env.PICA_SECRET_KEY!, {
  connectors: ["*"],
  actions: ["*"],
  permissions: "read" // Read-only access
});

const readOnlyAgent = new Agent({
  name: 'data-retrieval-agent',
  instructions: pica.systemPrompt,
  model: { provider: 'openai', name: 'gpt-5' },
  tools: pica.tools()
});

// Can read data but not modify
await readOnlyAgent.generate('Show me my last 5 Gmail emails');

​
Multi-Tenant Agent

Scope integrations to specific users:
Example
// Create agent for specific user
function createUserAgent(userId: string) {
  const pica = new Pica(process.env.PICA_SECRET_KEY!, {
    connectors: ["*"],
    actions: ["*"],
    identity: userId,
    identityType: "user"
  });

  return new Agent({
    name: `agent-${userId}`,
    instructions: pica.systemPrompt,
    model: { provider: 'openai', name: 'gpt-5' },
    tools: pica.tools()
  });
}

// Each user gets their own scoped agent
const userAgent = createUserAgent('user-123');
const response = await userAgent.generate(
  'Schedule a meeting for tomorrow at 2pm'
);

​
Agent in a Workflow

Use Pica-powered agents within Mastra workflows:
Example
import { Agent, Workflow } from '@mastra/core';
import { Pica } from '@picahq/toolkit';

const pica = new Pica(process.env.PICA_SECRET_KEY!, {
  connectors: ["*"],
  actions: ["*"]
});

const dataAgent = new Agent({
  name: 'data-processor',
  instructions: pica.systemPrompt,
  model: { provider: 'openai', name: 'gpt-5' },
  tools: pica.tools()
});

const workflow = new Workflow({
  name: 'lead-processing-workflow'
});

workflow
  .step('fetch-leads', {
    execute: async () => {
      return await dataAgent.generate(
        'Get all new leads from Salesforce created in the last 24 hours'
      );
    }
  })
  .then('enrich-leads', {
    execute: async ({ context }) => {
      const leads = context.fetch-leads;
      return await dataAgent.generate(
        `For each of these leads, search for company information: ${JSON.stringify(leads)}`
      );
    }
  })
  .then('send-summary', {
    execute: async ({ context }) => {
      const enrichedLeads = context.enrich-leads;
      return await dataAgent.generate(
        `Send a summary email of these enriched leads to sales@company.com: ${JSON.stringify(enrichedLeads)}`
      );
    }
  });

// Run the workflow
await workflow.execute();

​
Custom System Prompt

Combine your agent’s personality with Pica’s integration instructions: 
const pica = new Pica(process.env.PICA_SECRET_KEY!, {
  connectors: ["*"],
  actions: ["*"]
});

const customInstructions = `You are a friendly sales assistant named Sarah.
Your goal is to help sales teams manage their leads and follow-ups efficiently.
Always be professional and concise in your communications.`;

const agent = new Agent({
  name: 'sarah-sales-assistant',
  instructions: pica.generateSystemPrompt(customInstructions),
  model: { provider: 'openai', name: 'gpt-5' },
  tools: pica.tools()
});

​
Streaming Responses

Mastra supports streaming - use it with Pica tools for real-time responses: 
const pica = new Pica(process.env.PICA_SECRET_KEY!, {
  connectors: ["*"],
  actions: ["*"]
});

const agent = new Agent({
  name: 'streaming-agent',
  instructions: pica.systemPrompt,
  model: { provider: 'openai', name: 'gpt-5' },
  tools: pica.tools()
});

// Stream the response
const stream = await agent.stream(
  'Search my emails for any mentions of the Q4 budget and summarize them'
);

for await (const chunk of stream) {
  process.stdout.write(chunk.text);
}

​
Configuration Reference

All ToolKit configuration options are available: 
const pica = new Pica(process.env.PICA_SECRET_KEY!, {
  // Specify exact connections
  connectors: ["test::gmail::default::abc123"],
  
  // Limit to specific actions
  actions: ["conn_mod_def::GGSNOTZxFUU::ZWXBuJboTpS3Q_U06pF8gA"],
  
  // Set permission level
  permissions: "read", // "read" | "write" | "admin"
  
  // Multi-tenant scoping
  identity: "user_123",
  identityType: "user", // "user" | "team" | "organization" | "project"
  
  // Enable AuthKit integration
  authkit: true
});

View all configuration options

See the complete configuration reference in the Vercel AI SDK documentation

​
Best Practices

Use Pica-powered agents within Mastra workflows for deterministic multi-step processes. This gives you the flexibility of agentic tool calling combined with the reliability of workflow orchestration.
Enable Mastra’s memory features alongside Pica tools so your agent can reference previous conversations when executing integration actions.
const agent = new Agent({
  name: 'context-agent',
  instructions: pica.systemPrompt,
  model: { provider: 'openai', name: 'gpt-5' },
  tools: pica.tools(),
  enableMemory: true // Remember context
});
In multi-tenant applications, create separate agent instances with user-specific identity scoping:
function createUserAgent(userId: string) {
  const pica = new Pica(process.env.PICA_SECRET_KEY!, {
    connectors: ["*"],
    identity: userId,
    identityType: "user"
  });
  
  return new Agent({
    name: `agent-${userId}`,
    tools: pica.tools(),
    // ...
  });
}
Match permission levels to your use case:
  • Customer-facing agents: "read" or "write"
  • Internal automation: "admin"
  • Data retrieval: "read"

​
What’s next?

Full configuration options

View complete ToolKit configuration in the Vercel AI SDK docs

Mastra documentation

Learn more about Mastra agents, workflows, and memory

Browse available actions

Explore the 25,000+ actions across 200+ integrations

Get help

Contact support for assistance with your implementation