# CrewAI

CrewAI is a Python framework for orchestrating multi-agent systems. The Grid plugs in through CrewAI's `LLM` class as a standard OpenAI-compatible provider. No custom provider code: build an `LLM` pointed at The Grid, pass it to each `Agent`, and every step, tool call, and delegation runs on market-priced inference.

## Prerequisites

* CrewAI installed with the LiteLLM extra: `uv add "crewai[litellm]"` (or `pip install "crewai[litellm]"`). The `[litellm]` extra is required; plain `crewai` fails to initialize `model="openai/<instrument>"`.
* A Grid account at [app.thegrid.ai](https://app.thegrid.ai).
* Credits in your account. The Grid is prepaid.
* A Grid consumption API key from **Settings → API Keys → Create Consumption Key**.

## Setup

### 1. Add the key to your environment

Put it in a `.env` at your project root:

```bash
THEGRID_API_KEY=your-consumption-key-here
```

A `@CrewBase`-decorated project auto-loads `.env` via `python-dotenv`. For plain scripts, add `from dotenv import load_dotenv; load_dotenv()` at the top.

### 2. Build an `LLM` instance pointed at The Grid

In your crew module:

```python
import os
from crewai import LLM

grid_llm = LLM(
    model="openai/agent-prime",
    base_url="https://api.thegrid.ai/v1",
    api_key=os.getenv("THEGRID_API_KEY"),
)
```

The `openai/` prefix tells CrewAI to use the OpenAI-compatible transport. The model name after the slash is a Grid instrument from the [current instruments list](/docs/instrument-specifications/current-instruments.md).

{% hint style="warning" %}
The `openai/` prefix is required. Without it, CrewAI tries to resolve the bare instrument name against its native OpenAI model list and fails. Always write `openai/agent-prime`, not `agent-prime`.
{% endhint %}

### 3. Pass the LLM to your agents

```python
from crewai import Agent

researcher = Agent(
    role="Senior Researcher",
    goal="Find up-to-date information on {topic}",
    backstory="Experienced analyst who produces clean, sourced briefs.",
    llm=grid_llm,
)
```

For YAML-driven crews, keep `config/agents.yaml` exactly as the CrewAI CLI generates it. Inject the LLM from Python in `crew.py`:

```python
@CrewBase
class MyCrew:
    @agent
    def researcher(self) -> Agent:
        return Agent(config=self.agents_config["researcher"], llm=grid_llm)
```

### 4. (Optional) Tier instruments by agent role

Build one `LLM` instance per tier and route by cognitive load. Put the manager on Agent Max, daily workers on Agent Prime, prose synthesis on Text Prime, classification and extraction on Text Standard:

```python
common = dict(base_url="https://api.thegrid.ai/v1", api_key=os.getenv("THEGRID_API_KEY"))

grid_planner = LLM(model="openai/agent-max",     **common)
grid_worker  = LLM(model="openai/agent-prime",   **common)
grid_writer  = LLM(model="openai/text-prime",    **common)
grid_utility = LLM(model="openai/text-standard", **common)

Crew(
    agents=[...],
    tasks=[...],
    process=Process.hierarchical,
    manager_llm=grid_planner,
)
```

You can also split function-calling: `Agent(llm=grid_writer, function_calling_llm=grid_utility)` keeps reasoning expensive and tool-argument shaping cheap.

### 5. Run the crew

```bash
crewai run
```

## Verification

Drop this into a file and run it:

```python
import os
from crewai import LLM

llm = LLM(
    model="openai/agent-prime",
    base_url="https://api.thegrid.ai/v1",
    api_key=os.getenv("THEGRID_API_KEY"),
)
print(llm.call("Reply with OK only."))
```

If you see `OK`, auth and routing are good.

## Troubleshooting

{% hint style="warning" %}
**401 Unauthorized.** Confirm `THEGRID_API_KEY` is set, loaded by your script, and is a consumption key (not a trading key). Trading keys do not authorize inference.
{% endhint %}

{% hint style="warning" %}
**402 Payment Required.** Your credits are at zero. Top up at [app.thegrid.ai](https://app.thegrid.ai). Auto Top Up keeps long crews from stalling.
{% endhint %}

{% hint style="warning" %}
**404 / "model not available".** The model string must be `openai/<instrument>`, with a valid instrument ID. See the [current instruments list](/docs/instrument-specifications/current-instruments.md). Vendor names like `openai/gpt-4o` are rejected.
{% endhint %}

{% hint style="info" %}
**Error asking for `crewai[litellm]`.** Reinstall with the extra: `uv add "crewai[litellm]"`.
{% endhint %}

{% hint style="info" %}
**Mixing The Grid with other providers in one run.** Build separate `LLM` instances per provider in Python and inject them per agent. The bare-string YAML pattern (`llm: openai/agent-prime`) reads `OPENAI_API_KEY` and `OPENAI_BASE_URL` globally, which forces every `openai/*` model in the process to route to The Grid.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://thegrid.ai/docs/integrations-and-best-practices/integrations/crewai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.