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 introspecção 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 o endpoint de introspecção:

use SistemasEel\AgenteIaClient\Agente\TokenValidator;

$validator = new TokenValidator([
    'introspection_endpoint' => getenv('AGENTE_INTROSPECTION_ENDPOINT'),
    'client_id' => getenv('AGENTE_CLIENT_ID'),
    'client_secret' => getenv('AGENTE_CLIENT_SECRET'),
    'required_scopes' => ['agente:executar'],
]);

Campos aceitos na configuração:

• introspection_endpoint: URL de introspecção do token.
• 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 introspecção; por padrão, 5.0.

Fluxo recomendado

1. O endpoint recebe a chamada HTTP do Portal.
2. O pacote autentica o token técnico e valida o envelope do payload.
3. O endpoint instancia o manipulador da ação no sistema.
4. AgenteActionExecutor executa o manipulador e normaliza a resposta.
5. 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_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.

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, a autenticação e a validação ficam centralizadas em AgenteEndpointFactory, e a execução da ação fica com AgenteActionExecutor. 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.

$requestId = agente_guard_http_request();

$response = agente_execute_handler($handler, [
    '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'],
    'schema' => [
        ['chave' => 'termo', 'tipo' => 'string', 'obrigatorio' => false],
    ],
    '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.