PHPackages                             sistemas-eel/agente-ia-client - 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. sistemas-eel/agente-ia-client

ActiveLibrary[Utility & Helpers](/categories/utility)

sistemas-eel/agente-ia-client
=============================

Cliente do Agente de IA para uso com o Agente de IA da EEL-USP

v0.1.0(1mo ago)05MITPHP ^7.4|^8.0

Since Jul 6Compare

[ Source](https://github.com/sistemas-eel/agente-ia-client)[ Packagist](https://packagist.org/packages/sistemas-eel/agente-ia-client)[ Docs](https://github.com/sistemas-eel/agente-ia-client)[ RSS](/packages/sistemas-eel-agente-ia-client/feed)WikiDiscussions Synced 1w ago

READMEChangelogDependencies (4)Versions (2)Used By (0)

Agente IA Client
================

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

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

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

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

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

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

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

```