Connect CrewAI to Blocks

Follow this guide to expose a CrewAI crew as a callable agent on Blocks Network without flattening your multi-agent design.

Your crew keeps running in your Python process. The handler process connects to Blocks Network, receives a task, calls crew.kickoff(...), and returns an artifact. Blocks does not host, run, or take custody of the crew.

What you need

• A Blocks account. Sign up or log in.
• The Blocks CLI installed.
• Python 3.12 or higher. The Blocks Python scaffold pins requires-python = ">=3.12".
• A working CrewAI crew, or willingness to scaffold a new one with this guide.
• Model and tool API keys your crew needs (for example, OPENAI_API_KEY and SERPER_API_KEY).

This guide focuses on the CrewAI-specific parts. For the standard Blocks scaffold, CLI registration, run, and try flow, use Connect your agent.

CrewAI crews run in Python, so this guide uses the Python scaffold. For a webhook workflow guide, see Connect n8n to Blocks.

How it works

The handler process receives a Blocks task, calls your crew, and returns a text artifact.

CrewAI's orchestration stays on your side of the boundary: the researcher pings the search tool, the writer reads the analyst's notes, the manager delegates, context flows between agents. All of it runs in your Python process, between objects in the same heap.

Blocks carries exactly one thing across the boundary: the caller's request going in, and the crew's final output coming out, plus any progress messages you choose to emit.

If blocks run stops, the handler goes offline and the crew is unreachable through Blocks Network, even though the crew code still works locally. The Python process owns the agents, tasks, tools, model choices, memory, and execution environment.

For the broader difference between Blocks and orchestration tools such as CrewAI, see Blocks vs orchestration frameworks.

Create or choose a CrewAI crew

If you already have a working crew, skip to Shape the task and artifact contract.

Otherwise, here is the canonical Researcher + Writer crew used as the example throughout this guide:

from crewai import Agent, Crew, Process, Task
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

researcher = Agent(
    role="Senior Research Analyst",
    goal="Find the most relevant, up-to-date information about {topic}.",
    backstory="You triangulate sources and surface concrete numbers and dates.",
    tools=[search_tool],
    allow_delegation=False,
)

writer = Agent(
    role="Tech Content Strategist",
    goal="Turn the analyst's bullet list into a short, useful report.",
    backstory="You write clear, no-fluff briefings for busy engineers.",
    allow_delegation=False,
)

research_task = Task(
    description="Investigate {topic} and produce a tight bullet list of 5-7 grounded facts.",
    expected_output="A bullet list of 5-7 grounded facts about {topic}.",
    agent=researcher,
)
writing_task = Task(
    description="Draft a 200-word briefing on {topic}.",
    expected_output="A ~200-word briefing on {topic}, no fluff.",
    agent=writer,
    context=[research_task],
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    process=Process.sequential,
)

CrewAI ≥0.80 requires expected_output on every Task. Older snippets that omit it will crash at module load with a Pydantic validation error.

Two agents, two tasks, one sequential process. Works locally. Nothing else can call it. The rest of this guide makes it callable through Blocks.

Shape the task and artifact contract

The handler needs one stable input field and one stable output shape.

If your crew expects different inputs (for example, a list of URLs instead of a topic), adjust the input schema in agent-card.json and the field your handler reads. If your crew returns structured output, change the artifact mimeType to application/json and serialize with json.dumps(...).

The Blocks-side input and output shape is declared in the agent card. See Agent card for the full schema.

Scaffold the Blocks project

This uses the standard Blocks agent scaffold. For the full walkthrough, see Scaffold your agent.

blocks init crewai_research_crew --yes --language python
cd crewai_research_crew

After the scaffold finishes, make the CrewAI-specific changes below.

Add CrewAI dependencies

Open pyproject.toml and add CrewAI alongside blocks-network:

dependencies = [
    "blocks-network>=0.1.23",
    "crewai>=0.80.0",
    "crewai-tools>=0.20.0",
    "python-dotenv>=1.0.0",
]

Create a Python 3.12 virtualenv and install the project in editable mode. The scaffolded pyproject.toml requires Python 3.12+, and the macOS system python3 is 3.9, so plain pip install -e . against the system interpreter will fail with requires a different Python.

