Download the PHP package sistemas-eel/agente-ia-client without Composer

Agente IA Client

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:

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

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.

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

1. O endpoint recebe a chamada HTTP do Portal.
2. 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.
3. O pacote valida o envelope do payload.
4. O endpoint instancia o manipulador da ação no sistema.
5. AgenteActionExecutor executa o manipulador e normaliza a resposta.
6. O endpoint devolve JSON para o Portal.

Exemplo de uso em Laravel

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

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

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:

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

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:

Depois, no endpoint legado:

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:

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:

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:

Valide o pacote:

Execute os testes:

Licença

MIT.