---
title: AutoGen
description: Use @codespar/autogen to give Microsoft AutoGen agents commerce capabilities in Latin America.
---

import { Callout } from "fumadocs-ui/components/callout";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";

# AutoGen Adapter

<VersionBadge pkg="@codespar/autogen" />

The `@codespar/autogen` adapter converts CodeSpar session tools into Microsoft AutoGen's function tool format. Each tool includes a `callable` that routes execution through the CodeSpar session for billing and audit. Use it to give your AutoGen multi-agent conversations access to payments, invoicing, and shipping in Latin America.

<Callout type="info">
**Pick this adapter when** you need group-chat style multi-agent conversations (proposer + critic + executor patterns), Python-first workflows, or integration with Microsoft's Azure OpenAI ecosystem.
</Callout>

## Framework-specific notes

- **Functions register per agent** — each `ConversableAgent` can have its own subset of CodeSpar tools. Good fit for the group-chat pattern where a "proposer" agent does `codespar_discover` and an "executor" only gets `codespar_charge` / `codespar_pay`.
- **Human-in-the-loop is first-class** — AutoGen's `UserProxyAgent` can approve each tool call before it runs, perfect for high-risk commerce actions (payouts, bulk refunds) that need human sign-off.
- **Group chat for escalation** — three-agent patterns (customer service + fraud-check + finance-ops) resolve complex refund decisions more reliably than single-agent loops.
- **Azure OpenAI compatible** — the adapter does not care which OpenAI-compatible endpoint you use. Point AutoGen at Azure OpenAI deployments if your compliance requires keeping inference in your cloud.
- **Python** — the full `codespar` Python package (sync + async) works from AutoGen directly; see [Quickstart (Python)](/docs/quickstart-python).

## Installation

<Tabs items={["npm", "pnpm", "yarn"]}>
<Tab value="npm">
```bash
npm install @codespar/sdk @codespar/autogen
```
</Tab>
<Tab value="pnpm">
```bash
pnpm add @codespar/sdk @codespar/autogen
```
</Tab>
<Tab value="yarn">
```bash
yarn add @codespar/sdk @codespar/autogen
```
</Tab>
</Tabs>

<Callout type="info">
`@codespar/autogen` has a peer dependency on `@codespar/sdk@^0.10.0`. Make sure it is installed.
</Callout>
## API Reference

### `getTools(session): Promise<AutoGenFunctionTool[]>`

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

```typescript
import { CodeSpar } from "@codespar/sdk";
import { getTools } from "@codespar/autogen";

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

const tools = await getTools(session);
console.log(JSON.stringify(tools[0], null, 2));
```

```json title="Output: AutoGenFunctionTool"
{
  "type": "function",
  "function": {
    "name": "codespar_charge",
    "description": "Create an inbound charge (buyer pays merchant) — Pix / boleto / card",
    "parameters": {
      "type": "object",
      "properties": {
        "provider": { "type": "string" },
        "amount": { "type": "number" },
        "currency": { "type": "string" }
      },
      "required": ["provider", "amount", "currency"]
    }
  }
}
```

### `toAutoGenTool(tool, session): AutoGenFunctionTool`

Converts a single CodeSpar tool to AutoGen format with a bound `callable`.

```typescript
import { toAutoGenTool } from "@codespar/autogen";

const allTools = await session.tools();
const paymentTools = allTools
  .filter((t) => t.name.includes("pay"))
  .map((t) => toAutoGenTool(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 an AutoGen multi-agent conversation with CodeSpar tools:

```typescript title="autogen-agent.ts"
import { CodeSpar } from "@codespar/sdk";
import { getTools } from "@codespar/autogen";

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

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

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

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

  // 4. Simulate an agent loop (adapt to your AutoGen setup)
  const toolName = "codespar_charge";
  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);
  }

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

await run("Process payment of R$250 via Pix");
```

## Handling parallel tool calls

Execute multiple tool callables in parallel when the agent requests them:

```typescript
const toolCalls = [
  { name: "codespar_charge", 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

AutoGen supports streaming conversations. Use the `callable` in your tool execution handler:

```typescript title="autogen-streaming.ts"
import { CodeSpar } from "@codespar/sdk";
import { getTools } from "@codespar/autogen";

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

// Register tools with your AutoGen agent's tool executor
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:

```typescript
async function safeExecute(tool: AutoGenFunctionTool, 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,
    });
  }
}
```

<Callout type="info">
Returning errors as JSON strings lets the AutoGen agent reason about failures and decide whether to retry or try a different approach.
</Callout>
## Best practices

1. **Always close sessions.** Use `try/finally` to ensure `session.close()` runs.

2. **Scope servers narrowly.** Only connect the MCP servers your agents need.

3. **Build a tool registry.** Use a `Map` keyed by tool name for O(1) lookups in the tool execution handler.

4. **Set conversation limits.** Configure `max_consecutive_auto_reply` to prevent infinite agent loops.

5. **Return errors as strings.** Let agents reason about failures instead of crashing the conversation.

6. **Use typed tool calls.** The `AutoGenFunctionTool` interface ensures type safety in your tool execution handler.

## Newer SDK wrappers

`getTools(session)` is the agent-facing path. From any handler or callback you can also call typed wrappers on the session — same routing, no LLM hop:

- `session.discover(query)` / `session.charge(args)` / `session.pay(args)` / `session.ship(args)` — typed shortcuts for the meta-tools.
- `session.connectionWizard(serverId)` — open a hosted auth flow for a missing connection.
- `session.paymentStatus(toolCallId)` and `session.paymentStatusStream(toolCallId)` — async settlement correlation (poll or SSE).
- `session.verificationStatus(toolCallId)` and `session.verificationStatusStream(toolCallId)` — KYC outcome polling / SSE.

Full reference at [/docs/api/sdk](/docs/api/sdk).

## Next steps

<NextStepsGrid items={[
  { label: "CONCEPT", title: "Sessions", description: "Session lifecycle and configuration.", href: "/docs/concepts/sessions" },
  { label: "CONCEPT", title: "Tools & Meta-Tools", description: "Meta-tools and how routing works.", href: "/docs/concepts/tools" },
  { label: "PROVIDER", title: "CrewAI Adapter", description: "Alternative role-based multi-agent pattern.", href: "/docs/providers/crewai" },
  { label: "QUICKSTART", title: "Quickstart (Python)", description: "Sync and async flavours for FastAPI / Jupyter.", href: "/docs/quickstart-python" },
  { label: "QUICKSTART", title: "Quickstart", description: "End-to-end setup in under 5 minutes.", href: "/docs/quickstart" },
]} />