Agent Toolkit

The SumUp Agent Toolkit(Opens in a new tab) adds SumUp API tools to agentic applications built with LangChain, AI SDK, the OpenAI Agents SDK, or the Model Context Protocol (MCP).

Prerequisites

The Agent Toolkit requires Node.js 22 or later and a SumUp API key.

Installation

npm install @sumup/agent-toolkit

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.",
    },
  ],
});

console.log(response);

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.",
});

console.log(response.text);

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.");

console.log(result.finalOutput);

Tool approvals

The AI SDK and OpenAI Agents SDK adapters require approval before running tools that can modify data. Read-only tools run without approval. You can override the default with an approvalPolicy callback that is evaluated for each tool call.

const sumupAgentToolkit = new SumUpAgentToolkit({
  apiKey: process.env.SUMUP_API_KEY!,
  approvalPolicy: (tool) => !tool.annotations?.readOnly,
});

Your application is responsible for presenting and resolving approval requests using the framework’s approval flow.

Observability

Every adapter accepts optional lifecycle callbacks for recording tool execution rate, errors, and duration. Events include the tool name and timing information, but never tool arguments or results. Callback failures do not interrupt tool execution.

const sumupAgentToolkit = new SumUpAgentToolkit({
  apiKey: process.env.SUMUP_API_KEY!,
  observability: {
    onToolEnd: ({ toolName, durationMs }) => {
      console.info("SumUp tool completed", { toolName, durationMs });
    },
    onToolError: ({ toolName, durationMs, error }) => {
      console.error("SumUp tool failed", {
        toolName,
        durationMs,
        errorType: error instanceof Error ? error.name : "unknown",
      });
    },
  },
});

MCP adapter

Use the MCP adapter when embedding SumUp tools in your own MCP server.

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

const server = new SumUpAgentToolkit({
  apiKey: process.env.SUMUP_API_KEY!,
  readOnly: true,
  configuration: {},
});

The MCP adapter supports the following catalog controls:

• includeTools: expose only the named tools.
• excludeTools: omit the named tools.
• readOnly: expose only tools that do not modify data.
• includeOutputSchemas: advertise output schemas to MCP clients. This is disabled by default to reduce the context used by tools/list; tool results are still validated at runtime.

To connect an MCP client to SumUp without hosting your own server, use the managed SumUp MCP server.