Skip to content

Integration Guide

How to integrate the FCC Agent Team Framework with CI/CD pipelines, observability platforms, and existing enterprise toolchains.

CI/CD Integration

GitHub Actions

Add FCC validation and doc generation to your CI/CD pipeline:

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

jobs:
  validate:
    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]"

      - name: Run tests
        run: make test

      - name: Lint
        run: make lint

      - name: Validate personas
        run: fcc validate

      - name: Generate docs
        run: fcc generate-docs --output-dir ./generated-docs

      - name: Validate docs
        run: fcc validate-docs --input-dir ./generated-docs

      - name: Upload docs artifact
        uses: actions/upload-artifact@v4
        with:
          name: generated-docs
          path: ./generated-docs/

GitLab CI

# .gitlab-ci.yml
stages:
  - test
  - validate
  - docs

test:
  stage: test
  script:
    - pip install -e ".[dev]"
    - make test

validate:
  stage: validate
  script:
    - fcc validate
  needs: [test]

generate-docs:
  stage: docs
  script:
    - fcc generate-docs --output-dir ./generated-docs
    - fcc validate-docs --input-dir ./generated-docs
  artifacts:
    paths:
      - generated-docs/
  needs: [validate]

Pre-Commit Hooks

Add FCC validation as a pre-commit hook:

# .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]

Observability Integration

OpenTelemetry

FCC supports optional OpenTelemetry integration for production monitoring:

from fcc.observability.tracing import FccTracer
from fcc.observability.metrics import FccMetrics

# Basic setup (no OTel dependency required)
tracer = FccTracer()
metrics = FccMetrics()

# With OpenTelemetry (requires opentelemetry-api, opentelemetry-sdk)
from fcc.observability.exporters import OTelSpanExporter

tracer.add_exporter(OTelSpanExporter(
    endpoint="http://otel-collector:4317",
    service_name="fcc-framework",
))

Prometheus Metrics

Export FCC metrics to Prometheus-compatible format:

from fcc.observability.metrics import FccMetrics

metrics = FccMetrics()

# Record metrics during operation
metrics.record("simulation.runs", 1)
metrics.record("simulation.duration_ms", 450)
metrics.record("personas.loaded", 102)

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

Structured Logging

FCC traces can be exported as structured JSON logs:

from fcc.observability.exporters import JsonFileSpanExporter

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

# Spans are written as JSON files:
# /var/log/fcc/span_<trace_id>_<span_id>.json

Toolchain Integration

Knowledge Management Systems

Export FCC knowledge graphs to external graph databases:

from fcc.knowledge.serializers import JSONLDSerializer, RDFSerializer
from fcc.knowledge.builders import build_full_fcc_graph
from fcc.personas.registry import PersonaRegistry

registry = PersonaRegistry.from_package_data()
kg = build_full_fcc_graph(registry)

# Export to JSON-LD for Neo4j import
jsonld_serializer = JSONLDSerializer()
jsonld = jsonld_serializer.serialize(kg)

# Export to RDF for Apache Jena or Stardog
rdf_serializer = RDFSerializer()
rdf = rdf_serializer.serialize(kg, format="turtle")

Documentation Platforms

Integrate generated docs with documentation platforms:

# Generate docs in a format compatible with MkDocs
fcc generate-docs --output-dir ./docs/generated
fcc sitemap --output-dir ./docs/generated

# Build with MkDocs
mkdocs build

# Or with Sphinx
fcc generate-docs --output-dir ./docs/source/generated
sphinx-build docs/source docs/build

API Integration

Use the Protocol layer for integration with external services:

from fcc.protocols.a2a import A2AProtocol
from fcc.protocols.mcp import MCPProtocol
from fcc.protocols.bridge import ProtocolBridge

# Set up protocol bridge for external service communication
a2a = A2AProtocol()
mcp = MCPProtocol()
bridge = ProtocolBridge(protocols=[a2a, mcp])

Event Streaming

Forward FCC events to external event streaming platforms:

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

bus = EventBus()
serializer = EventSerializer()

def forward_to_kafka(event):
    """Forward events to Kafka (example)."""
    serialized = serializer.serialize(event)
    # kafka_producer.send("fcc-events", serialized)

bus.subscribe_all(forward_to_kafka)

Configuration Management

Environment Variables

FCC uses environment variables for configuration:

# AI provider keys
export ANTHROPIC_API_KEY="your-key"
export OPENAI_API_KEY="your-key"

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

# Federation
export FCC_FEDERATION_NAMESPACE="org.example.fcc"

Configuration File

Use .env files with python-dotenv:

# .env
ANTHROPIC_API_KEY=your-key
FCC_TRACE_EXPORTER=json
FCC_TRACE_OUTPUT_DIR=/var/log/fcc

from dotenv import load_dotenv
load_dotenv()

Testing Integration

Running FCC Tests in CI

# Full test suite
make test

# Specific test categories
pytest tests/personas/ -v        # Persona tests only
pytest tests/governance/ -v      # Governance tests only
pytest tests/messaging/ -v       # Event bus tests only

# With coverage report
pytest tests/ --cov=src/fcc --cov-report=html

Integration Test Pattern

def test_full_pipeline_integration():
    """Test the full FCC pipeline from scenario to knowledge graph."""
    from fcc.personas.registry import PersonaRegistry
    from fcc.simulation.engine import SimulationEngine
    from fcc.scenarios.loader import ScenarioLoader
    from fcc.knowledge.builders import build_full_fcc_graph

    registry = PersonaRegistry.from_package_data()
    scenarios = ScenarioLoader.from_package_data()
    scenario = scenarios.get("basic_fcc_cycle")

    engine = SimulationEngine(registry=registry, mode="mock")
    trace = engine.run(scenario)

    assert len(trace.steps) > 0
    assert trace.duration_ms > 0

    kg = build_full_fcc_graph(registry)
    assert len(kg.nodes) > 0
    assert len(kg.edges) > 0