Skip to content

Chapter 15: Protocol Integration

What is Protocol Integration?

Protocol integration extends the FCC framework beyond its internal Find-Create-Critique cycle to interoperate with external agent ecosystems. Rather than operating as a closed system, FCC publishes its capabilities through industry-standard protocols that allow other agent platforms, LLM hosts, and developer tools to discover and invoke FCC functionality.

Three protocols form the integration layer:

Protocol Standard Purpose
A2A Google Agent-to-Agent Publish persona capabilities as discoverable agent skills
MCP Anthropic Model Context Protocol Expose tools, resources, and prompts to LLM hosts
AGENTS.md Community convention Generate human-readable agent documentation

The sequence diagram below traces an external A2A task request from arrival through skill validation, event-bus routing, persona activation, and response serialization.

sequenceDiagram
    participant Ext as External Agent
    participant A2A as A2A Protocol
    participant ASD as A2A Skill Designer
    participant EBO as Event Bridge Orchestrator
    participant EB as EventBus
    participant P as FCC Persona

    Ext->>A2A: Send Task Request
    A2A->>ASD: Validate against skill defs
    ASD->>EBO: Route to EventBus
    EBO->>EB: publish(task.received)
    EB->>P: Activate persona
    P->>EB: publish(task.completed)
    EB->>EBO: Collect result
    EBO->>A2A: Serialize response
    A2A->>Ext: Return result

The same bridging pattern is reused for MCP tool calls; only the validator and serializer endpoints change.

Six protocol engineering personas manage these integrations:

ID Name Responsibility
ASD A2A Skill Designer Agent card specifications and skill definitions
MTA MCP Tool Architect Tool schemas, resource URIs, and prompt templates
EBO Event Bridge Orchestrator EventBus to protocol stream bridging
WSM WebSocket Stream Manager Real-time event delivery over WebSocket
PCA Protocol Compliance Auditor Protocol conformance verification
AMG AGENTS.md Generator Human-readable agent documentation

A2A Protocol: Agent Cards, Skills, Task Handling

What is an Agent Card?

An A2A Agent Card is a JSON document that describes an agent's identity, capabilities, and interaction protocols. In FCC, each persona maps naturally to an agent card because the R.I.S.C.E.A.R. specification already captures the data needed:

  • Skills come from role_skills
  • Capabilities come from responsibilities
  • Constraints come from constraints
  • Collaborators come from role_collaborators

Creating Agent Cards

from fcc.personas.registry import PersonaRegistry

registry = PersonaRegistry.from_data_dir()
persona = registry.get("RC")

agent_card = {
    "agent_id": f"fcc-{persona.id.lower()}",
    "name": persona.name,
    "version": "1.0.0",
    "description": persona.riscear.role,
    "archetype": persona.riscear.archetype,
    "skills": [
        {"name": skill, "type": "capability"}
        for skill in persona.riscear.role_skills
    ],
    "constraints": persona.riscear.constraints,
    "collaborators": persona.riscear.role_collaborators,
}

Skill Definitions

Each skill in an agent card corresponds to a specific capability that external agents can invoke. Skills include:

  • Input requirements: What the skill needs to operate
  • Output guarantees: What the skill produces
  • Constraint boundaries: What the skill will not do

Task Handling

When an external agent sends a task to an FCC persona via A2A:

  1. The A2A Skill Designer (ASD) validates the request against the persona's skill definitions
  2. The Event Bridge Orchestrator (EBO) routes the task through the EventBus for internal processing
  3. The persona executes the task within its R.I.S.C.E.A.R. constraints
  4. The response is serialized back through the A2A protocol

MCP Server: Tools, Resources, Prompts

Tool Definitions

The MCP server exposes FCC capabilities as structured tools. Each tool has a name, description, and JSON Schema for its input parameters.

FCC defines 14 tools organized by source module:

Module Tools
fcc.personas.registry list_personas, get_persona, search_personas
fcc.workflow list_workflows, get_workflow
fcc.governance check_constitution, evaluate_quality_gate
fcc.simulation run_mock_simulation
fcc.scenarios list_scenarios
fcc.personas.cross_reference get_cross_references
fcc.scaffold.doc_generator generate_docs
fcc.messaging.events list_event_types
fcc.collaboration start_collaboration_session
fcc.plugins list_plugins

