Use @codespar/letta to give Letta (MemGPT) agents commerce capabilities in Latin America.

Letta Adapter

The @codespar/letta adapter converts CodeSpar session tools into Letta's (formerly MemGPT) tool format. Each tool includes a callable that routes execution through the CodeSpar session for billing and audit. Use it to give your Letta agents with persistent memory access to commerce operations in Latin America.

Installation

npm install @codespar/sdk @codespar/letta

pnpm add @codespar/sdk @codespar/letta

yarn add @codespar/sdk @codespar/letta

@codespar/letta has a peer dependency on @codespar/sdk@^0.2.0. Make sure it is installed.

API Reference

`getTools(session): Promise<LettaTool[]>`

Fetches all tools from the session and converts them to Letta tool format. Each tool has name, description, parameters (JSON Schema), and a callable.

import { CodeSpar } from "@codespar/sdk";
import { getTools } from "@codespar/letta";

const codespar = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });
const session = await codespar.sessions.create({
  servers: ["stripe", "mercadopago"],
});

const tools = await getTools(session);
console.log(tools[0].name);       // "codespar_checkout"
console.log(tools[0].parameters); // { type: "object", properties: { ... } }

`toLettaTool(tool, session): LettaTool`

Converts a single CodeSpar tool to Letta format with a bound callable.

import { toLettaTool } from "@codespar/letta";

const allTools = await session.tools();
const paymentTools = allTools
  .filter((t) => t.name.includes("pay"))
  .map((t) => toLettaTool(t, session));

`handleToolCall(session, toolName, args): Promise<ToolResult>`

Convenience executor that routes a tool call through the CodeSpar session.

Full agent loop

This is a complete example of a Letta agent with persistent memory using CodeSpar tools:

letta-agent.ts

import { CodeSpar } from "@codespar/sdk";
import { getTools } from "@codespar/letta";

const codespar = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });

async function run(userMessage: string) {
  // 1. Create a session
  const session = await codespar.sessions.create({
    servers: ["stripe", "asaas"],
  });

  // 2. Get tools in Letta format
  const tools = await getTools(session);

  // 3. Register tools with your Letta agent
  // const agent = await client.createAgent({
  //   name: "commerce-agent",
  //   tools: tools.map((t) => ({
  //     name: t.name,
  //     description: t.description,
  //     parameters: t.parameters,
  //   })),
  // });

  // 4. Execute tools manually
  const checkoutTool = tools.find((t) => t.name === "codespar_checkout");
  if (checkoutTool) {
    const result = await checkoutTool.callable({
      provider: "stripe",
      amount: 25000,
      currency: "BRL",
    });
    console.log("Result:", result);
  }

  // 5. Clean up
  await session.close();
}

await run("Process a Pix payment for R$250");

Handling parallel tool calls

Execute multiple tool callables in parallel:

const results = await Promise.all(
  tools
    .filter((t) => ["codespar_checkout", "codespar_notify"].includes(t.name))
    .map((t) => t.callable({ amount: 5000, currency: "BRL" }))
);

Streaming

Letta agents support streaming responses. Use the callable in your tool execution handler for real-time results:

letta-streaming.ts

import { CodeSpar } from "@codespar/sdk";
import { getTools } from "@codespar/letta";

const codespar = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });
const session = await codespar.sessions.create({ servers: ["stripe"] });
const tools = await getTools(session);

// Register as Letta tool executor
async function executeToolCall(name: string, args: Record<string, unknown>) {
  const tool = tools.find((t) => t.name === name);
  if (!tool) return JSON.stringify({ error: `Unknown tool: ${name}` });
  return tool.callable(args);
}

Error handling

Wrap callable invocations in try-catch:

for (const tool of tools) {
  try {
    const result = await tool.callable(args);
    console.log(`${tool.name}:`, result);
  } catch (error) {
    console.error(`${tool.name} failed:`, error instanceof Error ? error.message : error);
  }
}

Letta agents have persistent memory. When a tool call fails, the agent remembers the failure context and can adapt its approach in future interactions.

Best practices

Always close sessions. Use try/finally to ensure session.close() runs.
Scope servers narrowly. Only connect the MCP servers your agent needs.
Leverage persistent memory. Letta agents remember past interactions — tool results become part of the agent's memory.
Use descriptive tool names. Letta's memory system benefits from clear, descriptive tool names for recall.
Return errors as strings. Let the agent reason about failures and store the context in memory.
Filter tools per task. Use session.findTools() to load only relevant tools for each agent instance.

Next steps

Sessions -- Session lifecycle and configuration
Tools and Meta-Tools -- Understand the 6 meta-tools and routing
OpenAI Adapter -- Letta uses OpenAI-compatible formats
AutoGen Adapter -- Similar callable pattern
Quickstart -- End-to-end setup in under 5 minutes

Letta

On this page