Quickstart: Enterprise Deployment

Deploy the FCC Agent Team Framework in a production environment with governance gates, compliance pipelines, CI/CD integration, protocol servers, and observability.

You will need approximately 30 minutes.

---

Prerequisites

• Python 3.10 or later
• pip and venv
• Git installed
• Familiarity with CI/CD pipelines and production Python deployments
• Optional: Docker, Node.js 18+ (for the web frontend)

---

Step 1: Install with Full Dependencies

Install FCC with all optional extras for a production deployment:

pip install "fcc-agent-team-ext[notebooks,streamlit,search,knowledge,observability,dev]"

Or from source with the complete development setup:

git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext
make venv && source .venv/bin/activate
make install-dev

Verify the installation and run the full test suite:

fcc --version
make test

Expected output from fcc --version:

fcc, version 1.0.1

Tip: The full install includes OpenTelemetry, sentence-transformers, rdflib, Streamlit, and Jupyter. If you need a minimal production footprint, install only the extras you need: pip install "fcc-agent-team-ext[observability]"

---

Step 2: Configure Governance Gates

FCC ships with 30+ quality gates and a 3-tier constitution system. Configure them for your organization:

Load and Inspect Quality Gates

from fcc.governance.quality_gates import load_quality_gates
from fcc._resources import get_data_dir

data_dir = get_data_dir()
gates = load_quality_gates(str(data_dir / "governance" / "quality_gates.yaml"))

print(f"Total quality gates: {len(gates)}")
for gate in gates[:5]:
    print(f"  {gate.id}: {gate.name} [{gate.severity}]")

Expected output:

Total quality gates: 30
  schema_valid: Schema Validation [critical]
  persona_complete: Persona Completeness [critical]
  test_coverage: Test Coverage [warning]
  lint_clean: Lint Clean [warning]
  docs_generated: Documentation Generated [info]

Configure Constitution Tiers

Constitutions define behavioral guardrails at three levels:

Tier	Enforcement	Example
Hard-stop	Blocking	"Never generate executable code"
Mandatory	Required	"Always cite sources"
Preferred	Advisory	"Use formal language when possible"

from fcc.governance.constitution_registry import ConstitutionRegistry
from fcc.personas.registry import PersonaRegistry

registry = PersonaRegistry.from_package_data()
const_reg = ConstitutionRegistry.from_registry(registry)

# Inspect constitution for a specific persona
constitution = const_reg.get("research_catalyst")
print(f"Persona: {constitution.persona_id}")
print(f"  Hard-stop rules: {len(constitution.hard_stop)}")
print(f"  Mandatory rules: {len(constitution.mandatory)}")
print(f"  Preferred rules: {len(constitution.preferred)}")

Validate the Governance Layer

fcc validate
fcc dashboard quality

---

Step 3: Set Up the Compliance Pipeline

Run automated compliance audits against EU AI Act (256+ requirements) and NIST AI RMF (29 subcategories):

# Run dual-regulation audit
fcc compliance-audit --regulation BOTH --format yaml --output compliance/audit_report

Expected output:

EU AI Act:  248/256 passed (96.9%)
NIST AI RMF: 27/29 passed (93.1%)
Reports written to compliance/audit_report_eu.yaml and compliance/audit_report_nist.yaml

Integrate Compliance with the Event Bus

The compliance pipeline emits events for real-time monitoring:

from fcc.compliance.auditor import ComplianceAuditor
from fcc.compliance.classifier import AIActClassifier
from fcc.compliance.pipeline import CompliancePipeline
from fcc.compliance.requirements import RequirementRegistry
from fcc.governance.constitution_registry import ConstitutionRegistry
from fcc.messaging.bus import EventBus
from fcc.messaging.events import EventType
from fcc.personas.registry import PersonaRegistry
from fcc._resources import get_personas_dir

# Set up event bus for compliance events
bus = EventBus()