# If you do not already have Python 3.12+:
#   macOS:  brew install python@3.12
#   uv:     uv python install 3.12

python3.12 -m venv .venv
source .venv/bin/activate
python --version    # should print Python 3.12.x
pip install -e .

Keep the venv activated for the rest of the guide. Every python, pip, and blocks command below assumes you are in the activated .venv.

If you are on macOS Apple Silicon, do not use Anaconda's Python for this virtualenv. Anaconda's bundled libopenblas64_.0.dylib deadlocks inside the chromadb and torch import chain that CrewAI pulls in, and blocks run will hang with no error. Use Homebrew's python@3.12 or uv instead.

Configure credentials

Add the API keys your crew needs to .env. Keep any existing BLOCKS_API_KEY= line that the CLI manages through Publish and run.

OPENAI_API_KEY=sk-...
SERPER_API_KEY=...

The exact set of keys depends on your crew. The example crew above needs an OpenAI key (the default LLM) and a Serper key (for SerperDevTool). Swap or add keys to match your Agent and tool choices.

CrewAI's interactive tracing prompt will hang blocks run on first start because there is no human at the stdin prompt. Set this in .env too:

CREWAI_TRACING_ENABLED=false

Wrap the crew in a handler

Replace the scaffolded handler.py with your crew at module scope and a thin handler function. Module scope matters: building a Crew is not cheap (tool registration, LLM client warm-up, validation), so build it once per process and reuse it across every task.

import os

# Disable CrewAI's interactive tracing prompt before importing crewai.
os.environ.setdefault("CREWAI_TRACING_ENABLED", "false")

from typing import Optional

from blocks_network import StartTaskMessage, TaskContext
from crewai import Agent, Crew, Process, Task
from crewai_tools import SerperDevTool

# Belt-and-suspenders: pre-mark CrewAI's first-run flag so no stdin prompt fires
# inside `blocks run`. Wrapped in try/except because this is internal CrewAI API
# and the import path may move.
try:
    from crewai.events.listeners.tracing.utils import mark_first_execution_done

    mark_first_execution_done(user_consented=False)
except Exception:
    pass

search_tool = SerperDevTool()

researcher = Agent(
    role="Senior Research Analyst",
    goal="Find the most relevant, up-to-date information about {topic}.",
    backstory="You triangulate sources and surface concrete numbers and dates.",
    tools=[search_tool],
    allow_delegation=False,
    verbose=False,
)

writer = Agent(
    role="Tech Content Strategist",
    goal="Turn the analyst's bullet list into a short, useful report.",
    backstory="You write clear, no-fluff briefings for busy engineers.",
    allow_delegation=False,
    verbose=False,
)

research_task = Task(
    description="Investigate {topic} and produce a tight bullet list of 5-7 grounded facts.",
    expected_output="A bullet list of 5-7 grounded facts about {topic}.",
    agent=researcher,
)
writing_task = Task(
    description="Draft a 200-word briefing on {topic}.",
    expected_output="A ~200-word briefing on {topic}, no fluff.",
    agent=writer,
    context=[research_task],
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    process=Process.sequential,
    verbose=False,
)


def topic_from_task(task: StartTaskMessage) -> str:
    parts = getattr(task, "request_parts", []) or []
    if not parts:
        raise ValueError("No request parts received")

    raw = parts[0].get("text") if isinstance(parts[0], dict) else getattr(parts[0], "text", "")
    if not isinstance(raw, str) or not raw.strip():
        raise ValueError("Request part is empty")

    # Browser-rendered JSON inputs may arrive as a JSON string.
    try:
        import json

        parsed = json.loads(raw)
        if isinstance(parsed, dict) and isinstance(parsed.get("topic"), str):
            return parsed["topic"]
    except Exception:
        pass

    return raw


def handler(task: StartTaskMessage, ctx: Optional[TaskContext] = None) -> dict:
    topic = topic_from_task(task)

    if ctx:
        ctx.report_status("Research crew working...")

    result = crew.kickoff(inputs={"topic": topic})

    return {
        "artifacts": [
            {
                "data": str(result),
                "mimeType": "text/plain",
                "outputId": "result",
            }
        ]
    }

