Federated from workspace · PL-003 · zaixos-ai-platform/docs/WAVE_6_AGENT_RUNTIME.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

---

M-18 Wave 6 — Agent Runtime (PL-003)

Package: zaixos/ai-platform@0.6.0
Layer: packages/laravel/src/Application/Agents/ + Application/Tools/

Purpose

Wave 6 extracts reusable Agent Runtime machinery from PRD-001 into PL-003. Products register digital workers; the platform owns registration, discovery, permissions, capabilities, execution orchestration, health, and metadata.

This is not a workflow engine, LangChain clone, or autonomous AI framework.

Architecture

AgentRuntime (public façade)
  ├─ AgentRegistry / AgentResolver
  ├─ AgentLifecycleManager + AgentHealthManager
  ├─ AgentPermissionManager + AgentCapabilityManager
  └─ AgentInvocationPipeline
        ├─ ConversationEngine (Wave 5) — conversation-only path
        ├─ PromptEngine (Wave 4) — system prompt rendering
        ├─ AgentExecutor
        │     ├─ AiJobOrchestrator + AiJobProcessor (Wave 3)
        │     └─ ToolExecutionOrchestrator + ToolRegistry
        └─ ProviderGateway (Wave 2) — via job executor only

Execution pipeline

1. Resolve AgentDefinition by agentKey
2. Validate permissions (product-supplied permission strings)
3. Validate capabilities (provider, model, tools)
4. Build AgentContext (tenantId only — no clinicId)
5. Optional custom AiAgentContract handler delegation
6. Platform path:
   • Conversation path (no tools): ConversationEngine::sendMessage
   • Job path (tools or non-conversation): PromptEngine → AgentExecutor → jobs + tool rounds
7. Persist execution metadata via AgentExecutionStoreContract
8. Dispatch execution events

Registration

Products register agents at bootstrap:

$runtime->register(new RegisterAgentData(
    key: 'clinic-assistant',
    displayName: 'Clinic Assistant',
    description: 'Product-owned assistant shell',
    capability: new AgentCapability(
        supportedProviders: ['stub'],
        supportedModels: ['stub-default'],
        requiredPermissions: ['agents.run'],
        requiredTools: [],
        supportsConversation: true,
    ),
    defaultProviderKey: 'stub',
    defaultModelKey: 'stub-default',
    promptTemplateKey: 'system.default',
), tenantId: $tenantId);

Products may optionally bind a custom AiAgentContract handler class for business-specific orchestration while still using platform lifecycle and metadata.

Boundaries

Forbidden inside PL-003 agent layer:

• App\Modules, clinic identifiers, dental/CRM/finance domains
• Product assistant modules (ClinicAI, Operational Intelligence, Workflow)

Wave 7 readiness

Agent context includes memoryReferences and knowledgeReferences placeholders. Memory Runtime (Wave 7) will populate these without changing the agent pipeline contract.

Tests

• Architecture: tests/Architecture/AgentLayerTest.php
• Unit: packages/laravel/tests/Unit/AgentRuntimeTest.php, ToolExecutionOrchestratorTest.php