Skip to content

Add a tool

You will add a refund tool to the order agent. It changes the world, so it says so and reports what each refund did. You need this for any tool that writes to a payment provider, a database or another system.

A tool that changes the world declares effect: { kind: "write" }. A tool without it counts as read-only, so it is safe to run again after a crash. The businessKey names the real operation, such as refund:42, so a retry is recognised as the same refund. This tool refunds an order and reports the outcome:

refund-tool.ts
/** Builds the `refund_create` tool over your payment provider. */
export function refundTool(issueRefund: IssueRefund) {
return defineTool({
name: "refund_create",
description: "Refund an order in full.",
inputSchema: z.object({ order: z.number().int().positive() }),
effect: { kind: "write", businessKey: ({ order }) => `refund:${order}` },
async execute({ order }) {
const reply = await issueRefund(order);
return { content: [], outcome: outcomeOf(order, reply) };
},
});
}

An outcome says which of five things happened: applied, not_applied, compensated, partial or unknown. It also says what the model should do next and whether a retry is safe. The model reads the outcome first, then your content.

Every kind except applied marks the result as an error, so the model treats a declined refund as a failure it can explain to the customer.

Next, stop the agent before it runs a write.

These docs are licensedCC BY 4.0. Thelicence text is in the repository.