Skip to content

CrewAI Integration

This tutorial shows you how to use FCC personas as CrewAI agents. CrewAI's role-based agent model is a natural fit for FCC's R.I.S.C.E.A.R. specifications: CrewAI agents require a role, goal, and backstory, all of which map directly to R.I.S.C.E.A.R. fields.

Prerequisites

pip install fcc-agent-team-ext crewai crewai-tools

You will also need an OpenAI API key or another LLM provider supported by CrewAI.

The R.I.S.C.E.A.R. to CrewAI Mapping

CrewAI's Agent class requires three primary fields. Here is how they map from FCC:

CrewAI Field FCC Source Rationale
role persona.role_title Short, descriptive role label
goal persona.riscear.role Narrative description of the agent's purpose
backstory Full R.I.S.C.E.A.R. system prompt Rich behavioral context including style, archetype, constraints

Step 1: Load Personas and Build Agents

from fcc._resources import get_personas_dir
from fcc.personas.registry import PersonaRegistry
from fcc.simulation.prompts import build_persona_system_prompt
from crewai import Agent

registry = PersonaRegistry.from_yaml_directory(get_personas_dir())

def fcc_to_crewai_agent(persona_id: str, llm=None) -> Agent:
    """Convert an FCC PersonaSpec into a CrewAI Agent."""
    persona = registry.get(persona_id)
    backstory = build_persona_system_prompt(persona)

    return Agent(
        role=persona.role_title,
        goal=persona.riscear.role,
        backstory=backstory,
        verbose=True,
        allow_delegation=False,
        llm=llm,
    )

# Create agents for the core FCC cycle
researcher = fcc_to_crewai_agent("RC")
architect = fcc_to_crewai_agent("BC")
evangelist = fcc_to_crewai_agent("DE")

Step 2: Define Tasks from R.I.S.C.E.A.R. Expected Output

Each persona's expected_output field describes the deliverables it produces. Use these to define CrewAI tasks:

from crewai import Task

def make_task(persona_id: str, agent: Agent, description: str, context=None) -> Task:
    """Create a Task using the persona's expected_output as the output spec."""
    persona = registry.get(persona_id)
    expected = "\n".join(f"- {e}" for e in persona.riscear.expected_output)

    return Task(
        description=description,
        expected_output=f"Produce the following deliverables:\n{expected}",
        agent=agent,
        context=context or [],
    )

# Find phase: Research Crafter gathers information
research_task = make_task(
    "RC",
    researcher,
    "Research API rate limiting patterns, gathering best practices, "
    "common implementations, and security considerations.",
)

# Create phase: Blueprint Crafter designs the solution
blueprint_task = make_task(
    "BC",
    architect,
    "Create a detailed blueprint for an API rate limiting system "
    "based on the research findings.",
    context=[research_task],
)

# Critique phase: Documentation Evangelist reviews
review_task = make_task(
    "DE",
    evangelist,
    "Review the blueprint for completeness, clarity, and adherence "
    "to documentation standards. Provide specific improvement suggestions.",
    context=[blueprint_task],
)

Step 3: Build and Run the Crew

from crewai import Crew, Process