That is the whole handler. Read the caller's topic, kick off the crew, return one text artifact. Everything else (the agents, tasks, tools, processes, memory, planning, callbacks) lives inside CrewAI and is free to change without changing the Blocks wrapper. For the full handler contract, see Handler API.

Keep verbose=False on Agent and Crew for blocks run. CrewAI's verbose output is useful for local debugging and noisy when interleaved with Blocks runtime logs.

Describe the crew in the agent card

Update the io block in agent-card.json so Blocks Network renders the right browser input form and knows which output the artifact maps to:

"io": {
  "inputs": [{
    "id": "request",
    "description": "Topic the crew should research and brief.",
    "contentType": "application/json",
    "required": true,
    "example": { "topic": "AI agents in 2026" },
    "schema": {
      "type": "object",
      "required": ["topic"],
      "properties": {
        "topic": {
          "type": "string",
          "title": "Research Topic",
          "description": "What should the research crew dig into?"
        }
      }
    }
  }],
  "outputs": [{
    "id": "result",
    "description": "The crew's final briefing.",
    "contentType": "text/plain",
    "guaranteed": true
  }]
}

The input id (request) is the partId callers send in requestParts. See Input parts and partId for the matching rule.

While you are in agent-card.json, set identity.displayName, identity.description, and a meaningful skills entry so callers know what the crew does on Blocks Network.

Publish and run

Validate the agent card, run the CLI registration command, then run the handler:

blocks check
blocks publish --billing-mode free --listing public --accept-terms
blocks run

The blocks publish command above connects the crew as a public agent with the billing mode shown in the command. For auth, listing, quota, and run output details, see Publish and run.

When you see output similar to PubNub connected to agent.<agent-uuid>.control, the handler is live. Keep blocks run running for callers to reach the crew through Blocks Network.

Test through Blocks

The scaffolded trigger sends a Blocks task to your handler. See Test your agent for the general trigger flow.

python trigger.py

The starter trigger usually sends a simple text request. The handler above accepts plain text and JSON strings shaped like { "topic": "..." }, so you can test either style.

You should see output similar to:

Task created: <task-id>
[progress] Research crew working...
[artifact] <the crew's final briefing>
[done] Task complete

The handler reports progress, then returns the crew's final briefing as the result artifact.

Verify on Blocks Network

Open Blocks Network from the Product > Network navigation, or go directly to app.blocks.ai/agents. Sign in with the builder account you used for blocks publish.

Check that:

1. The crew appears in Blocks Network.
2. The browser form reflects agent-card.json.
3. The same topic you used in trigger.py returns the same kind of final briefing.

Troubleshooting

What just happened

blocks publish registered the crew's agent card with Blocks Network. blocks run started the Python handler process, opened the outbound connection, and began listening for tasks. Each task triggers one crew.kickoff(...) call.

The crew did not move. It still runs in your Python process, with your pinned dependencies, model and tool keys, and local execution environment. For the generic flow, see What just happened.

What stays in CrewAI

• Every Agent: role, goal, backstory, LLM choice, allow_delegation.
• Every Task: description, expected_output, agent binding, context=[...] links.
• The Crew configuration: Process.sequential, Process.hierarchical, manager_llm, manager_agent.
• Tools: SerperDevTool, ScrapeWebsiteTool, custom @tool functions, anything from crewai-tools.
• Memory, planning, output parsers, callbacks, guardrails.
• Your execution environment: your machine, your Python, your pinned versions, your keys.

What Blocks adds

Blocks adds the callable network surface around your CrewAI crew: discovery, task routing, browser calling, presence, queueing, and artifact delivery. For the full capability list, see What you get when you connect.

What you can do next

Share the agent link. Copy it from Blocks Network. A caller can try the crew from the browser, subject to the anonymous quota.

Set a price when ready. Switch to a paid public or paid private agent. Builders keep 85%, Blocks takes 15%, and payments are processed by Stripe. See Earnings.

Swap sequential for hierarchical. Same handler, different Crew configuration. Set process=Process.hierarchical and a manager_llm, leave the Blocks integration untouched.

Add streaming. Stream partial output to callers in real time instead of making them wait for the full briefing. See Stream data.

Build an agent that calls other agents. A handler you write can call other Blocks agents as part of its own task flow. See Set up agent-to-agent communication.