CrewAI Integration with The Grid | Agent LLM Setup

Connect CrewAI to The Grid with the LLM class. Use the OpenAI-compatible endpoint, assign Grid models to agents, and tier by role.

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.

• 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:

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:

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.

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.

3. Pass the LLM to your agents

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:

@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:

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

crewai run

Verification

Drop this into a file and run it:

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

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.

402 Payment Required. Your credits are at zero. Top up at app.thegrid.ai. Auto Top Up keeps long crews from stalling.

404 / "model not available". The model string must be openai/<instrument>, with a valid instrument ID. See the current instruments list. Vendor names like openai/gpt-4o are rejected.

Error asking for crewai[litellm]. Reinstall with the extra: uv add "crewai[litellm]".

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.