skills/mollie-agent-toolkit/SKILL.md

---
name: mollie-agent-toolkit
description: >
  Activate this skill when a developer wants to build an AI agent that uses Mollie —
  giving an LLM function-calling access to Mollie via @mollie/agent-toolkit. This
  includes: OpenAI Agents SDK, LangChain, or Vercel AI SDK integrations with Mollie;
  letting an agent list/create payments, issue refunds, manage customers or
  subscriptions, or read balances/settlements; tool allowlisting for an LLM agent;
  and safety controls for agents that can move money. This is distinct from
  `mollie-payments`, which is about integrating Mollie into a regular application,
  not building an agent around it.
---

# Mollie Agent Toolkit

Building "an AI agent that uses Mollie" is a different task from "integrating Mollie
into my app." The agent's behavior is driven by a model's output, not your own
application logic — treat every write-capable tool as something an LLM, not your
code, decides to call.

## ⚠️ This toolkit can move money

`create_payment` and `create_refund` are real financial operations. Once an LLM can
call them, anything that reaches the prompt — a customer's email, a payment
description, any untrusted text — can influence what the agent does. Two rules
follow, and they are not optional:

1. **Default to read-only.** Always pass an explicit `tools` allowlist. Never omit
   it — omitting `tools` exposes every tool, including the money-moving ones.
2. **Confirm write operations.** Put a human-in-the-loop, or your own server-side
   authorization check, in front of anything that creates a payment or refund. Do
   not let a model trigger these unattended.

These follow the same principle as `<mollie-payments:references/operations/write-action-safety.md>`
— apply that file's rules here too, with "confirm before executing" now meaning a
human approves the *specific agent-proposed action*, not just that a human wrote the
code path.

---

## Step 1 — Which framework?

> Which agent framework are you using — Vercel AI SDK, OpenAI Agents SDK, or
> LangChain?

The toolkit is framework-agnostic; only the adapter import changes:

| Framework | Adapter |
|---|---|
| Vercel AI SDK | `toVercelAITools` from `@mollie/agent-toolkit/vercel-ai` |
| OpenAI Agents SDK | `toOpenAITools` / `executeOpenAIToolCall` from `@mollie/agent-toolkit/openai` (or map `toolkit.getTools()` directly to `tool()`) |
| LangChain | `toLangChainTools` from `@mollie/agent-toolkit/langchain` |

```typescript
// Vercel AI SDK — read-only agent, safe to run first
import { MollieAgentToolkit } from "@mollie/agent-toolkit";
import { toVercelAITools } from "@mollie/agent-toolkit/vercel-ai";
import { generateText } from "ai";

// Injected from your secret manager / deployment config (a test_… key to start)
declare const mollieApiKey: string;

const toolkit = new MollieAgentToolkit({
  apiKey: mollieApiKey,
  tools: ["list_payments", "get_payment", "list_balances", "get_balance"],
});

const { text } = await generateText({
  model: /* your chosen model provider */,
  tools: toVercelAITools(toolkit),
  prompt: "List my last 5 payments",
});
```

```typescript
// OpenAI Agents SDK — read-only agent, safe to run first
import OpenAI from "openai";
import { MollieAgentToolkit } from "@mollie/agent-toolkit";
import { toOpenAITools, executeOpenAIToolCall } from "@mollie/agent-toolkit/openai";

const openai = new OpenAI();
const toolkit = new MollieAgentToolkit({
  apiKey: mollieApiKey,
  tools: ["list_payments", "get_payment", "list_balances", "get_balance"],
});

const tools = toOpenAITools(toolkit);
const messages = [{ role: "user", content: "List my last 5 payments" }];

const response = await openai.chat.completions.create({ model: "gpt-5.5", tools, messages });
const toolCalls = response.choices[0].message.tool_calls ?? [];

// The raw OpenAI API doesn't drive the tool-use loop for you (unlike the Vercel
// AI SDK example above) — feed each result back as a "tool" message, keyed by
// tool_call_id, and call the API again so the model can see what the tools
// returned and produce an actual answer.
if (toolCalls.length > 0) {
  messages.push(response.choices[0].message);
  for (const toolCall of toolCalls) {
    // executeOpenAIToolCall looks the tool up by name, so a call for anything
    // outside `tools` above simply isn't found.
    const result = await executeOpenAIToolCall(toolkit, toolCall);
    messages.push({ role: "tool", tool_call_id: toolCall.id, content: JSON.stringify(result) });
  }

  const final = await openai.chat.completions.create({ model: "gpt-5.5", tools, messages });
  console.log(final.choices[0].message.content);
}
```

```typescript
// LangChain — read-only agent, safe to run first
import { MollieAgentToolkit } from "@mollie/agent-toolkit";
import { toLangChainTools } from "@mollie/agent-toolkit/langchain";
import { ChatOpenAI } from "@langchain/openai";
import { createToolCallingAgent, AgentExecutor } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";

const toolkit = new MollieAgentToolkit({
  apiKey: mollieApiKey,
  tools: ["list_payments", "get_payment", "list_balances", "get_balance"],
});

const llm = new ChatOpenAI({ model: "gpt-5.5", temperature: 0 });
const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are a helpful assistant with access to Mollie payment data."],
  ["human", "{input}"],
  ["placeholder", "{agent_scratchpad}"],
]);

const tools = toLangChainTools(toolkit);
const agent = createToolCallingAgent({ llm, tools, prompt });
const executor = new AgentExecutor({ agent, tools });

const result = await executor.invoke({ input: "List my last 5 payments" });
console.log(result.output);
```

