README

Cliente PHP para expor endpoints compatíveis com o Agente de IA da EEL-USP.

O pacote centraliza autenticação por token técnico, validação do payload recebido, validação de schema dos campos, execução de handlers de ação e normalização das respostas JSON.

Funciona com Laravel 8+ e PHP legado 7.4+.

Requisitos

PHP 7.4 ou superior.
Composer.
Acesso ao endpoint de introspection de tokens usado pelo Portal.
Laravel ^8.0|^9.0|^10.0|^11.0|^12.0|^13.0 para integração automática via service provider.

Instalação

Quando o pacote estiver disponível no Packagist, instale diretamente:

composer require sistemas-eel/agente-ia-client

Se o pacote for usado diretamente a partir do GitHub, declare o repositório VCS no composer.json do projeto consumidor:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "git@github.com:ORGANIZACAO/agente-ia-client.git"
        }
    ],
    "require": {
        "sistemas-eel/agente-ia-client": "^1.0"
    }
}

Configuração

O validador de token espera as credenciais e a URL de introspection do token.

Aqui, introspection significa a validação remota do token técnico enviado pelo Portal antes de o sistema executar a ação do agente.

use SistemasEel\AgenteIaClient\Agente\TokenValidator;

$validator = new TokenValidator([
    'introspection_endpoint' => getenv('AGENTE_INTROSPECTION_ENDPOINT'), // URL que confirma se o token recebido é válido e ativo
    'client_id' => getenv('AGENTE_CLIENT_ID'),
    'client_secret' => getenv('AGENTE_CLIENT_SECRET'),
    'required_scopes' => ['agente:executar'],
]);

Campos aceitos na configuração:

introspection_endpoint: URL usada para validar o token técnico enviado pelo Portal antes de executar a ação do agente.
client_id: identificador do cliente técnico.
client_secret: segredo do cliente técnico.
expected_client_id: cliente esperado no token; se omitido, usa client_id.
required_scopes: escopos obrigatórios; por padrão, agente:executar.
verify_ssl: ativa ou desativa validação SSL no Guzzle; por padrão, true.
timeout: timeout HTTP da introspection; por padrão, 5.0.
cache_ttl: TTL do cache da introspection, em segundos; por padrão, 60.
origem: origem esperada no payload; por padrão, agente_ia.
acao: ação esperada quando ela for global para o endpoint.
schema_version: versão do schema esperada; por padrão, 1.
payload_version: versão do payload esperada; por padrão, v2.
required_usuario: campos obrigatórios em usuario; por padrão, nome e codpes.
required_dados: campos obrigatórios em dados; por padrão, nenhum.

Fluxo recomendado

O endpoint recebe a chamada HTTP do Portal.
O pacote chama o endpoint de introspection para verificar se o token técnico recebido está ativo, pertence ao cliente esperado e tem os escopos exigidos.
O pacote valida o envelope do payload.
O endpoint instancia o manipulador da ação no sistema.
AgenteActionExecutor executa o manipulador e normaliza a resposta.
O endpoint devolve JSON para o Portal.

Exemplo de uso em Laravel

Publique o arquivo de configuração no projeto consumidor:

php artisan vendor:publish --tag=agente-ia-config

Isso cria config/agente-ia.php. Configure as credenciais no .env do projeto:

AGENTE_INTROSPECTION_ENDPOINT=https://...
AGENTE_CLIENT_ID=...
AGENTE_CLIENT_SECRET=...
AGENTE_CACHE_TTL=60
AGENTE_MODO_OPERACAO=preview

O exemplo Laravel deste repositório organiza a integração com rotas finas apontando para controllers. Isso é apenas um exemplo de uso recomendado, não uma estrutura obrigatória do pacote.

No Laravel, o pacote registra automaticamente:

AgenteEndpointFactory: autentica, valida schema e valida o envelope do payload.
LaravelAgenteEndpoint: helper para controllers que executa o handler e devolve JSON.
Cache de introspection usando o cache padrão do Laravel.

Exemplo de rotas:

use App\Http\Controllers\Agente\ConsultarDocumentosController;
use App\Http\Controllers\Agente\CriarSolicitacaoController;
use Illuminate\Support\Facades\Route;

Route::post('/agente/documentos/consultar', ConsultarDocumentosController::class);
Route::post('/agente/solicitacoes/criar', CriarSolicitacaoController::class);

Nos controllers de exemplo, LaravelAgenteEndpoint centraliza autenticação, validação, execução do handler e resposta JSON. Um controller de consulta pode ficar assim:

use App\Agente\ConsultarDocumentosHandler;
use Illuminate\Http\Request;
use SistemasEel\AgenteIaClient\Agente\Laravel\LaravelAgenteEndpoint;