finding_count = 0
def on_finding(event):
    global finding_count
    finding_count += 1

bus.subscribe(EventType.COMPLIANCE_FINDING_RAISED, on_finding)

# Build the compliance pipeline
registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
const_reg = ConstitutionRegistry.from_registry(registry)
classifier = AIActClassifier(const_reg)
reqs = RequirementRegistry.default_eu_ai_act()
auditor = ComplianceAuditor(reqs, classifier, const_reg)

pipeline = CompliancePipeline(auditor=auditor, event_bus=bus)
result = pipeline.run(registry)

print(f"Compliance rate: {result.report.compliance_rate:.1%}")
print(f"Findings raised: {result.findings_raised}")
print(f"Duration: {result.duration_ms:.0f}ms")

View on the Compliance Dashboard

fcc dashboard audit
fcc dashboard compliance

---

Step 4: Integrate with CI/CD

GitHub Actions

Add FCC validation, benchmarks, and compliance to your pipeline:

# .github/workflows/fcc-pipeline.yml
name: FCC Pipeline
on: [push, pull_request]

jobs:
  validate-and-benchmark:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install FCC
        run: pip install -e ".[dev,observability]"

      - name: Run tests
        run: make test

      - name: Lint
        run: make lint

      - name: Validate personas
        run: fcc validate

      - name: Run CLEAR+ benchmarks
        run: fcc benchmark run --suite baseline --output benchmark_results.yaml

      - name: Run compliance audit
        run: |
          fcc compliance-audit --regulation BOTH \
            --format yaml \
            --output compliance_report

      - name: Generate model cards
        run: fcc model-card generate --all --output model-cards/

      - name: Generate documentation
        run: |
          fcc generate-docs --dir generated-docs
          fcc validate-docs --dir generated-docs

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: fcc-artifacts
          path: |
            benchmark_results.yaml
            compliance_report_eu.yaml
            compliance_report_nist.yaml
            model-cards/
            generated-docs/

Pre-Commit Hooks

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: fcc-validate
        name: FCC Persona Validation
        entry: fcc validate
        language: python
        pass_filenames: false
        types: [yaml]

      - id: fcc-compliance
        name: FCC Compliance Check
        entry: fcc compliance-check
        language: python
        pass_filenames: false
        always_run: true

---

Step 5: Develop Organization-Specific Plugins

FCC supports 10 plugin types. Scaffold a new plugin for your organization:

fcc init-plugin --name acme-fcc-personas --type personas

Expected output:

Initialized FCC plugin 'acme-fcc-personas' at ./acme-fcc-personas
  Type: fcc.plugins.personas

Next steps:
  cd acme-fcc-personas
  pip install -e .
  fcc plugins list  # verify your plugin is discovered

Plugin Directory Structure

acme-fcc-personas/
  pyproject.toml          # Entry point: fcc.plugins.personas
  src/
    acme_fcc_personas/
      __init__.py
      personas/
        analyst.yaml      # Custom persona definitions
        reviewer.yaml
      plugin.py           # Plugin registration

Register Custom Personas via Plugin

# src/acme_fcc_personas/plugin.py
from fcc.plugins.base import PluginMeta, PluginType

PLUGIN_META = PluginMeta(
    id="acme-personas",
    name="ACME Custom Personas",
    version="1.0.0",
    plugin_type=PluginType.PERSONAS,
    description="ACME Corp domain-specific personas",
    author="ACME Engineering",
)

Verify plugin discovery:

pip install -e ./acme-fcc-personas
fcc plugins list
fcc plugins validate

Expected output:

Discovered 1 plugin(s), loaded 1:
  acme-personas v1.0.0 [personas]
    ACME Corp domain-specific personas

---

Step 6: Set Up MCP Server for IDE Integration

The Model Context Protocol (MCP) server exposes FCC tools, resources, and prompts to IDE extensions (VS Code, Cursor, Claude Desktop):