Resource URIs

MCP resources use a structured fcc:// URI scheme:

fcc://personas              # Full persona registry
fcc://personas/{id}         # Individual persona
fcc://workflows             # Available workflow graphs
fcc://workflows/{name}      # Specific workflow
fcc://scenarios             # Simulation scenarios
fcc://constitutions/{id}    # Persona constitution rules
fcc://quality-gates         # Quality gate definitions
fcc://cross-references      # Cross-reference matrix
fcc://tags                  # Tag registry
fcc://events/types          # Event type catalog
fcc://actions/{persona_id}  # Workflow actions
fcc://plugins               # Plugin registry
fcc://ecosystem             # Ecosystem metadata
fcc://collaboration/sessions # Active sessions

Prompt Templates

The MCP server includes prompt templates that help LLM hosts use FCC tools effectively. Templates cover common workflows like persona lookup, simulation execution, and governance checking.

AGENTS.md Generation

The AGENTS.md Generator (AMG) produces human-readable documentation from persona definitions. This file follows community conventions for describing agent capabilities in a format that developers and AI assistants can easily consume.

An AGENTS.md file includes:

  • Agent identity and version
  • Capability summary with skill list
  • Input and output specifications
  • Constraint boundaries
  • Collaboration network
  • Getting started instructions

Generate AGENTS.md via the CLI:

fcc generate-docs --format agents-md --output AGENTS.md

EventBus Protocol Bridge

The Event Bridge Orchestrator (EBO) connects the internal EventBus to external protocol streams. This bridge enables:

  • Event forwarding: Internal FCC events are serialized and forwarded to external consumers via WebSocket or HTTP
  • Event filtering: Subscribers can filter by event type, persona, or workflow phase
  • Event replay: Historical events can be replayed for debugging or audit purposes
  • Backpressure handling: The bridge applies backpressure when consumers cannot keep up with event volume

The WebSocket Stream Manager (WSM) handles the transport layer, managing connections, reconnections, and message delivery guarantees.

Hands-on Lab: Generate Agent Cards

Objective

Generate A2A agent cards for all 107 personas and analyze the skill distribution across categories.

Steps

  1. Load the persona registry
  2. Convert each persona to an agent card
  3. Count skills per category
  4. Identify the categories with the most and fewest skills
  5. Generate a summary report
from fcc.personas.registry import PersonaRegistry
from collections import Counter, defaultdict

registry = PersonaRegistry.from_data_dir()
all_personas = list(registry)

# Generate cards
cards = []
for p in all_personas:
    card = {
        "agent_id": f"fcc-{p.id.lower()}",
        "name": p.name,
        "category": p.category,
        "skills": p.riscear.role_skills or [],
    }
    cards.append(card)

# Analyze skills by category
skills_by_category = defaultdict(int)
for card in cards:
    skills_by_category[card["category"]] += len(card["skills"])

print(f"Total cards: {len(cards)}")
print(f"Total skills: {sum(skills_by_category.values())}")
print(f"\nSkills by category:")
for cat, count in sorted(skills_by_category.items(),
                          key=lambda x: x[1], reverse=True):
    print(f"  {cat:<25} {count}")

Expected Output

You should see approximately 500-600 total skills distributed across all persona categories, with ML lifecycle and integration categories typically having the highest skill counts.

Summary and Next Steps

Protocol integration transforms FCC from a standalone framework into an interoperable platform that participates in broader agent ecosystems.

Key takeaways:

  1. A2A Agent Cards make persona capabilities discoverable by external agent platforms through standardized skill definitions
  2. MCP Tools and Resources expose FCC functionality to LLM hosts through structured tool schemas and fcc:// resource URIs
  3. AGENTS.md provides human-readable documentation following community conventions
  4. The EventBus Protocol Bridge enables real-time event streaming across protocol boundaries with filtering and replay
  5. Six protocol engineering personas manage the full integration lifecycle from design through compliance auditing

Next steps:

  • Chapter 16 covers JV Governance with dual-axis IP evaluation
  • Explore the Protocol Explorer Streamlit app for visual browsing
  • Review sample prompts in docs/tutorials/sample-prompts/protocol-engineering-prompts.md
  • Try Notebook 13 for hands-on protocol integration exercises