Protocol Integration Quick Start

Get up and running with FCC protocol integration in 15 minutes. This guide covers agent card generation, MCP server concepts, AGENTS.md output, and protocol event exploration.

---

Prerequisites

• Python 3.10+
• FCC package installed (pip install -e .)
• Persona YAML files loaded (ships with the package)

Verify your installation:

python -c "from fcc.personas.registry import PersonaRegistry; r = PersonaRegistry.from_data_dir(); print(f'{len(list(r))} personas loaded')"

You should see 107 personas loaded (or the current persona count).

---

1. Generate Agent Cards

A2A agent cards describe persona capabilities in a format external agents can discover and invoke.

from fcc.personas.registry import PersonaRegistry
import json

registry = PersonaRegistry.from_data_dir()

def persona_to_agent_card(persona):
    spec = persona.riscear
    return {
        "agent_id": f"fcc-{persona.id.lower()}",
        "name": persona.name,
        "version": "1.0.0",
        "description": spec.role,
        "archetype": spec.archetype,
        "fcc_phase": persona.fcc_phase,
        "category": persona.category,
        "skills": [
            {"name": s, "type": "capability"}
            for s in (spec.role_skills or [])
        ],
        "constraints": spec.constraints,
    }

# Generate a card for the Research Crafter
rc = registry.get("RC")
card = persona_to_agent_card(rc)
print(json.dumps(card, indent=2))

Generate cards for all personas:

all_cards = [persona_to_agent_card(p) for p in registry]
print(f"Generated {len(all_cards)} agent cards")

# Save to file
with open("agent_cards.json", "w") as f:
    json.dump(all_cards, f, indent=2)

---

2. Understand MCP Server Concepts

The MCP server exposes FCC as 14 tools and 14 resources. Tools are callable functions; resources are readable data endpoints.

Key tools:

Tool	What it does
list_personas	List all personas with optional category filter
get_persona	Get detailed persona info by ID
search_personas	Search by name, role, or archetype
run_mock_simulation	Run a deterministic simulation
check_constitution	Validate constitution compliance

Key resources:

URI	Content
fcc://personas	Full persona registry
fcc://workflows	Workflow graph definitions
fcc://quality-gates	Quality gate definitions
fcc://cross-references	Persona cross-reference matrix

---

3. Generate AGENTS.md

The AGENTS.md file provides human-readable agent documentation:

from fcc.personas.registry import PersonaRegistry

registry = PersonaRegistry.from_data_dir()

lines = ["# AGENTS.md", "", "## FCC Agent Team", ""]
for p in sorted(registry, key=lambda p: p.id):
    lines.append(f"### {p.id} -- {p.name}")
    lines.append(f"")
    lines.append(f"- **Phase:** {p.fcc_phase}")
    lines.append(f"- **Category:** {p.category}")
    lines.append(f"- **Archetype:** {p.riscear.archetype}")
    lines.append(f"- **Role:** {p.riscear.role}")
    if p.riscear.role_skills:
        lines.append(f"- **Skills:** {', '.join(p.riscear.role_skills)}")
    lines.append("")

agents_md = "\n".join(lines)
with open("AGENTS.md", "w") as f:
    f.write(agents_md)
print(f"Generated AGENTS.md with {len(list(registry))} agent entries")

---

4. Explore Protocol Events

The EventBus bridges internal FCC events to protocol streams. Explore event types and subscribe to protocol-relevant events:

from fcc.messaging.events import EventType

print("Protocol-relevant event types:")
for et in EventType:
    print(f"  {et.name}: {et.value}")

Create a protocol event subscriber:

from fcc.messaging.bus import EventBus, Subscriber, EventFilter
from fcc.messaging.events import Event, EventType

bus = EventBus()

# Subscribe to simulation events
events_received = []

def on_event(event: Event) -> None:
    events_received.append(event)
    print(f"  Received: {event.event_type.value} from {event.source}")

subscriber = Subscriber(
    name="protocol-bridge",
    callback=on_event,
    event_filter=EventFilter(event_types={EventType.SIMULATION_STARTED}),
)

bus.subscribe(subscriber)
print(f"Subscribed to EventBus as 'protocol-bridge'")
print(f"Active subscribers: {bus.subscriber_count()}")

---

Next Steps

• Notebook 13 (notebooks/13_protocol_integration.ipynb): Hands-on protocol integration exercises
• Protocol Explorer (apps/streamlit/protocol_explorer.py): Visual protocol browsing app
• Chapter 15 (docs/guidebook/ch15_protocol_integration.md): Full protocol integration guide
• Sample Prompts (docs/tutorials/sample-prompts/protocol-engineering-prompts.md): Ready-to-use prompts for protocol engineering personas