App Agents

App iframe (useAgent hook)
  → postMessage("second:agent:trigger")
    → AppAgentBridge (parent window)
      → POST /api/.../agent-runs              (create run)
      → POST /api/.../agent-runs/{runId}/stream?startOnly=1
        (start agent without opening a browser SSE stream)
        → Worker POST /sessions/{appId}__agent__{runId}/agent-run
          → AgentRunManager runs agent in background
          → Worker calls tools, writes data
          → Worker POSTs /api/internal/agent-run-complete when done

App iframe (callIntegrationTool)
  → postMessage("second:integration:execute")
    → AppIntegrationBridge (parent window)
      → POST /api/.../app-tools/{toolName}/execute
        → Verify approved agents.json appTools policy
        → Resolve app-scoped integration grant
        → Inject static secrets or current viewer OAuth token server-side
        → Execute bounded HTTP request
        → Return response to app code

{
  "appTools": [
    {
      "type": "custom",
      "name": "posthog_events_page",
      "displayName": "Fetch PostHog events page",
      "description": "Fetches one bounded page of PostHog events for app-side grouping.",
      "enabled": true,
      "integration": {
        "name": "PostHog",
        "domain": "posthog.com",
        "keySlug": "default"
      },
      "endpoint": {
        "method": "GET",
        "url": "https://app.posthog.com/api/projects/{{projectId}}/events/",
        "headers": { "Authorization": "Bearer {{secrets.POSTHOG_PERSONAL_API_KEY}}" },
        "queryParams": { "after": "{{after}}", "before": "{{before}}", "limit": "{{limit}}" }
      },
      "mockData": [
        { "results": [{ "distinct_id": "user_123", "event": "$pageview" }], "next": null },
        { "results": [{ "distinct_id": "user_456", "event": "signup" }], "next": null },
        { "results": [], "next": null }
      ]
    }
  ],
  "agents": [
    {
      "id": "lead-enricher",
      "name": "Lead Enricher",
      "description": "Searches the web to find current information about leads",
      "systemPrompt": "You are a lead enrichment specialist...",
      "dataCollections": ["leads"],
      "tools": [
        {
          "type": "builtin",
          "name": "WebSearch",
          "enabled": true,
          "recommended": true
        },
        {
          "type": "custom",
          "name": "hubspot_fetch_contacts",
          "displayName": "Fetch Contacts",
          "description": "Search and retrieve contacts from HubSpot CRM",
          "enabled": true,
          "recommended": true,
          "integration": {
            "name": "HubSpot",
            "domain": "hubapi.com",
            "setupSearchQuery": "How to get HubSpot API key"
          },
          "endpoint": {
            "method": "GET",
            "url": "https://api.hubapi.com/crm/v3/objects/contacts",
            "headers": { "Authorization": "Bearer {{secrets.HUBSPOT_PRIVATE_APP_TOKEN}}" },
            "queryParams": { "query": "{{query}}", "limit": "10" }
          },
          "responseSchema": {
            "type": "object",
            "description": "HubSpot contacts response"
          },
          "mockData": [
            { "id": "101", "properties": { "firstname": "Sarah", "lastname": "Chen" } },
            { "id": "102", "properties": { "firstname": "Marcus", "lastname": "Johnson" } },
            { "id": "103", "properties": { "firstname": "Priya", "lastname": "Patel" } }
          ]
        }
      ]
    }
  ]
}

{
  "integrations": [
    {
      "name": "Slack",
      "domain": "slack.com",
      "keySlug": "default",
      "keyName": "Slack post key for this app",
      "capabilityLabel": "Slack post",
      "why": "This app sends Slack messages.",
      "permissionGroups": [
        {
          "name": "Send messages",
          "description": "Allows the app to post messages into selected Slack channels.",
          "permissions": ["chat:write"]
        }
      ],
      "secrets": [
        {
          "name": "SLACK_BOT_TOKEN",
          "label": "Slack bot token",
          "description": "Paste the Bot User OAuth Token that starts with xoxb-.",
          "required": true
        }
      ],
      "setupInstructions": {
        "overview": "Create or update a Slack app, grant the bot scope, install it to the workspace, and paste the bot token in Second.",
        "steps": [
          {
            "title": "Open Slack apps",
            "description": "Go to [Slack | API apps](https://api.slack.com/apps) and create a new app or open the existing app you want Second to use.",
            "url": "https://api.slack.com/apps"
          }
        ],
        "links": [
          { "label": "Slack API apps", "url": "https://api.slack.com/apps" }
        ]
      }
    }
  ]
}

import { useAgent } from '@/lib/second-sdk';

function EnrichButton({ leadId }: { leadId: string }) {
  const { trigger, status, isRunning } = useAgent('lead-enricher');

  return (
    <button
      onClick={() => trigger(`Enrich lead ${leadId}`)}
      disabled={isRunning}
    >
      {isRunning ? 'Enriching...' : 'Enrich'}
    </button>
  );
}

const { agents } = useAgentList();
// agents: Array<{ id: string; name: string; description: string }>

import { callIntegrationTool } from '@/lib/second-sdk';

type EventsPage = {
  results: Array<{ distinct_id?: string; event?: string }>;
  next?: string | null;
};

const result = await callIntegrationTool<
  { projectId: string; after?: string; before?: string; limit: number },
  EventsPage
>('posthog_events_page', {
  projectId: '123',
  after: '2026-05-01',
  before: '2026-05-20',
  limit: 100,
});

if (!result.success) {
  throw new Error(result.error ?? 'PostHog request failed');
}

// App → Platform
second:agent:trigger      { agentId, prompt }
second:agents:list-request  {}
second:integration:execute  { toolName, input }
second:integration:report-failure { toolName, input, result, description, attemptedTask? }

// Platform → App
second:agent:update       { agentId, runId, status, result?, error? }
second:agents:list-response { agents: [...] }
second:integration:execute-response { success, data?, mock, mockReason?, statusCode?, error?, errorCode?, errorCategory?, resolution?, retryable?, canRequestBuilderRepair?, details? }
second:integration:report-failure-response { ok, status?, builderRunId?, error? }

const presentAgents = tool(
  "present_agents",
  "Present the agent configuration to the user for approval...",
  {},
  async () => {
    const agentsConfig = JSON.parse(readFileSync("agents.json", "utf-8"));
    // Validate agentsConfig.agents and return the card payload.
  },
);

type AppAgentRunDocument = {
  _id: string;
  appId: string;
  workspaceId: string;
  triggeredByUserId: string;
  triggeredByUserEmail: string;
  triggeredByUserName: string;
  sourceVersion?: "draft" | "published";
  agentId: string;
  agentName: string;
  prompt: string;
  status: "pending" | "running" | "streaming" | "completed" | "failed";
  result: unknown | null;
  messages: unknown[];
  sessionId: string | null;
  activeStreamId: string | null;
  usage: RunUsage | null;
  createdAt: Date;
  updatedAt: Date;
};

{
  "runId": "abc-123",
  "prompt": "Enrich lead Sarah Chen",
  "systemPrompt": "You are a lead enrichment specialist...",
  "agentConfig": { "id": "lead-enricher", "tools": [...], "dataCollections": ["leads"] },
  "allowedTools": ["WebSearch", "WebFetch", "mcp__app_data__update_app_data"],
  "workspaceId": "ws-1",
  "appId": "app-1",
  "callbackUrl": "http://web:3000/api/internal/agent-run-complete",
  "sourceFiles": { "src/App.tsx": "..." }
}