php-agentic/docs/architecture.md

---
title: Architecture
description: Technical architecture of the core-agentic package
updated: 2026-01-29
---

# Architecture

The `core-agentic` package provides AI agent orchestration infrastructure for the Host UK platform. It enables multi-agent collaboration, persistent task tracking, and unified access to multiple AI providers.

## Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                        MCP Protocol Layer                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │ Plan     │ │ Phase    │ │ Session  │ │ State    │ ... tools │
│  │ Tools    │ │ Tools    │ │ Tools    │ │ Tools    │           │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘           │
└───────┼────────────┼────────────┼────────────┼──────────────────┘
        │            │            │            │
┌───────┴────────────┴────────────┴────────────┴──────────────────┐
│                      AgentToolRegistry                           │
│  - Tool registration and discovery                               │
│  - Permission checking (API key scopes)                          │
│  - Dependency validation                                         │
│  - Circuit breaker integration                                   │
└──────────────────────────────────────────────────────────────────┘
        │
┌───────┴──────────────────────────────────────────────────────────┐
│                         Core Services                             │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐     │
│  │ AgenticManager │  │ AgentApiKey    │  │ PlanTemplate   │     │
│  │ (AI Providers) │  │ Service        │  │ Service        │     │
│  └────────────────┘  └────────────────┘  └────────────────┘     │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐     │
│  │ IpRestriction  │  │ Content        │  │ AgentSession   │     │
│  │ Service        │  │ Service        │  │ Service        │     │
│  └────────────────┘  └────────────────┘  └────────────────┘     │
└──────────────────────────────────────────────────────────────────┘
        │
┌───────┴──────────────────────────────────────────────────────────┐
│                         Data Layer                                │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│
│  │ AgentPlan   │ │ AgentPhase  │ │ AgentSession│ │ AgentApiKey ││
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘│
│  ┌─────────────┐ ┌─────────────┐                                 │
│  │ Workspace   │ │ Task        │                                 │
│  │ State       │ │             │                                 │
│  └─────────────┘ └─────────────┘                                 │
└──────────────────────────────────────────────────────────────────┘
```

## Core Concepts

### Agent Plans

Plans represent structured work with phases, tasks, and progress tracking. They persist across agent sessions, enabling handoff between different AI models or instances.

```
AgentPlan
├── slug (unique identifier)
├── title
├── status (draft → active → completed/archived)
├── current_phase
└── phases[] (AgentPhase)
    ├── name
    ├── tasks[]
    │   ├── name
    │   └── status
    ├── dependencies[]
    └── checkpoints[]
```

**Lifecycle:**
1. Created via MCP tool or template
2. Activated to begin work
3. Phases started/completed in order
4. Plan auto-completes when all phases done
5. Archived for historical reference

### Agent Sessions

Sessions track individual work periods. They enable context recovery when an agent's context window resets or when handing off to another agent.

```
AgentSession
├── session_id (prefixed unique ID)
├── agent_type (opus/sonnet/haiku)
├── status (active/paused/completed/failed)
├── work_log[] (chronological actions)
├── artifacts[] (files created/modified)
├── context_summary (current state)
└── handoff_notes (for next agent)
```

**Handoff Flow:**
1. Session logs work as it progresses
2. Before context ends, agent calls `session_handoff`
3. Handoff notes capture summary, next steps, blockers
4. Next agent calls `session_resume` to continue
5. Resume session inherits context from previous

### Workspace State

Key-value state storage shared between sessions and plans. Enables agents to persist decisions, configurations, and intermediate results.

```
WorkspaceState
├── key (namespaced identifier)
├── value (any JSON-serialisable data)
├── type (json/markdown/code/reference)
└── category (for organisation)
```

## MCP Tool Architecture

All MCP tools extend the `AgentTool` base class which provides:

### Input Validation

```php
protected function requireString(array $args, string $key, ?int $maxLength = null): string
protected function optionalInt(array $args, string $key, ?int $default = null): ?int
protected function requireEnum(array $args, string $key, array $allowed): string
```

### Circuit Breaker Protection

```php
return $this->withCircuitBreaker('agentic', function () {
    // Database operations that could fail
    return AgentPlan::where('slug', $slug)->first();
}, fn () => $this->error('Service unavailable', 'circuit_open'));
```

### Dependency Declaration

```php
public function dependencies(): array
{
    return [
        ToolDependency::contextExists('workspace_id', 'Workspace required'),
        ToolDependency::toolCalled('session_start', 'Start session first'),
    ];
}
```

### Tool Categories

| Category | Tools | Purpose |
|----------|-------|---------|
| `plan` | plan_create, plan_get, plan_list, plan_update_status, plan_archive | Work plan management |
| `phase` | phase_get, phase_update_status, phase_add_checkpoint | Phase operations |
| `session` | session_start, session_end, session_log, session_handoff, session_resume, session_replay | Session tracking |
| `state` | state_get, state_set, state_list | Persistent state |
| `task` | task_update, task_toggle | Task completion |
| `template` | template_list, template_preview, template_create_plan | Plan templates |
| `content` | content_generate, content_batch_generate, content_brief_create | Content generation |

## AI Provider Abstraction

The `AgenticManager` provides unified access to multiple AI providers:

```php
$ai = app(AgenticManager::class);