crew = Crew(
    agents=[researcher, architect, evangelist],
    tasks=[research_task, blueprint_task, review_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff()
print(result)

Advanced: Champion-Orchestrated Crew

FCC champion personas orchestrate teams of base personas. This maps naturally to CrewAI's hierarchical process mode. The champion becomes the manager agent:

# Load the Research Crafter Champion and its team
rchm = registry.get("RCHM")  # Research Crafter Champion
team_ids = rchm.orchestrates  # ["RC", "CIA", "STE", "RIC"]

# Build the team
team_agents = [fcc_to_crewai_agent(pid) for pid in team_ids]

# Build the champion as the manager
champion_agent = fcc_to_crewai_agent("RCHM")

# Create tasks for each team member
team_tasks = []
for pid, agent in zip(team_ids, team_agents):
    persona = registry.get(pid)
    task = make_task(
        pid,
        agent,
        f"Execute your responsibilities as the {persona.name}: "
        f"{persona.riscear.role[:200]}",
    )
    team_tasks.append(task)

# Build the crew with hierarchical process
research_crew = Crew(
    agents=team_agents,
    tasks=team_tasks,
    process=Process.hierarchical,
    manager_agent=champion_agent,
    verbose=True,
)

result = research_crew.kickoff()

Advanced: Cross-Reference-Driven Delegation

Use the cross-reference matrix to enable intelligent delegation. When an agent needs input from another persona, the matrix tells you exactly who to ask:

from fcc.personas.cross_reference import CrossReferenceMatrix

matrix = CrossReferenceMatrix.from_yaml(get_personas_dir() / "cross_reference.yaml")

def get_upstream_context(persona_id: str) -> str:
    """Build a context description from upstream interactions."""
    upstream = matrix.upstream(persona_id)
    if not upstream:
        return "No upstream dependencies."

    lines = []
    for entry in upstream:
        source = registry.get(entry.source_id)
        lines.append(
            f"- {source.name} ({entry.relationship_type}): {entry.interaction}"
        )
    return "Upstream inputs:\n" + "\n".join(lines)

# Include upstream context in the task description
bc_context = get_upstream_context("BC")
blueprint_task = Task(
    description=(
        f"Create a blueprint for the API rate limiting system.\n\n{bc_context}"
    ),
    expected_output="Design documents with architecture diagrams",
    agent=architect,
    context=[research_task],
)

Adding Constraints as Guardrails

FCC constraints translate well to CrewAI guardrails. Include them in the agent's backstory or as task validation:

def fcc_to_crewai_agent_with_guardrails(persona_id: str) -> Agent:
    """Create a CrewAI agent with explicit constraint guardrails."""
    persona = registry.get(persona_id)
    backstory = build_persona_system_prompt(persona)

    # Append explicit guardrails section
    constraints = "\n".join(f"- {c}" for c in persona.riscear.constraints)
    backstory += (
        f"\n\n## GUARDRAILS (Non-negotiable)\n"
        f"You MUST adhere to these constraints at all times:\n{constraints}"
    )

    return Agent(
        role=persona.role_title,
        goal=persona.riscear.role,
        backstory=backstory,
        verbose=True,
    )

Complete Example: Full FCC Crew

This example builds a five-persona crew covering the entire FCC core cycle:

from fcc._resources import get_personas_dir
from fcc.personas.registry import PersonaRegistry
from fcc.simulation.prompts import build_persona_system_prompt
from crewai import Agent, Task, Crew, Process

registry = PersonaRegistry.from_yaml_directory(get_personas_dir())

# Build all five core agents
agents = {}
for pid in ["RC", "BC", "DE", "RB", "UG"]:
    persona = registry.get(pid)
    agents[pid] = Agent(
        role=persona.role_title,
        goal=persona.riscear.role,
        backstory=build_persona_system_prompt(persona),
        verbose=True,
        allow_delegation=False,
    )

# Define the FCC pipeline tasks
topic = "CI/CD pipeline documentation for a microservices platform"

tasks = [
    Task(description=f"Research: {topic}", expected_output="Research inventory",
         agent=agents["RC"]),
    Task(description="Create blueprint from research", expected_output="Design document",
         agent=agents["BC"]),
    Task(description="Create operational runbook", expected_output="Step-by-step runbook",
         agent=agents["RB"]),
    Task(description="Create end-user guide", expected_output="User guide",
         agent=agents["UG"]),
    Task(description="Review all outputs for quality", expected_output="Review report",
         agent=agents["DE"]),
]

crew = Crew(agents=list(agents.values()), tasks=tasks, process=Process.sequential)
result = crew.kickoff()
print(result)

Tips for Production Use

  1. Use champion personas as managers. CrewAI's hierarchical process mode maps directly to FCC's champion architecture, where RCHM, BCHM, UGCH, and RBCH each coordinate a team.
  2. Enable delegation selectively. Set allow_delegation=True only for champion agents. Base personas should execute their own work.
  3. Map cross-reference coordination to peer interactions. When two personas have a coordination relationship, they may need bidirectional tool access in CrewAI.
  4. Use riscear.role_adoption_checklist for acceptance criteria. Each persona's adoption checklist defines what "done" looks like -- use it in task expected_output.