# Start MCP server in stdio mode
fcc protocol mcp-server

Expected output:

Starting FCC MCP server (SDK mode)...
  Tools: 12
  Resources: 8
  Prompts: 5

For environments without the MCP SDK, use the fallback JSON-RPC mode:

fcc protocol mcp-server --fallback

Configure in Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "fcc": {
      "command": "fcc",
      "args": ["protocol", "mcp-server"]
    }
  }
}

---

Step 7: Generate A2A Agent Cards

Agent-to-Agent (A2A) cards enable service discovery between FCC personas and external agent systems:

# Generate cards for all 102 personas
fcc protocol a2a-cards --output agent-cards/

Expected output:

Generated 102 Agent Cards in agent-cards/

Generate the consolidated AGENTS.md file:

fcc protocol agents-md --output AGENTS.md

Generate a card for a single persona:

fcc protocol a2a-cards --persona research_catalyst --output agent-cards/

---

Step 8: Configure Observability

Basic Tracing (No External Dependencies)

from fcc.observability.tracing import FccTracer
from fcc.observability.exporters import JsonFileSpanExporter, ConsoleSpanExporter

# Create tracer with exporters
tracer = FccTracer()
tracer.add_exporter(ConsoleSpanExporter())  # Print to stdout
tracer.add_exporter(JsonFileSpanExporter(output_dir="./traces"))  # Write JSON files

# Use in simulations
with tracer.start_span("simulation.run") as span:
    span.set_attribute("scenario_id", "GEN-001")
    span.set_attribute("mode", "mock")

    # Nested spans for detailed tracing
    with tracer.start_span("workflow.traverse") as child:
        child.set_attribute("steps", 5)
        # ... simulation logic ...

Metrics Collection

from fcc.observability.metrics import FccMetrics

metrics = FccMetrics()

# Record operational metrics
metrics.record("simulation.runs", 1)
metrics.record("simulation.duration_ms", 450)
metrics.record("personas.loaded", 102)
metrics.record("compliance.checks_passed", 248)
metrics.record("benchmark.suites_run", 1)

# Export for monitoring
for name, values in metrics.all().items():
    print(f"fcc_{name}_total {sum(values)}")
    print(f"fcc_{name}_count {len(values)}")

Instrument Engines

Use the integration helpers to attach observability to simulation and action engines:

from fcc.observability.integration import (
    instrument_simulation_engine,
    instrument_action_engine,
)
from fcc.observability.tracing import FccTracer
from fcc.observability.metrics import FccMetrics
from fcc.messaging.bus import EventBus
from fcc.simulation.engine import SimulationEngine
from fcc.personas.registry import PersonaRegistry

tracer = FccTracer()
metrics = FccMetrics()
bus = EventBus()

registry = PersonaRegistry.from_package_data()
engine = SimulationEngine(registry=registry, mode="mock")

# Attach observability
instrument_simulation_engine(
    engine,
    tracer=tracer,
    metrics=metrics,
    event_bus=bus,
)

# Now all simulation runs emit spans, metrics, and events

OpenTelemetry Integration (Optional)

For production monitoring with Jaeger, Datadog, or Grafana:

pip install "fcc-agent-team-ext[observability]"

from fcc.observability.tracing import FccTracer
from fcc.observability.exporters import JsonFileSpanExporter

tracer = FccTracer()
tracer.add_exporter(JsonFileSpanExporter(output_dir="/var/log/fcc"))

# Spans are written as JSON files for collection by your
# observability pipeline (Fluentd, Filebeat, etc.)

---

Step 9: Environment Configuration

Configure FCC through environment variables for production deployments:

# .env file (loaded via python-dotenv)

# AI provider keys (only needed for non-mock mode)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# Observability
FCC_TRACE_EXPORTER=json
FCC_TRACE_OUTPUT_DIR=/var/log/fcc
FCC_OTEL_ENDPOINT=http://otel-collector:4317