// Use specific provider
$response = $ai->claude()->generate($system, $user);
$response = $ai->gemini()->generate($system, $user);
$response = $ai->openai()->generate($system, $user);

// Use by name (for configuration-driven selection)
$response = $ai->provider('gemini')->generate($system, $user);
```

### Provider Interface

All providers implement `AgenticProviderInterface`:

```php
interface AgenticProviderInterface
{
    public function generate(string $systemPrompt, string $userPrompt, array $config = []): AgenticResponse;
    public function stream(string $systemPrompt, string $userPrompt, array $config = []): Generator;
    public function name(): string;
    public function defaultModel(): string;
    public function isAvailable(): bool;
}
```

### Response Object

```php
class AgenticResponse
{
    public string $content;
    public string $model;
    public int $inputTokens;
    public int $outputTokens;
    public int $durationMs;
    public ?string $stopReason;
    public array $raw;

    public function estimateCost(): float;
}
```

## Authentication

### API Key Flow

```
Request → AgentApiAuth Middleware → AgentApiKeyService::authenticate()
                                            │
                                            ├── Validate key (SHA-256 hash lookup)
                                            ├── Check revoked/expired
                                            ├── Validate IP whitelist
                                            ├── Check permissions
                                            ├── Check rate limit
                                            └── Record usage
```

### Permission Model

```php
// Permission constants
AgentApiKey::PERM_PLANS_READ      // 'plans.read'
AgentApiKey::PERM_PLANS_WRITE     // 'plans.write'
AgentApiKey::PERM_SESSIONS_WRITE  // 'sessions.write'
// etc.

// Check permissions
$key->hasPermission('plans.write');
$key->hasAllPermissions(['plans.read', 'sessions.write']);
```

### IP Restrictions

API keys can optionally restrict access by IP:

- Individual IPv4/IPv6 addresses
- CIDR notation (e.g., `192.168.1.0/24`)
- Mixed whitelist

## Event-Driven Boot

The module uses the Core framework's event-driven lazy loading:

```php
class Boot extends ServiceProvider
{
    public static array $listens = [
        AdminPanelBooting::class => 'onAdminPanel',
        ConsoleBooting::class => 'onConsole',
        McpToolsRegistering::class => 'onMcpTools',
    ];
}
```

This ensures:
- Views only loaded when admin panel boots
- Commands only registered when console boots
- MCP tools only registered when MCP module initialises

## Multi-Tenancy

All data is workspace-scoped via the `BelongsToWorkspace` trait:

- Queries auto-scoped to current workspace
- Creates auto-assign workspace_id
- Cross-tenant queries throw `MissingWorkspaceContextException`

## File Structure

```
core-agentic/
├── Boot.php                    # Service provider with event handlers
├── config.php                  # Module configuration
├── Migrations/                 # Database schema
├── Models/                     # Eloquent models
│   ├── AgentPlan.php
│   ├── AgentPhase.php
│   ├── AgentSession.php
│   ├── AgentApiKey.php
│   └── WorkspaceState.php
├── Services/                   # Business logic
│   ├── AgenticManager.php      # AI provider orchestration
│   ├── AgentApiKeyService.php  # API key management
│   ├── IpRestrictionService.php
│   ├── PlanTemplateService.php
│   ├── ContentService.php
│   ├── ClaudeService.php
│   ├── GeminiService.php
│   └── OpenAIService.php
├── Mcp/
│   ├── Tools/Agent/            # MCP tool implementations
│   │   ├── AgentTool.php       # Base class
│   │   ├── Plan/
│   │   ├── Phase/
│   │   ├── Session/
│   │   ├── State/
│   │   └── ...
│   ├── Prompts/                # MCP prompt definitions
│   └── Servers/                # MCP server configurations
├── Middleware/
│   └── AgentApiAuth.php        # API authentication
├── Controllers/
│   └── ForAgentsController.php # Agent discovery endpoint
├── View/
│   ├── Blade/admin/            # Admin panel views
│   └── Modal/Admin/            # Livewire components
├── Jobs/                       # Queue jobs
├── Console/Commands/           # Artisan commands
└── Tests/                      # Pest test suites
```

## Dependencies

- `host-uk/core` - Event system, base classes
- `host-uk/core-tenant` - Workspace, BelongsToWorkspace trait
- `host-uk/core-mcp` - MCP infrastructure, CircuitBreaker