PHPackages                             chen-zhanjie/hyperf-agentic - 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. [Utility & Helpers](/categories/utility)
4. /
5. chen-zhanjie/hyperf-agentic

ActiveHyperf-extension[Utility & Helpers](/categories/utility)

chen-zhanjie/hyperf-agentic
===========================

Hyperf-native AI Agent SDK — config-driven, Hermes-inspired

1.2.0(1mo ago)122MITPHPPHP >=8.1

Since Apr 15Pushed 1mo agoCompare

[ Source](https://github.com/chen-zhanjie/hyperf-agentic)[ Packagist](https://packagist.org/packages/chen-zhanjie/hyperf-agentic)[ RSS](/packages/chen-zhanjie-hyperf-agentic/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (6)Dependencies (5)Versions (20)Used By (0)

Hyperf Agentic SDK
==================

[](#hyperf-agentic-sdk)

[简体中文](README.zh-CN.md) | English

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

Installation
------------

[](#installation)

```
composer require chen-zhanjie/hyperf-agentic
```

Publish config files:

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

Quick Start
-----------

[](#quick-start)

### 1. Configure LLM Provider

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

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

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

[](#database-driven-agents-v040)

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
--------

[](#core-api)

MethodDescription`run(name, messages)`Execute a named agent`runStream(name, messages, onEvent)`Execute with SSE streaming`runWithConfig(config, messages, options)`Execute with dynamic config`runStreamWithConfig(config, messages, onEvent, options)`Dynamic config + streaming`chat(messages)`Pure LLM chat (no tools)`chatStream(messages, onChunk)`Pure LLM streaming`resume(sessionId)`Resume a suspended session`approveTool(tool, sessionId)`Approve a tool/pattern globally or per-session`approveAll(sessionId)`Approve all tools globally or per-session`revokeTool(tool, sessionId)`Revoke a tool approval`revokeAll(sessionId)`Revoke all approvalsDocumentation
-------------

[](#documentation)

DocumentDescription[Getting Started](docs/en/getting-started.md)Installation and quick start[Configuration](docs/en/configuration.md)Full configuration reference[API Reference](docs/en/api.md)Agentic facade method reference[Tools](docs/en/tools.md)Tool system: registration, custom tools, built-ins[Skills](docs/en/skills.md)3-level progressive disclosure skill system[Guardrails](docs/en/guardrails.md)Input/output safety checks[Conversations](docs/en/conversations.md)Multi-turn conversation persistence[Database Agents](docs/en/database-agents.md)Database-driven dynamic agent creation[Architecture](docs/en/architecture.md)5-layer architecture overview[Changelog](docs/en/changelog.md)Version history> 简体中文文档：[docs/zh-CN/](docs/zh-CN/)

Architecture
------------

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

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

[](#license)

MIT

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance90

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

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 ~0 days

Total

18

Last Release

51d ago

Major Versions

0.9.0 → 1.0.02026-04-19

### Community

Maintainers

![](https://www.gravatar.com/avatar/54d80b8f5777fc160194136359bae7cfc6396609678efce98f12e47faf5011ca?d=identicon)[chen-zhanjie](/maintainers/chen-zhanjie)

---

Top Contributors

[![chen-zhanjie](https://avatars.githubusercontent.com/u/80261118?v=4)](https://github.com/chen-zhanjie "chen-zhanjie (49 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/chen-zhanjie-hyperf-agentic/health.svg)

```
[![Health](https://phpackages.com/badges/chen-zhanjie-hyperf-agentic/health.svg)](https://phpackages.com/packages/chen-zhanjie-hyperf-agentic)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.6k38.2k](/packages/matomo-matomo)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

21764.8M1.6k](/packages/drupal-core)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.4M195](/packages/sulu-sulu)[friendsoftypo3/content-blocks

TYPO3 CMS Content Blocks - Content Types API | Define reusable components via YAML

101466.4k44](/packages/friendsoftypo3-content-blocks)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6941.5M395](/packages/drupal-core-recommended)[kimai/kimai

Kimai - Time Tracking

4.7k8.7k1](/packages/kimai-kimai)

PHPackages © 2026

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