> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AutoGen integration guide - agents and task automation

AutoGen is an open-source framework for building collaborative multi-agent workflows. This article shows you how to use it with SambaNova models to automate complex, multi-step tasks.

## Prerequisites

Before you begin, ensure you have:

* A [SambaCloud](https://cloud.sambanova.ai?utm_source=autogen\&utm_medium=external\&utm_campaign=cloud_signup) account with an active API key.
* Python 3.10 or later. Run `python --version` to confirm. AutoGen 0.4 and later requires Python 3.10, and on Python 3.9 `pip` installs the incompatible 0.2 release instead.

## Installation

This guide uses the AutoGen 0.4 and later packages: `autogen-agentchat` for agents and teams, and the model clients in `autogen-ext`.

<Warning>
  Several PyPI packages share the AutoGen name and their APIs are not interchangeable. Install `autogen-agentchat`. The `autogen` and `ag2` packages belong to a separately maintained fork that uses different imports, and code written for one does not run on the other.
</Warning>

1. Create and activate a virtual environment.

   ```bash theme={}
   python -m venv .venv
   source .venv/bin/activate
   ```

2. Install AutoGen with the OpenAI-compatible model client.

   ```bash theme={}
   pip install "autogen-agentchat>=0.7,<0.8" "autogen-ext[openai]>=0.7,<0.8"
   ```

   The upper bound keeps you on the 0.7 API. AutoGen has reorganized its packages across releases, so pin the minor version and test before you upgrade.

3. Set your API key as an environment variable.

   ```bash theme={}
   export SAMBANOVA_API_KEY="your-api-key"
   ```

## Connect AutoGen to SambaCloud

SambaCloud exposes an OpenAI-compatible endpoint, so you connect through `OpenAIChatCompletionClient` with `base_url` set to `https://api.sambanova.ai/v1`.

Because SambaNova model names are not OpenAI model names, you must also pass a `model_info` dictionary describing the model's capabilities. Without it, the client raises `ValueError: model_info is required when model name is not a valid OpenAI model`.

The following example builds a two-agent team. A writer drafts an explanation and a reviewer either approves it or asks for fixes, and the two take turns until the reviewer replies `APPROVED`.

```python theme={}
import asyncio
import os

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.conditions import TextMentionTermination
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient


async def main() -> None:
    model_client = OpenAIChatCompletionClient(
        model="Meta-Llama-3.3-70B-Instruct",
        base_url="https://api.sambanova.ai/v1",
        api_key=os.environ["SAMBANOVA_API_KEY"],
        model_info={
            "vision": False,
            "function_calling": True,
            "json_output": False,
            "structured_output": False,
            "family": "unknown",
        },
    )

    writer = AssistantAgent(
        "writer",
        model_client=model_client,
        description="Drafts short technical explanations.",
        system_message="You draft short technical explanations. Keep them under 120 words.",
    )

    reviewer = AssistantAgent(
        "reviewer",
        model_client=model_client,
        description="Reviews drafts for accuracy and clarity.",
        system_message=(
            "You review the draft for accuracy and clarity. "
            "If it is correct and clear, reply with APPROVED. "
            "Otherwise, list the specific fixes needed."
        ),
    )

    team = RoundRobinGroupChat(
        [writer, reviewer],
        termination_condition=TextMentionTermination("APPROVED"),
        max_turns=4,
    )

    await Console(team.run_stream(task="Explain what a mixture-of-experts model is."))
    await model_client.close()


asyncio.run(main())
```

You should see an output similar to the one below.

```text theme={}
# Expected output
---------- TextMessage (user) ----------
Explain what a mixture-of-experts model is.
---------- TextMessage (writer) ----------
A mixture-of-experts model routes each token to a small subset of specialist
subnetworks, so only a fraction of parameters activate per token. That keeps
compute per token low while total capacity stays high.
---------- TextMessage (reviewer) ----------
APPROVED
```

`Console` prints each turn as it arrives, with the agent name in the header, so the `writer` and `reviewer` labels are how you confirm both agents ran rather than one answering twice. The run stops as soon as a message contains `APPROVED`, which is two model calls here, or after four turns if the reviewer never approves. If you only ever see `writer` turns, the termination string never matched and `max_turns` ended the run.

<Note>
  AutoGen 0.4 and later is async-first. Agent and team methods must be awaited, which is why the example wraps them in `asyncio.run()`. In a Jupyter notebook, drop the `asyncio.run(main())` line and `await` the calls directly in a cell.
</Note>

### Choose a model

Pass any [SambaCloud model](/docs/en/models/sambacloud-models) as `model`. Multi-agent workflows that give agents tools also need a model that supports function calling. Check the [supported models](/docs/en/features/function-calling) before you set `"function_calling": True`, because the client raises `ValueError: Model does not support function calling` only after you attach a tool.

## Example notebooks

Try out some examples with the following notebooks:

* [Travel planning notebook](https://github.com/sambanova/integrations/blob/main/autogen/travel-planning.ipynb): Build a comprehensive travel itinerary with a team of agents. This notebook needs only your SambaNova API key, so start here.
* [Company research notebook](https://github.com/sambanova/integrations/blob/main/autogen/company-research.ipynb): Use a team of agents to search the web, find stock information, and generate a report. This one also needs a Google Custom Search API key and search engine ID, and it installs `yfinance` and `matplotlib`.

Both notebooks read `SAMBANOVA_API_KEY` and `SAMBANOVA_URL` from a `.env` file, and prompt you for any value they cannot find. Set `SAMBANOVA_URL` to `https://api.sambanova.ai/v1`.

## Troubleshooting

<AccordionGroup>
  <Accordion title="ModuleNotFoundError: No module named 'autogen_agentchat'">
    You installed the 0.2 release, which ships an `autogen` module instead. On Python 3.9, `pip` selects it silently because 0.4 and later require Python 3.10.

    Confirm `python --version` is 3.10 or later, then reinstall with the bounded command in [Installation](#installation).
  </Accordion>

  <Accordion title="ValueError: model_info is required when model name is not a valid OpenAI model">
    `OpenAIChatCompletionClient` looks up capabilities by model name and does not recognize SambaNova model names.

    Pass the `model_info` dictionary shown in [Connect AutoGen to SambaCloud](#connect-autogen-to-sambacloud).
  </Accordion>

  <Accordion title="ValueError: Missing required field in ModelInfo">
    `vision`, `function_calling`, `json_output`, and `family` are each mandatory in `model_info`.

    Add the missing key. Omitting `structured_output` instead prints `UserWarning: Missing required field 'structured_output' in ModelInfo` and still constructs, but it becomes mandatory in a later release, so set all five as shown above.
  </Accordion>

  <Accordion title="ValueError: Model does not support function calling">
    You attached tools to an agent whose `model_info` sets `"function_calling": False`.

    Choose a model from the [function calling supported models](/docs/en/features/function-calling) and set `"function_calling": True`.
  </Accordion>

  <Accordion title="401 or 403 from the endpoint">
    `SAMBANOVA_API_KEY` is unset, expired, or the shell that runs your script never received the export.

    Re-export the key, then confirm it works with:

    ```bash theme={}
    curl -H "Authorization: Bearer $SAMBANOVA_API_KEY" https://api.sambanova.ai/v1/models
    ```
  </Accordion>
</AccordionGroup>

## Additional resources

* [AutoGen documentation](https://microsoft.github.io/autogen/stable/)
* [Function calling](/docs/en/features/function-calling)
* [SambaCloud models](/docs/en/models/sambacloud-models)