@tryportal/agent-tools

Server-side helpers for Portal. Define tools the support agent can call in your own codebase, serve them from one route, and derive the keys the widget needs. Zero dependencies, WebCrypto only, Node 18+.

Tools in one route

import { p, portal } from "@tryportal/agent-tools";

export const { GET, POST } = portal({
  tools: {
    orderStatus: {
      description: "Look up the status of an order by its number.",
      input: { orderNumber: p.string("The order number, like ORD-1042.") },
      async execute({ orderNumber }) {
        return db.orders.findByNumber(orderNumber);
      },
    },
  },
});

Set PORTAL_KEY in your env, deploy, and open the route once: an unsigned GET connects the URL and starts the sync. risk: "high" on a tool makes every call wait for a teammate's approval in the inbox.

Works as a Next route handler, and anywhere else that speaks fetch Request and Response.

The widget key

import { publicKeyFromPortalKey } from "@tryportal/agent-tools";

const apiKey = publicKeyFromPortalKey(process.env.PORTAL_KEY!);

Derives the browser-safe portal_pk_ id for the @tryportal/widget component without exposing the secret half.

Identity verification

import { signPortalUser } from "@tryportal/agent-tools";

const hash = await signPortalUser(session.user.id);

Signs a user id with PORTAL_KEY so the widget can tie a conversation to a person across devices.

Docs

Tool patterns, risk levels, portal.config.ts, and the full reference: tryportal.app, or the source at github.com/tryportal/portal.