README

A reusable, governed, tenant-safe Laravel 13 package for building business AI agents.

Overview

Ririkana Agent Framework provides the infrastructure layer for building production AI agents in Laravel. It handles governance, multi-tenancy, tool authorization, budgets, approvals, memory, and observability — freeing application developers to focus on domain-specific agent behavior.

Key principles:

• Multi-tenant by design — every agent run, tool call, and model request is tenant-scoped
• Governed, not gated — tools are classified by risk; high-risk operations require policy-based approval
• Provider-agnostic — agents reference logical model profiles, not hardcoded provider names
• Fully observable — every model call, tool execution, policy decision, and approval is audited
• Package-only — no frontend, no user model, no product business logic. Consuming apps provide those via contracts.

Installation

composer require ririkana/agent-framework

Publish the configuration:

php artisan vendor:publish --tag=ririkana-agent-config

Run the framework migrations:

php artisan ririkana-agent:install

Quick Start

1. Define an agent manifest

use Ririkana\AgentFramework\Domain\Agent\AgentKey;
use Ririkana\AgentFramework\Domain\Agent\AgentManifest;
use Ririkana\AgentFramework\Domain\Agent\AgentVersion;
use Ririkana\AgentFramework\Domain\Agent\ManifestStatus;

$manifest = AgentManifest::create(
    key: new AgentKey('customer-support'),
    version: new AgentVersion('1.0.0'),
    instructionProvider: 'You are a helpful customer support agent.',
    modelProfile: 'support-agent',
    toolPolicy: 'customer-tools',
    guardrailProfile: 'default',
    memoryPolicy: 'default',
    capabilities: ['text'],
    status: ManifestStatus::Published,
);

2. Register the agent

use Ririkana\AgentFramework\Contracts\AgentRegistry;

app(AgentRegistry::class)->register($manifest);

3. Register tools

use Ririkana\AgentFramework\Contracts\ToolRegistry;

// Implement GovernedTool interface on your tool
app(ToolRegistry::class)->register(new LookupCustomerTool);

4. Execute the agent

use Ririkana\AgentFramework\Contracts\AgentRuntime;
use Ririkana\AgentFramework\Domain\Context\ActorContext;
use Ririkana\AgentFramework\Domain\Context\ExecutionContext;
use Ririkana\AgentFramework\Domain\Context\TenantContext;
use Ririkana\AgentFramework\Domain\Context\TraceContext;

$context = new ExecutionContext(
    new TenantContext('customer-123'),
    new ActorContext('user-456', 'human'),
    'req-'.Str::uuid(),
    new TraceContext('00-'.bin2hex(random_bytes(16)).'-01'),
    'en',
    'web',
    new DateTimeImmutable,
);

$result = app(AgentRuntime::class)->execute(
    new AgentExecutionRequest($context, $manifest, 'Find order #9876')
);

echo $result->text;

Core Contracts

Contract	Purpose
AgentRuntime	Execute, stream, and queue agent runs
AgentRegistry	Register and query agent manifests
ToolRegistry	Register governed tools
ToolExecutor	Validate, authorize, and execute tool calls
PolicyEngine	Evaluate guardrail and policy decisions
ModelRouter	Select provider/model by capability and profile
BudgetLedger	Track and enforce usage budgets
ConversationStore	Store and retrieve conversation messages
ApprovalGateway	Request and resolve human approvals
AuditSink	Record audit events for every operation
KnowledgeRetriever	Retrieve evidence from RAG service
WorkflowOrchestrator	Dispatch n8n workflows
RunRepository	Persist agent runs with optimistic concurrency
ContextResolver	Resolve tenant/actor from HTTP request
ContextSerializer	Serialize/deserialize execution context

Capabilities

Text / Chat

The primary agent capability. Agents receive prompts, execute tools, and return text or structured output.

$result = app(AgentRuntime::class)->execute($request);
// Read text, structured output, usage, and finish reason

Sub-Agent Delegation

Parent agents can delegate tasks to child agents through an allowlisted delegation policy.

use Ririkana\AgentFramework\Contracts\AgentDelegator;
use Ririkana\AgentFramework\Domain\Delegation\DelegationPolicy;

$policy = new DelegationPolicy(allowlist: [
    'parent-agent' => ['child-agent-1', 'child-agent-2'],
], maxDepth: 3, maxDescendants: 10);

