@sumup/agent-toolkit

SumUp Agent Toolkit - Typescript

Allow LLM agents to integrate with the SumUp API using function calling from frameworks such as LangChain, AI SDK, and the OpenAI Agents SDK. For full documentation, see sumup.github.io/sumup-ai.

Install

Install SumUp Agent Toolkit using:

npm install @sumup/agent-toolkit
# or
yarn add @sumup/agent-toolkit

Tool selection

All adapters accept includeTools, excludeTools, and readOnly. Without these options, the full catalog remains available. Exclusions take precedence; includeTools: [] exposes no tools. readOnly: true only includes tools explicitly marked read-only.

const sumupAgentToolkit = new SumUpAgentToolkit({
  apiKey: process.env.SUMUP_API_KEY!,
  includeTools: [
    "list_memberships",
    "list_transactions_v2_1",
    "get_transaction_v2_1",
  ],
  readOnly: true,
});

The MCP adapter also accepts transformTool, applied after selection, to customize a tool's descriptor, input schema, and callback together. For example, a hosted application can restrict checkout creation to Hosted Checkout without changing the shared API tool. Keep annotations accurate for the customized behavior.

Observability

Every adapter accepts optional redaction-safe lifecycle callbacks. Events include the tool name, start time, duration, and errors, but never tool arguments or results. Callback failures are ignored so telemetry cannot break tool execution.

const sumupAgentToolkit = new SumUpAgentToolkit({
  apiKey: process.env.SUMUP_API_KEY!,
  observability: {
    onToolEnd: ({ toolName, durationMs }) => {
      metrics.histogram("sumup.agent_tool.duration", durationMs, { toolName });
    },
    onToolError: ({ toolName, error }) => {
      logger.error({ toolName, error }, "SumUp agent tool failed");
    },
  },
});

LangChain

import { SumUpAgentToolkit } from "@sumup/agent-toolkit/langchain";
import { createAgent } from "langchain";

const sumupAgentToolkit = new SumUpAgentToolkit({
  apiKey: process.env.SUMUP_API_KEY!,
});

const agent = createAgent({
  model: "openai:gpt-4o",
  tools: sumupAgentToolkit.getTools(),
});

const response = await agent.invoke({
  messages: [
    {
      role: "user",
      content: "Tell me about my last 10 transactions please.",
    },
  ],
});

AI SDK

import { SumUpAgentToolkit } from "@sumup/agent-toolkit/ai";
import { generateText, stepCountIs } from "ai";

const sumupAgentToolkit = new SumUpAgentToolkit({
  apiKey: process.env.SUMUP_API_KEY!,
});

const response = await generateText({
  model: "openai/gpt-4o",
  tools: sumupAgentToolkit.getTools(),
  stopWhen: stepCountIs(5),
  prompt: "Tell me about my last 10 transactions please.",
});

For full example see AI SDK Example.

OpenAI Agents SDK

import { Agent, run } from "@openai/agents";
import { SumUpAgentToolkit } from "@sumup/agent-toolkit/openai";

const sumupAgentToolkit = new SumUpAgentToolkit({
  apiKey: process.env.SUMUP_API_KEY!,
});

const agent = new Agent({
  name: "Transactions reporter",
  instructions: "You are a helpful payments assistant.",
  tools: sumupAgentToolkit.getTools(),
});

const result = await run(
  agent,
  "Tell me about my last 10 transactions please.",
);

console.log(result.finalOutput);

For full example see OpenAI Example.