Use @codespar/crewai to give CrewAI agent crews commerce capabilities in Latin America.

CrewAI Adapter

The @codespar/crewai adapter converts CodeSpar session tools into CrewAI's tool format. Each tool has a run method that routes execution through the CodeSpar session for billing and audit. Use it to give your CrewAI crews access to payments, invoicing, shipping, and other commerce operations in Latin America.

Installation

npm install @codespar/sdk @codespar/crewai

pnpm add @codespar/sdk @codespar/crewai

yarn add @codespar/sdk @codespar/crewai

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

API Reference

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

Fetches all tools from the session and converts them to CrewAI tool format. Each tool has name, description, schema (JSON Schema), and a run method.

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

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].schema); // { type: "object", properties: { ... } }

`toCrewAITool(tool, session): CrewAITool`

Converts a single CodeSpar tool to CrewAI format. The run method is bound to the session for execution.

import { toCrewAITool } from "@codespar/crewai";

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

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

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

import { handleToolCall } from "@codespar/crewai";

const result = await handleToolCall(session, "codespar_checkout", {
  provider: "stripe",
  amount: 4990,
  currency: "BRL",
});

Full agent loop

This is a complete example of a CrewAI crew using CodeSpar tools for commerce operations:

crewai-agent.ts

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

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

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

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

  // 3. Define your agents
  const paymentAgent = {
    role: "Payment Specialist",
    goal: "Handle all payment operations for Brazilian e-commerce",
    backstory: "Expert in Brazilian payment methods including Pix, boleto, and credit cards.",
    tools,
  };

  const shippingAgent = {
    role: "Shipping Coordinator",
    goal: "Manage shipping and logistics across Brazil",
    backstory: "Expert in Brazilian shipping via Correios and private carriers.",
    tools,
  };

  // 4. Define tasks and create crew
  const task = {
    description: userMessage,
    agent: paymentAgent,
    expectedOutput: "A confirmation of the completed operation with details.",
  };

  // 5. Execute (using your CrewAI runtime)
  // const crew = new Crew({ agents: [paymentAgent, shippingAgent], tasks: [task] });
  // const result = await crew.kickoff();

  // For manual execution:
  for (const tool of tools) {
    if (tool.name === "codespar_checkout") {
      const result = await tool.run({
        provider: "stripe",
        amount: 25000,
        currency: "BRL",
        description: "Order #1234",
      });
      console.log("Checkout result:", result);
    }
  }

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

await run("Process payment of R$250 via Pix for order #1234");

Handling parallel tool calls

When multiple tools need to run concurrently, use Promise.all with the run method:

const results = await Promise.all([
  tools.find((t) => t.name === "codespar_checkout")!.run({
    provider: "stripe",
    amount: 4990,
    currency: "BRL",
  }),
  tools.find((t) => t.name === "codespar_notify")!.run({
    channel: "email",
    to: "customer@example.com",
    subject: "Payment received",
  }),
]);

Streaming

CrewAI supports step-by-step callbacks. Use handleToolCall in your callbacks to stream tool results:

crewai-callbacks.ts

import { CodeSpar } from "@codespar/sdk";
import { handleToolCall } from "@codespar/crewai";

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

// In your crew step callback:
async function onToolCall(toolName: string, args: Record<string, unknown>) {
  console.log(`Executing: ${toolName}`);
  const result = await handleToolCall(session, toolName, args);
  console.log(`Result:`, result.data);
  return result;
}

Error handling

Wrap tool.run() calls in try-catch and return errors as structured data:

for (const tool of tools) {
  try {
    const result = await tool.run(input);
    console.log("Success:", result);
  } catch (error) {
    console.error(`Tool ${tool.name} failed:`, error instanceof Error ? error.message : error);
    // Return error to the agent for reasoning
  }
}

Returning errors as tool results (instead of throwing) lets the agent reason about the failure and decide whether to retry with different parameters.

Best practices

Always close sessions. Use try/finally to ensure session.close() runs even if the crew throws.
Scope servers narrowly. Only connect the MCP servers your crew needs. Fewer tools improves agent accuracy.
Assign tools per agent. Give each agent only the tools relevant to its role instead of sharing all tools across agents.
Set clear goals. CrewAI agents work best with specific, measurable goals and clear backstories.
Return errors as results. Let agents reason about failures instead of crashing the crew.
Limit task delegation. Use allow_delegation: false for simple tasks to prevent unnecessary back-and-forth between agents.

Next steps

Sessions -- Session lifecycle and configuration
Tools and Meta-Tools -- Understand the 6 meta-tools and routing
OpenAI Adapter -- Direct OpenAI SDK integration
LangChain Adapter -- Use with LangChain.js agents
Quickstart -- End-to-end setup in under 5 minutes

CrewAI

On this page