README

简体中文 | English

A config-driven AI Agent SDK for Hyperf applications. Agent is a config, not a class.

Installation

composer require chen-zhanjie/hyperf-agentic

Publish config files:

php bin/hyperf.php vendor:publish chenzhanjie/hyperf-agentic

Quick Start

1. Configure LLM Provider

Edit config/autoload/agentic/providers.php:

return [
    'default' => 'openai',
    'providers' => [
        'openai' => [
            'protocol' => 'openai',
            'api_key'  => env('OPENAI_API_KEY'),
            'base_url' => 'https://api.openai.com/v1',
            'model'    => 'gpt-4o',
        ],
    ],
];

2. Define an Agent

Edit config/autoload/agentic/agents.php:

return [
    'general' => [
        'persona' => 'You are a helpful assistant.',
        'max_iterations' => 10,
    ],
];

3. Run the Agent

use ChenZhanjie\Agentic\Agentic;

$agentic = $this->container->get(Agentic::class);

$result = $agentic->run('general', [
    ['role' => 'user', 'content' => 'Hello!'],
]);

echo $result->content;

Database-Driven Agents (v0.4.0)

Create agents dynamically from database config:

use ChenZhanjie\Agentic\Persona\Persona;

$result = $agentic->runWithConfig(
    [
        'persona' => new Persona(name: 'Expert', content: 'You are an expert.'),
        'tools' => ['search'],
        'skills' => ['search-guide'],
        'max_iterations' => 15,
    ],
    [['role' => 'user', 'content' => 'Hello']],
    ['conversation_id' => 'conv-123'],  // auto history management
);

Core API

Documentation

简体中文文档：docs/zh-CN/

Architecture

Layer 5: Entry Points (Controller / Command / CLI)
    ↓
Layer 4: Agentic Facade (config-driven entry point)
    ↓
Layer 3: Agent Core (AgentRunner + ToolDispatcher + LoopState + GuardrailRunner + MiddlewarePipeline)
    ↓
Layer 2: Subsystems (ToolRegistry / PromptBuilder / LlmClient / SkillRegistry)
    ↓
Layer 1: Foundation (Contract/ — interfaces, zero upstream dependencies)

Testing

composer install
vendor/bin/phpunit

575 tests, 1146 assertions — all passing.

Note: Run vendor/bin/phpunit after install. Test count reflects latest version.

License

MIT