Use @codespar/camel to give CAMEL-AI role-playing agents commerce capabilities in Latin America.

CAMEL-AI Adapter

The @codespar/camel adapter converts CodeSpar session tools into CAMEL-AI's OpenAI-compatible function format with a callable for execution. Each tool routes through the CodeSpar session for billing and audit. Use it to give your CAMEL role-playing agent conversations access to commerce operations in Latin America.

Installation

npm install @codespar/sdk @codespar/camel

pnpm add @codespar/sdk @codespar/camel

yarn add @codespar/sdk @codespar/camel

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

API Reference

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

Fetches all tools and converts them to CAMEL's function format. Each tool has type: "function", a function object with name, description, and parameters, plus a callable for execution.

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

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(JSON.stringify(tools[0], null, 2));

Output: CamelFunction

{
  "type": "function",
  "function": {
    "name": "codespar_checkout",
    "description": "Create a checkout session for a product or service",
    "parameters": {
      "type": "object",
      "properties": {
        "provider": { "type": "string" },
        "amount": { "type": "number" },
        "currency": { "type": "string" }
      },
      "required": ["provider", "amount", "currency"]
    }
  }
}

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

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

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

  // 3. Create a tool registry
  const toolRegistry = new Map(
    tools.map((t) => [t.function.name, t])
  );

  // 4. Define role-playing agents
  const assistantRole = {
    name: "Commerce Expert",
    description:
      "Expert in Brazilian e-commerce operations including payments, " +
      "invoicing, and shipping via Pix, boleto, and credit cards.",
  };

  const userRole = {
    name: "Store Owner",
    description: "Owner of a Brazilian online store who needs help with operations.",
  };

  // 5. Execute tool calls from the conversation
  const toolName = "codespar_checkout";
  const tool = toolRegistry.get(toolName);

  if (tool) {
    const result = await tool.callable({
      provider: "stripe",
      amount: 25000,
      currency: "BRL",
      description: "Order #1234",
    });
    console.log("Tool result:", result);
  }

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

await run("I need to process a payment of R$250 via Pix for order #1234");

Handling parallel tool calls

Execute multiple tool callables in parallel:

const toolCalls = [
  { name: "codespar_checkout", args: { provider: "stripe", amount: 4990, currency: "BRL" } },
  { name: "codespar_notify", args: { channel: "email", to: "customer@example.com" } },
];

const results = await Promise.all(
  toolCalls.map(async (tc) => {
    const tool = toolRegistry.get(tc.name);
    if (!tool) throw new Error(`Unknown tool: ${tc.name}`);
    return { name: tc.name, result: await tool.callable(tc.args) };
  })
);

Streaming

Use CAMEL's conversation streaming with the callable for tool execution:

camel-streaming.ts

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

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 tool executor in your CAMEL setup
async function executeToolCall(name: string, args: Record<string, unknown>) {
  const tool = tools.find((t) => t.function.name === name);
  if (!tool) return JSON.stringify({ error: `Unknown tool: ${name}` });
  return tool.callable(args);
}

Error handling

Wrap callable invocations in try-catch:

async function safeExecute(tool: CamelFunction, args: Record<string, unknown>) {
  try {
    return await tool.callable(args);
  } catch (error) {
    return JSON.stringify({
      error: error instanceof Error ? error.message : "Tool call failed",
      tool_name: tool.function.name,
    });
  }
}

Returning errors as JSON strings lets the CAMEL agents reason about failures within the role-playing conversation.

Best practices

Always close sessions. Use try/finally to ensure session.close() runs.
Scope servers narrowly. Only connect the MCP servers your agents need.
Use a tool registry. Create a Map for O(1) tool lookups by name.
Define clear roles. CAMEL agents work best with specific role descriptions that explain their expertise.
Return errors as strings. Let agents reason about failures within the conversation.
Share the same session. Both agents in a role-playing pair should use the same CodeSpar session for consistent state.

Next steps

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

CAMEL-AI

CAMEL-AI Adapter

Installation

API Reference

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

`toCamelTool(tool, session): CamelFunction`

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

Full agent loop

Handling parallel tool calls

Streaming

Error handling

Best practices

Next steps

On this page