README

Biblioteca PHP leve para execução de agentes de IA com suporte a tools e skills plugáveis, construída sobre o LLPhant.

Requisitos

PHP >= 8.1
Extensão curl
Composer

Instalação

composer require mftsoft/agent-runner

Configuração

Crie um arquivo .env na raiz do projeto com as variáveis necessárias:

OPENAI_API_KEY=sua-chave-aqui
OPENAI_API_URL=https://api.openai.com/v1/   # opcional
OPENAI_API_MODEL=gpt-4o-mini                # opcional

Uso básico

use MftSoft\AgentRunner\AgentRunner;

$runner = new AgentRunner();

$resposta = $runner->run('Qual é a capital do Brasil?');

echo $resposta;

Opções do construtor

$runner = new AgentRunner([
    'apiKey'        => 'sua-chave',
    'url'           => 'https://api.openai.com/v1/',
    'model'         => 'gpt-4o-mini',
    'systemPrompt'  => 'Você é um assistente especializado em finanças.',
    'temperature'   => 0.7,
    'maxIterations' => 10,
    'skillsPath'    => '/caminho/para/skills',
]);

Opção	Padrão	Descrição
`apiKey`	`OPENAI_API_KEY` do `.env`	Chave da API OpenAI (ou compatível)
`url`	`https://api.openai.com/v1/`	URL base da API
`model`	`gpt-4o-mini`	Modelo a ser utilizado
`systemPrompt`	Assistente genérico	Prompt de sistema base
`temperature`	`1.0`	Temperatura de geração
`maxIterations`	`20`	Limite de iterações do loop agêntico
`skillsPath`	`<raiz-do-projeto>/skills`	Caminho para o diretório de skills

Tools

Tools são classes de serviço que expõem métodos chamáveis pelo agente. Use ToolFactory::build() para registrá-las no runner.

Adicionando uma tool

use MftSoft\AgentRunner\AgentRunner;
use MftSoft\AgentRunner\ToolFactory;
use LLPhant\Chat\FunctionInfo\Parameter;

// Classe de serviço (ex: do AdiantFramework)
$calculadora = new CalculadoraService();

$runner = new AgentRunner();

$runner->addTool(
    ToolFactory::build(
        $calculadora,
        'calcular',
        'Realiza cálculos matemáticos a partir de uma expressão',
        new Parameter('expressao', 'string', 'A expressão matemática a calcular')
    )
);

$resposta = $runner->run('Quanto é 15% de 3.800?');

A classe de serviço deve expor o método com o mesmo nome informado:

class CalculadoraService
{
    public function calcular(string $expressao): string
    {
        // implementação
    }
}

Sem tools

O runner funciona normalmente sem nenhuma tool registrada — o agente responde apenas com o conhecimento do modelo.

Skills

Skills são capacidades documentadas em arquivos Markdown. O agente as lê sob demanda e decide quando utilizá-las com base na tarefa do usuário.

Estrutura de diretórios

skills/
├── consultar-estoque/
│   └── skill.md
├── gerar-relatorio/
│   └── skill.md
└── enviar-email/
    └── skill.md

Formato do skill.md

# Nome da Skill

## Objetivo
Descreva o que essa skill faz.

## Quando usar
Descreva os cenários em que essa skill deve ser aplicada.

## Como usar
Passo a passo ou instruções para o agente executar a skill.

O agente chama automaticamente a tool readSkill quando identifica que uma skill é relevante. A listagem das skills disponíveis é injetada no system prompt a cada sessão.

Caminho personalizado

$runner = new AgentRunner(['skillsPath' => '/var/app/skills']);

API

`AgentRunner`

// Envia uma mensagem e retorna a resposta final do agente
$runner->run(string $prompt): string

// Adiciona uma tool ao agente
$runner->addTool(FunctionInfo $tool): void

// Substitui o system prompt
$runner->setSystemPrompt(string $prompt): void

// Define o histórico de mensagens
$runner->setMessages(array|MessageCollection $messages): void

// Retorna o histórico de mensagens
$runner->getMessages(): array

// Limpa o histórico de mensagens
$runner->reset(): void

// Retorna a instância do chat (LLPhant)
$runner->getChat(): OpenAIChat

`ToolFactory`

// Constrói um FunctionInfo a partir de um objeto de serviço
ToolFactory::build(
    object $service,
    string $method,
    string $description,
    Parameter ...$parameters
): FunctionInfo

`SkillFactory`

// Define o caminho base das skills
SkillFactory::setSkillsPath(string $path): void

// Retorna o caminho base das skills
SkillFactory::getSkillsPath(): string

// Retorna a lista de skills disponíveis em formato Markdown
SkillFactory::listSkills(): string

// Constrói o FunctionInfo da tool readSkill (usado internamente pelo AgentRunner)
SkillFactory::build(): FunctionInfo

Compatibilidade com APIs OpenAI-compatíveis

O runner funciona com qualquer API compatível com o padrão OpenAI, como Ollama, Groq, OpenRouter, entre outras.

$runner = new AgentRunner([
    'url'   => 'http://localhost:11434/v1/',
    'model' => 'llama3',
]);

Licença

MIT — MFTSoft

mftsoft / agent-runner

Maintainers

Package info

Statistics

Security