Architektur agentischer Systeme

Agentische Systeme sind mehr als ein LLM mit Editor-Zugang. Produktive Architekturen trennen Intent, Policy, Execution, Verification und Observability in klare Schichten mit harten Boundaries. Agenticode in Köln designt diese Stacks für PHP-Backends, API-Plattformen und Multi-Domain-Frontends – holistisch und betriebssicher.

Schichtenmodell: Von Intent bis Observability

Die Intent-Schicht nimmt menschliche Ziele entgegen und übersetzt sie in strukturierte Task-Graphen. Die Policy-Schicht (Cursor Rules, ADRs, PHPStan) definiert Grenzen. Die Execution-Schicht führt Agent-Loops und MCP-Tools aus. Verification aggregiert Test-, Lint- und Security-Ergebnisse. Observability korreliert alles über trace_id.

Jede Schicht kommuniziert nur über definierte Schnittstellen – kein Agent greift direkt auf die Produktionsdatenbank zu, sondern über MCP-Tools der Execution-Schicht. Kein Deploy ohne grüne Verification.

Dieses Modell skaliert von Solo-Gründer (alle Schichten in einem Repo) bis Enterprise (Orchestrator als eigener Service, MCP-Server-Cluster, zentrales Policy-Registry).

Layer-Boundary-Guard: erlaubte Aufrufe zwischen Architektur-Schichten.
<?php

declare(strict_types=1);

namespace App\Agentic\Architecture;

enum AgenticLayer: string
{
    case Intent = 'intent';
    case Policy = 'policy';
    case Execution = 'execution';
    case Verification = 'verification';
    case Observability = 'observability';
}

final class LayerBoundaryGuard
{
    public function assertAllowedCall(AgenticLayer $from, AgenticLayer $to): void
    {
        $allowed = [
            AgenticLayer::Intent->value => [AgenticLayer::Policy->value, AgenticLayer::Execution->value],
            AgenticLayer::Policy->value => [AgenticLayer::Execution->value],
            AgenticLayer::Execution->value => [AgenticLayer::Verification->value, AgenticLayer::Observability->value],
            AgenticLayer::Verification->value => [AgenticLayer::Observability->value, AgenticLayer::Intent->value],
        ];

        if (!in_array($to->value, $allowed[$from->value] ?? [], true)) {
            throw new \LogicException("Layer violation: {$from->value} → {$to->value}");
        }
    }
}

Bounded Contexts und Failure Isolation

Agenten ohne Domain-Grenzen erzeugen Cross-Cutting-Chaos: ein Billing-Fix bricht Auth. Bounded Contexts begrenzen Agent-Scope physisch (Verzeichnisse) und logisch (Policies). Jeder Context hat eigene Tests, eigene MCP-Tools, eigene Deployment-Frequenz.

Failure Isolation bedeutet: Ein gescheiterter Agent-Run in Context A rollt nicht Context B zurück. Git-Branches, Feature Flags und modulare CI-Pipelines (nur betroffene Testsuite) implementieren das.

Agenticode kartiert bestehende Systeme auf Context-Maps und definiert Anti-Corruption-Layer zwischen Legacy und neuen agentisch gebauten Modulen – besonders relevant bei PHP-Monolithen mit jahrelanger Geschichte.

Context-Map: Pfade, Tools, CI und Deploy pro Bounded Context.
bounded_contexts:
  billing:
    paths: ["src/Billing/**", "tests/Billing/**"]
    mcp_tools: ["billing_get_invoice", "billing_create_draft"]
    ci_testsuite: Billing
    deploy: independent_canary

  auth:
    paths: ["src/Auth/**", "tests/Auth/**"]
    mcp_tools: ["auth_validate_token"]
    ci_testsuite: Auth
    deploy: shared_with_core

anti_corruption:
  legacy_user_table:
    adapter: App\Billing\LegacyUserIdAdapter
    context: billing

Observability und Betrieb

Ohne Observability sind Agent-Stacks Black Boxes. Agenticode instrumentiert: trace_id pro Run, strukturierte Logs (Phase, Iteration, Tool-Calls), Metriken (Token, Dauer, Erfolgsrate pro Agent-Rolle), und Artefakt-Storage (Diffs, Observe-JSON, ADRs).

Alerting fokussiert auf Anomalien: plötzlich hohe Iterationszahlen, wiederholte Policy-Verletzungen, steigende Post-Merge-Defect-Rate trotz grüner CI. Diese Signale triggern Policy-Reviews – nicht blindes Vertrauen in grüne Gates.

Betrieb bedeutet auch: Policy-Versionierung, Skill-Deprecation, MCP-Tool-Lifecycle. Agentische Systeme sind lebende Plattformen – Agenticode begleitet Kunden in Köln über den initialen Build hinaus mit Runbooks und Quarterly Architecture Reviews.

Run-Metadaten: Policy-Version, Agent-Rollen und Verification in einem Trace.
{
  "trace_id": "arch-audit-koeln-9b2c",
  "run_metadata": {
    "policy_version": "cursor-rules@1.4.2",
    "layers_touched": ["intent", "execution", "verification"],
    "agents": [
      { "role": "planner", "iterations": 1, "tokens": 4200 },
      { "role": "implementer", "iterations": 3, "tokens": 18500 },
      { "role": "tester", "iterations": 2, "tokens": 9100 }
    ]
  },
  "verification": {
    "phpunit": "pass",
    "phpstan": "pass",
    "diff_lines": 312
  },
  "observability_sink": "https://logs.internal/agentic/v1/events"
}