class ConsultarDocumentosController
{
    public function __invoke(
        Request $request,
        LaravelAgenteEndpoint $endpoint,
        ConsultarDocumentosHandler $handler
    ) {
        return $endpoint->handle($request, $handler, [
            ['chave' => 'termo', 'tipo' => 'string', 'obrigatorio' => false],
            ['chave' => 'limite', 'tipo' => 'integer', 'obrigatorio' => false],
        ], 'consultar');
    }
}

A implementação completa está em:

examples/laravel/routes/api.php
examples/laravel/app/Http/Controllers/Agente/ConsultarDocumentosController.php
examples/laravel/app/Http/Controllers/Agente/CriarSolicitacaoController.php

Uso em PHP legado

O arquivo src/Legacy/agente.php é carregado pelo autoload do Composer e expõe helpers para endpoints legados.

No PHP legado, a própria aplicação costuma manter um arquivo local de configuração e repassar esse array para os helpers do pacote.

Exemplo de arquivo local config/agente-ia.php:

<?php

return [
    'introspection_endpoint' => getenv('AGENTE_INTROSPECTION_ENDPOINT') ?: '',
    'client_id' => getenv('AGENTE_CLIENT_ID') ?: '',
    'client_secret' => getenv('AGENTE_CLIENT_SECRET') ?: '',
    'required_scopes' => ['agente:executar'],
    'acao' => 'consultar',
    'schema_version' => 1,
    'payload_version' => 'v2',
    'required_usuario' => ['nome', 'codpes'],
    'required_dados' => [],
    'schema' => [
        ['chave' => 'termo', 'tipo' => 'string', 'obrigatorio' => false],
        ['chave' => 'limite', 'tipo' => 'integer', 'obrigatorio' => false],
    ],
];

Depois, no endpoint legado:

require __DIR__ . '/../vendor/autoload.php';

$config = require __DIR__ . '/../config/agente-ia.php';

$requestId = agente_guard_http_request();

$response = agente_execute_handler(
    $handler,
    array_merge($config, ['request_id' => $requestId]),
    $requestId
);

agente_emit_response($response, $requestId);

Handlers

Handlers devem implementar AgenteActionHandler ou estender uma das classes base:

ConsultaAgenteHandler: para ações de consulta.
GravacaoAgenteHandler: para ações de criação ou gravação com suporte a preview, persistência e idempotência.
MysqliGravacaoAgenteHandler: adaptador para PHP legado com mysqli.
LaravelGravacaoAgenteHandler: adaptador para Laravel.

Um handler retorna um array com os dados da resposta. O AgenteActionExecutor normaliza esse retorno para o formato:

[
    'status' => 200,
    'body' => [
        'protocolo' => 'DOCUMENTOS-CONSULTA',
        'resposta_direta' => 'Encontrei 2 documento(s).',
    ],
]

Também é possível usar AgenteResponse::successArray(), AgenteResponse::errorArray() e AgenteResponse::accepted() para montar respostas padronizadas.

Schema de campos

O SchemaValidator valida os campos em dados.campos.

Exemplo:

[
    ['chave' => 'termo', 'tipo' => 'string', 'obrigatorio' => false],
    ['chave' => 'limite', 'tipo' => 'integer', 'obrigatorio' => false],
    ['chave' => 'prioridade', 'tipo' => 'enum', 'obrigatorio' => false, 'opcoes' => ['baixa', 'media', 'alta']],
]

Tipos suportados incluem string, integer, float, boolean, array, object, enum e multi_enum.

Exemplos

Os exemplos usam nomes e tabelas fictícios. Em um sistema real, mantenha no manipulador da ação apenas a regra do domínio e deixe autenticação, validação, normalização de resposta e emissão JSON com o pacote.

examples/legacy/consulta-endpoint.php: consulta em PHP legado.
examples/legacy/gravacao-endpoint.php: criação em PHP legado usando mysqli.
examples/laravel/app/Agente/ConsultarDocumentosHandler.php: manipulador de consulta Laravel.
examples/laravel/app/Agente/CriarSolicitacaoHandler.php: manipulador de criação Laravel.
examples/laravel/app/Http/Controllers/Agente/ConsultarDocumentosController.php: controller de consulta.
examples/laravel/app/Http/Controllers/Agente/CriarSolicitacaoController.php: controller de criação.
examples/laravel/routes/api.php: rotas Laravel que consomem os handlers.

Desenvolvimento

Instale as dependências:

composer install

Valide o pacote:

composer validate --strict

Execute os testes:

vendor/bin/phpunit

Licença

MIT.

sistemas-eel / agente-ia-client

Maintainers

Package info

Statistics

Security