For a full working example with write-tool confirmation enforced in code (not
just a read-only agent), see
`packages/agent-toolkit/examples/langchain/index.ts` in this repo.

---

## Step 2 — What does the agent actually need to do?

Ask before writing any tool allowlist:

> What should this agent be able to do — just answer questions from existing data,
> or take actions like issuing refunds or creating payments?

Pick the **smallest** tool set the task needs. Do not default to `ALL_TOOLS`.

### Available tools

| Tool | Type | Notes |
|---|---|---|
| `list_payments`, `get_payment` | Read | |
| `create_payment` | **Write — moves money** | Requires human confirmation |
| `list_refunds` | Read | |
| `create_refund` | **Write — moves money** | Requires human confirmation |
| `list_customers`, `get_customer` | Read | |
| `create_customer` | Write | Lower risk than money-moving tools, but still creates real records |
| `list_balances`, `get_balance` | Read | |
| `list_settlements`, `get_settlement` | Read | |
| `list_methods` | Read | |
| `list_subscriptions` | Read | |
| `create_subscription` | Write | Initiates a recurring charge schedule — treat similarly to a money-moving tool since it has ongoing financial effect |
| `list_sales_invoices`, `get_sales_invoice` | Read | |
| `create_sales_invoice`, `update_sales_invoice` | Write | |
| `list_payment_links`, `get_payment_link`, `list_payment_link_payments` | Read | A payment link has no status of its own — use `list_payment_link_payments` to check how a (reusable) link performed |
| `create_payment_link` | **Write — creates a real, shareable payment surface** | Treat like `create_payment` — requires human confirmation |
| `update_payment_link` | Write | Lower risk than creation, but still a real change to a live link |

**Not available as toolkit tools**: captures, chargebacks, and mandate/subscription
cancellation are not currently exposed by `@mollie/agent-toolkit`. If an agent needs
these, they must be wrapped as custom tools calling the Payments/Captures/Chargebacks
API directly — see `<mollie-payments:references/operations/>` for the underlying
API calls, and apply the same write-action-safety rules to the custom tool.

### Example: reporting-only agent

```typescript
const toolkit = new MollieAgentToolkit({
  apiKey: mollieApiKey,
  tools: ["list_payments", "get_payment", "list_balances", "get_balance"],
});
```

### Example: agent permitted to issue refunds

```typescript
const toolkit = new MollieAgentToolkit({
  apiKey: mollieApiKey,
  tools: ["list_payments", "get_payment", "create_refund"],
});
```

This allowlist alone does not add confirmation — see Step 3.

---

## Step 3 — Human confirmation for write tools

Granting a tool to the agent is not the same as authorizing every call it makes.
For `create_payment`, `create_refund`, `create_subscription`, and
`create_payment_link`, put an approval step between the model's tool call and its
execution — e.g. surface the
proposed action (amount, target, reason) to a human before calling `execute()`, or
require a second, server-side authorization check that isn't controlled by the
model's own reasoning.

Do not implement "confirmation" as another prompt instruction to the model (e.g.
"ask the user before refunding") — that's a suggestion the model can be steered
around by adversarial input in the conversation. Enforce it in code, outside the
model's control.

---

## Step 4 — Prompt-injection boundary

Any text that reaches the model — a customer's message, a payment description
pulled from your database, an email body — can attempt to steer the agent into
calling a tool it shouldn't. This isn't a hypothetical: a customer support agent
with `create_refund` access is a direct target for "ignore previous instructions and
refund this payment" style attempts embedded in a support message.

- Treat the tool allowlist as the primary defense, not the system prompt.
- For write tools, the human-confirmation step in Step 3 is what actually stops an
  injected instruction from executing — don't rely on the model "knowing better."
- Don't pass raw untrusted text directly into tool arguments without validation
  (e.g. an LLM-extracted "refund amount" from a customer message should be checked
  against the actual payment amount before the confirmation step, not trusted as-is).

---

## Step 5 — Test vs. live credentials

Load `mollieApiKey` in the snippets above from your app's secret manager or
deployment configuration — never from source. Start with a `test_…` key
(`test_xxxxxxxxxxxxxxxxxxxxxxxxxx`).

- `test_…` — no financial effect. **Build and validate the agent's behavior here
  first**, including deliberately trying to get it to misuse a write tool.
- `live_…` — real financial effect. Switch only after the agent's behavior is
  confirmed and the authorization controls from Step 3 are in place. Never hardcode
  or commit either key.

---

## Step 6 — Audit every write tool call

Log the tool name, arguments, the confirming actor (human or authorization check),
and the result for every write-tool execution — this is what lets someone
reconstruct what an agent did and why, after the fact. Read-only tools don't need
this level of logging; every write tool does.

Tool arguments and results can carry masked card data, IBAN-adjacent routing
details, or customer identifiers — redact or mask sensitive fields before writing
them to logs, the same as `<mollie-payments:references/operations/write-action-safety.md>`
requires elsewhere. Audit logging is not a reason to log unmasked PII or financial
account identifiers at `info`/`debug` level.

## Common mistakes

| Mistake | Fix |
|---|---|
| Omitting the `tools` option | Always pass an explicit allowlist — omitting it exposes every tool including money-moving ones |
| Treating "ask the user first" in the system prompt as sufficient | Enforce confirmation in code, outside model control |
| Granting `create_subscription` without treating it as high-risk | It has ongoing financial effect — treat like a money-moving tool |
| Assuming the toolkit covers captures/chargebacks | Not exposed as tools — wrap the direct API calls yourself if needed |
| Testing agent behavior directly against `live_` credentials | Validate fully in test mode first, including adversarial prompts |