# Teaching Script — DD-12: CrewAI (Role-Based Multi-Agent, Emergent Coordination)

**Course**: Master Course · **Deep-Dive**: DD-12 · **Duration**: 60 minutes · **Audience**: Senior Engineer and above
**Slides**: `03-slide-deck.html` (10 slides)

> *45,900+ stars. Most accessible multi-agent framework. Role-based sequential/concurrent crews. The emergent-coordination pole — paired with LangGraph (DD-10) as the declared-coordination pole, both load-bearing for Course 4 E09 (Multi-Agent Orchestration).*

---

## [SLIDE 1] Title — CrewAI

Welcome to DD-12, CrewAI. This is the role-based multi-agent framework, and it is the most accessible entry point into multi-agent orchestration in the entire roster. Where LangGraph, DD-10, makes you draw explicit nodes and edges, and the OpenAI Agents SDK, DD-11, hands you handoffs and agents-as-tools as primitives, CrewAI asks you to do something far more intuitive. Describe the team you wish you had, and it runs.

That is the pitch, and the 45,900 stars on GitHub tell you it landed. Today we study why the mental model works, what it sacrifices, and how it pairs with LangGraph to define the multi-agent coordination axis that Course 4's E09 module takes as its organizing principle.

## [SLIDE 2] The thesis — describe the team

The three frameworks on the screen are the multi-agent landscape you need to hold in your head. LangGraph, DD-10, on the left — draw the graph. Declared coordination. Maximum ceremony, maximum auditability. The OpenAI Agents SDK, DD-11, on the right — compose agents. Handoffs plus agents-as-tools. Production primitives with sandboxing. And CrewAI in the middle — describe the team. Roles, goals, backstories. Emergent coordination. The graph is not drawn; it emerges from task context references and the process type.

Here is the key phrase: "describe the team" beats "draw the graph" for first-time builders. That is CrewAI's whole value proposition, and it is real. The cost is on the screen too — the emergent graph is invisible past about five tasks, and the framework sacrifices production-readiness. No sandbox. Crew-scoped shared memory with no write isolation. Run logs below the structured-event floor. CrewAI is a framework for orchestration prototyping and teaching, not a production harness. Hold both sides of that in your head.

## [SLIDE 3] The three primitives — Crew, Agent, Task

The entire mental model is three primitives. The Agent is the unit of role. An agent is its system prompt, assembled from role, goal, backstory, plus the tool set it can call. Role IS the system prompt — that is the load-bearing insight. CrewAI does not give you a raw system-prompt string; it gives you a templated one whose fields are role, goal, and backstory. This is Module 12, prompt assembly, applied at the agent granularity rather than the harness granularity. The template is the framework's opinion.

The Task is the unit of work. A task has a description, an assigned agent, an expected output, and optional context — other tasks whose output feeds this one. And here is the architectural decision: tasks carry the dependency graph implicitly. If Task B lists Task A in context, A runs first and its result is injected into B's prompt. The graph is not drawn; it emerges from context references.

The Crew is the unit of orchestration. It holds the agents, the tasks, and the process strategy. It owns the loop, the memory, the kickoff entry point. Crewai kickoff reads the process type and dispatches. That is the entire mental model — and the reason it has 45,000 stars.

## [SLIDE 4] Emergent vs declared coordination — the load-bearing axis

Now the central architectural claim of this deep-dive. CrewAI and LangGraph define the multi-agent coordination axis, and this axis is load-bearing for Course 4's E09 module.

CrewAI is the emergent-coordination pole. You define roles and tasks. The coordination graph emerges from task context references and the process type. You never draw an edge. This is simpler to declare and more intuitive for first-time builders. The cost: the emergent graph is invisible. For a three-agent crew this is a feature. For a fifteen-agent crew it becomes a liability — the implicit dependency graph cannot be audited, checkpointed at specific nodes, or edited without rerunning the crew.

LangGraph, DD-10, is the declared-coordination pole. You draw explicit nodes and edges. The graph is a first-class object you can visualize, checkpoint, and edit. More ceremony upfront, but the graph is fully auditable. You can interrupt at any node, resume from any checkpoint, and prove properties about the flow.

Every other multi-agent framework in the roster sits between these two poles. And the diagnostic question is on the screen: do you need to prove properties about the coordination graph? If yes — compliance, security audit, reproducibility — declared coordination earns its ceremony. If no — prototyping, internal tools, exploratory work — emergent coordination earns its speed. That choice is the organizing principle of Course 4 E09. When you choose a multi-agent architecture, you are choosing where to sit on this axis.

## [SLIDE 5] Two orchestration modes

Sequential is the default and the well-trodden path. Tasks run in list order; each task's output is appended to a shared context the next agent reads. This is a linear ReAct chain stretched across multiple roles — conceptually close to Module 1's conversation-driven loop, except each turn is owned by a different role-shaped system prompt. Sequential composes well for research-then-write, draft-then-review, plan-then-execute. This is where CrewAI earns its 4-out-of-5 on Module 1.3, subagents — it is a textbook multi-agent pattern.

Concurrent, or hierarchical, adds a manager agent that decomposes the goal, assigns subtasks to the worker agents, runs them, and synthesizes results. This is closer to the meta-hierarchy in DD-06, oh-my-opencode's Sisyphus, Prometheus, Atlas, Junior taxonomy — except CrewAI's manager is implicit and the hierarchy is one level deep, whereas DD-06's is a deliberate multi-tier design. Use sequential for clean role decomposition; use hierarchical when a manager's synthesis adds value the sequential chain cannot.

