PHPackages                             ririkana/agent-framework - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. ririkana/agent-framework

ActiveLibrary[Framework](/categories/framework)

ririkana/agent-framework
========================

Reusable Laravel package for governed, tenant-safe AI agent execution.

v0.1.3(1mo ago)10MITPHPPHP ^8.5CI passing

Since Jul 7Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/Ririkana-Labs/ririkana-agent)[ Packagist](https://packagist.org/packages/ririkana/agent-framework)[ RSS](/packages/ririkana-agent-framework/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (10)Versions (4)Used By (0)

Ririkana Agent Framework
========================

[](#ririkana-agent-framework)

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

![Tests](https://camo.githubusercontent.com/e8018bdb9fb2808ec9e25ee9222da3d06971f328735a65a707083d982579dac8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d39352532307061737365642d627269676874677265656e)![Coverage](https://camo.githubusercontent.com/f8d5864a109addceb1ccb1590650904e26cc29043bed6cfbf0b009e3f4651330/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d37352532352d79656c6c6f77)![PHP](https://camo.githubusercontent.com/140267cec03492487ddf1b27d97eb73242fa0fff260b31930bd4daa764b2fbf6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e352d626c7565)![Laravel](https://camo.githubusercontent.com/49550df88f7739ee574d20768baf3f4786812de95a7baa4b313edc4d4a176d99/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d25354531332e302d726564)![License](https://camo.githubusercontent.com/b8cadaa967891081f8f165695470689986c028821dd8a040132f6e661795dc0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c7565)

Overview
--------

[](#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
------------

[](#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
-----------

[](#quick-start)

### 1. Define an agent manifest

[](#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

[](#2-register-the-agent)

```
use Ririkana\AgentFramework\Contracts\AgentRegistry;

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

### 3. Register tools

[](#3-register-tools)

```
use Ririkana\AgentFramework\Contracts\ToolRegistry;

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

### 4. Execute the agent

[](#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
--------------

[](#core-contracts)

ContractPurpose`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 contextCapabilities
------------

[](#capabilities)

### Text / Chat

[](#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

[](#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

[](#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

[](#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

[](#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
------------

[](#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
-------------

[](#configuration)

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

SectionPurpose`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 budgetEnvironment variables are documented in `.env.example`.

AI Provider Setup
-----------------

[](#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
----------------

[](#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
-------

[](#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
----------------------

[](#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
------------

[](#requirements)

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

License
-------

[](#license)

MIT License. See `LICENSE` for details.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance90

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

3

Last Release

49d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c3798ae23dea2e880c4625719e04818e5c002f8d117afa101c4582525e9fd128?d=identicon)[Joemuigai](/maintainers/Joemuigai)

---

Top Contributors

[![Joemuigai](https://avatars.githubusercontent.com/u/39778761?v=4)](https://github.com/Joemuigai "Joemuigai (12 commits)")

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ririkana-agent-framework/health.svg)

```
[![Health](https://phpackages.com/badges/ririkana-agent-framework/health.svg)](https://phpackages.com/packages/ririkana-agent-framework)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M354](/packages/psalm-plugin-laravel)[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.5k31.8M163](/packages/laravel-cashier)[laravel/ai

The official AI SDK for Laravel.

1.1k4.6M342](/packages/laravel-ai)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

80427.1M249](/packages/laravel-mcp)[api-platform/laravel

API Platform support for Laravel

58190.1k21](/packages/api-platform-laravel)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

265.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)