# Federation
FCC_FEDERATION_NAMESPACE=org.yourcompany.fcc

from dotenv import load_dotenv
load_dotenv()

Warning: Never commit .env files or API keys to version control. Add .env to your .gitignore and use secrets management in CI/CD.

---

Step 10: Knowledge Graph Export for Enterprise Systems

Export the FCC knowledge graph for integration with graph databases:

# Export to RDF (Turtle) for Apache Jena or Stardog
fcc knowledge export --format turtle --output fcc_ontology.ttl

# Export to JSON-LD for Neo4j import
fcc knowledge export --format jsonld --output fcc_ontology.jsonld

View federation status across namespaces:

fcc knowledge federation --projects paom,aome,constel
fcc ecosystem health

---

Step 11: Forward Events to External Systems

Integrate the FCC event bus with your existing event infrastructure:

from fcc.messaging.bus import EventBus
from fcc.messaging.events import EventType
from fcc.messaging.serialization import EventSerializer

bus = EventBus()
serializer = EventSerializer()

# Forward all events to your message queue
def forward_to_queue(event):
    """Forward FCC events to your infrastructure."""
    payload = serializer.serialize(event)
    # Example: kafka_producer.send("fcc-events", payload)
    # Example: sqs_client.send_message(QueueUrl=url, MessageBody=payload)
    print(f"  -> {event.event_type.value}: forwarded")

bus.subscribe_all(forward_to_queue)

# Subscribe to specific event types for targeted routing
def on_compliance_finding(event):
    """Alert on compliance findings."""
    # Example: pagerduty_client.trigger(event.payload)
    print(f"  ALERT: compliance finding raised")

bus.subscribe(EventType.COMPLIANCE_FINDING_RAISED, on_compliance_finding)

---

Quick Reference: CLI Commands for Operations

Task	Command
Validate project structure	fcc validate
Run simulation	fcc simulate --scenario GEN-001
Generate documentation	fcc generate-docs --dir docs_output
Validate documentation	fcc validate-docs --dir docs_output
Run CLEAR+ benchmarks	fcc benchmark run --suite baseline
Compare benchmarks	fcc benchmark compare base.yaml candidate.yaml
Generate model cards	fcc model-card generate --all
Run compliance audit	fcc compliance-audit --regulation BOTH
Start MCP server	fcc protocol mcp-server
Generate A2A agent cards	fcc protocol a2a-cards --output cards/
Generate AGENTS.md	fcc protocol agents-md
List plugins	fcc plugins list
Validate plugins	fcc plugins validate
Scaffold a plugin	fcc init-plugin --name my-plugin --type personas
Export knowledge graph	fcc knowledge export --format turtle -o kg.ttl
View persona dashboard	fcc dashboard personas
View compliance dashboard	fcc dashboard compliance
View ecosystem health	fcc ecosystem health
Search personas semantically	fcc search personas -q "data governance"

---

What's Next

You have deployed FCC with governance, compliance, CI/CD integration, protocol servers, plugins, and observability. Here are deeper resources:

• Enterprise architecture: See Enterprise Deployment for scaling patterns, multi-team deployment, and high-availability considerations.
• CI/CD deep dive: See Integration Guide for GitLab CI, pre-commit hooks, and documentation platform integration.
• Governance and compliance: See Governance and Compliance for constitution authoring and quality gate customization.
• AI compliance: See AI Compliance for EU AI Act Article-by-Article analysis and NIST AI RMF crosswalk.
• Guidebook: Work through the FCC Guidebook (20 chapters) for comprehensive framework coverage.
• Book series: Read Building with FCC (Book 2) Ch. 8 for production deployment patterns and Advanced FCC (Book 3) Ch. 8 for enterprise scaling.
• Learning paths: Follow the Practitioner Path for a structured 16+ hour progression through all production topics.