## [SLIDE 6] The security surface — handoffs plus shared memory

Now the security architecture, and there are two attack surfaces CrewAI's design creates. Both are consequences of the role-based, crew-scoped model.

First: task-output handoff injection. Each handoff — where one agent's output becomes the next agent's input — is an untrusted-content boundary. Module 2.4, Vector 1. A compromised upstream agent can inject instructions into its task output that the downstream agent reads and acts on. Indirect prompt injection propagating through the handoff. The cure is to treat every handoff as untrusted input — validate task outputs before injecting them into the next agent's prompt. Do not assume the upstream agent's output is benign just because the upstream agent was declared with a benign role.

Second: crew-scoped memory poisoning. All agents in a crew share one memory store. There is no write isolation — Module 4.3's write-gating defense is unavailable by default. A compromised agent writes a poisoned entry that every other agent in the crew later reads. This is the same compounding-poisoning argument as Hermes, DD-08, except here the compounding is across agents within a single crew run, not across sessions. The compounding that makes shared memory convenient is the same compounding that makes poisoning dangerous. The cure is to opt for agent-scoped memory — which is not available by default, and is one of the three things to fix.

## [SLIDE 7] The score profile — 33/60, orchestration-first shape

Now the score. 33 out of 60. Highest on Module 1.3, subagents, at 4-out-of-5 — sequential crews are a textbook multi-agent pattern, and the role-based mental model is the most accessible in the category. Module 1, loop, at 3-out-of-5 — role-per-turn is clean but token-heavy, no steering mid-crew. Module 2, tools, at 3-out-of-5 — per-agent attachment is good, no isolation enforcement. Module 4, memory, at 3-out-of-5 — three tiers exist, but crew-scoping forfeits write isolation.

The low scores are where CrewAI's orchestration-first design shows. Module 5, sandbox, 1-out-of-5 — none, bring your own. Module 8, state, 2-out-of-5 — limited checkpointing, long crews don't resume. Module 9, verification, 1-out-of-5 — none built-in. Module 11, security, 1-out-of-5 — no security model, shared memory is an attack surface.

Read the score as a profile, not a ranking. The 4-out-of-5 on Module 1.3 and the 1-out-of-5 on Modules 5, 9, and 11 are the same design decision — CrewAI optimizes for orchestration accessibility and treats production-readiness as bring-your-own. This is the orchestration-first shape. You build on CrewAI to prototype multi-agent patterns and to teach orchestration. You move to LangGraph when the dependency graph needs to be explicit, or to the Agents SDK when you need sandboxing and handoffs as primitives.

## [SLIDE 8] Anti-patterns

Three anti-patterns to avoid. First: role-ifying everything because the abstraction is pleasant. The role-goal-backstory template is so intuitive that every multi-step task becomes a crew. The cost: latency, token cost — each agent re-reads shared context — and a new injection surface per handoff. The cure is the diagnostic question. If one agent with one system prompt and a subtask list could do the work, you don't need a crew. Reserve multi-agent for work that genuinely decomposes along role lines with different policies, tool sets, or verification duties.

Second: treating task-output handoffs as trusted. Each handoff is an untrusted-content boundary. A compromised upstream agent injects instructions the downstream agent executes. The cure is to validate task outputs before injecting them into the next agent's prompt. Treat every handoff as untrusted input.

Third: deploying CrewAI crews without sandboxing. CrewAI has no built-in sandbox — Module 5 at 1-out-of-5. If your agents execute tools with side effects, those tools run on the host with no isolation. The cure is to bring your own sandbox — Docker, E2B — and route tool execution through it. This is the same lesson as NemoClaw, DD-09, and the Agents SDK, DD-11 — isolation is not optional in production — except CrewAI makes it bring-your-own rather than baked in.

## [SLIDE 9] What you can now do — (covered in closing)

## [SLIDE 10] Closing

Let me close the loop. After this deep-dive, you can state CrewAI's defining contribution — the role-based mental model — and why "describe the team" is the most accessible multi-agent entry point. You can distinguish emergent coordination, CrewAI, from declared coordination, LangGraph, and explain why this contrast defines the multi-agent coordination axis that Course 4 E09 takes as its organizing principle. You can describe the three primitives, the two orchestration modes, and the role-to-prompt mapping. You can score CrewAI 33 out of 60 and defend the shape. And you can articulate the security implications of crew-scoped shared memory and the untrusted-content boundary at each task handoff.

The lab simulates a CrewAI-style role-based crew in pure Python. You define agents with role-goal-backstory, assign tasks, run a sequential crew, observe the emergent dependency graph, and demonstrate the security risk — indirect prompt injection propagating through a task-output handoff into crew-scoped shared memory. That is the work.

Remember the load-bearing claim. CrewAI is the emergent-coordination pole; LangGraph is the declared-coordination pole. Every multi-agent framework sits between them. When you choose a multi-agent architecture, you are choosing where to sit on this axis, and the choice is a tradeoff between declaration speed and auditability. That is the Course 4 E09 connection, and it is why this deep-dive pairs with DD-10.

Next is DD-13, OpenHarness. See you there.

---

*End of teaching script. Approximate word count: 2000 words. Pair with slides 1-10 in `03-slide-deck.html`. Slides 9 and 10 are covered together in the closing section.*