$delegator = app(AgentDelegator::class);
$result = $delegator->delegate(
    new AgentDelegationRequest('parent-run-id', 'parent-agent', 'child-agent-1', 'Analyze this document'),
    $context,
);

Image Generation

use Ririkana\AgentFramework\Contracts\ImageGenerator;
use Ririkana\AgentFramework\Domain\Media\ImageGenerationRequest;

$generator = app(ImageGenerator::class);
$result = $generator->generate(
    new ImageGenerationRequest(prompt: 'A futuristic city skyline', aspectRatio: 'landscape', quality: 'high'),
    $context,
);
// $result->storagePath, $result->mimeType, $result->checksum, etc.

Text-to-Speech

use Ririkana\AgentFramework\Contracts\SpeechSynthesizer;
use Ririkana\AgentFramework\Domain\Media\SpeechSynthesisRequest;

$synthesizer = app(SpeechSynthesizer::class);
$result = $synthesizer->synthesize(
    new SpeechSynthesisRequest(text: 'Your order has shipped', voiceId: 'nova'),
    $context,
);

Speech Transcription

use Ririkana\AgentFramework\Contracts\Transcriber;
use Ririkana\AgentFramework\Domain\Media\TranscriptionRequest;

$transcriber = app(Transcriber::class);
$result = $transcriber->transcribe(
    new TranscriptionRequest(sourcePath: 'meeting.mp3', diarization: true),
    $context,
);
echo $result->transcript;

Architecture

Contracts (interfaces)
    ↑
Domain (immutable value objects, pure business logic)
    ↑
Infrastructure (implementations: DB, HTTP, Laravel AI SDK)
    ↑
Http / Console (controllers, commands)

• Domain must not import Laravel AI SDK, Eloquent, HTTP, Redis, n8n, or product namespaces
• Infrastructure implements contracts
• Controllers and commands call contracts, not internal classes
• Consuming applications call public contracts and registrars

Configuration

All configuration lives in config/ririkana-agent.php. Key sections:

Section	Purpose
database	Connection and table prefix
persistence	Driver: memory (dev) or database (production)
runtime	Default runtime: fake or laravel-ai
openrouter	OpenRouter API key and default models
rag	Ririkana RAG service credentials
n8n	n8n workflow engine credentials
routes	Optional headless HTTP routes
limits	Tool result size and timeout defaults
budgets	Daily usage budget

Environment variables are documented in .env.example.

AI Provider Setup

The package works with any provider supported by Laravel AI SDK. OpenRouter is recommended — one API key covers text, image, TTS, and transcription.

OPENROUTER_API_KEY=sk-or-v1-your-key
AI_PROVIDER=openrouter

See docs/implementation/integrations/OPENROUTER-SETUP.md for detailed setup instructions.

Console Commands

php artisan ririkana-agent:install              # Install framework (migrations, config)
php artisan ririkana-agent:verify               # Verify core bindings resolve
php artisan ririkana-agent:doctor               # Check configuration health
php artisan ririkana-agent:publish-migrations   # Publish migration files
php artisan ririkana-agent:reconcile            # Reconcile stale runs
php artisan ririkana-agent:prune                # Prune expired data
php artisan ririkana-agent:conformance          # Run conformance suite

Testing

composer test                    # Run all tests (95 pass, 2 skip)
composer test:unit               # Unit tests
composer test:feature            # Feature tests
composer test:contract           # Contract tests
composer test:architecture       # Architecture layering tests
composer test:conformance        # Conformance tests
composer test:lint               # Pint code style
composer test:types              # PHPStan level 8

Architecture Decisions

The framework follows 24 Architecture Decision Records (ADRs) in docs/09-adrs/. Key decisions:

• ADR-0003: Laravel AI SDK isolated behind AgentRuntime
• ADR-0004: Logical model profiles, not hardcoded model names
• ADR-0005: Laravel remains business source of truth
• ADR-0007: n8n must not write directly to business tables
• ADR-0014: Every tool classified by risk and side effects
• ADR-0016: PostgreSQL as durable default, Redis as supporting
• ADR-0018: W3C Trace Context across boundaries

Full documentation at docs/.

Requirements

• PHP 8.5+
• Laravel 13.x
• PostgreSQL (production) or SQLite (development)
• Laravel AI SDK 0.8.x (optional, for live provider calls)

License

MIT License. See LICENSE for details.