Este documento descreve os endpoints RESTful/JSON da plataforma USP AI Services, a autenticação, os contratos de entrada e saída estruturada dos agentes de IA e as instruções para consumo via código PHP ou integração externa.
- 1. Visão Geral e Autenticação
- 2. Endpoints da API
- 3. Agentes de IA e Uso em Código PHP
- 4. Tratamento de Erros e Códigos HTTP
Todos os serviços de IA oferecem tanto interface web interativa quanto respostas estruturadas em JSON. Para obter a resposta em formato JSON em qualquer rota, inclua o cabeçalho HTTP:
Accept: application/json- As rotas residem sob o grupo de middleware
authemroutes/web.php. - Requisições de navegador/SPA: Reutilizam a sessão autenticada (via Senha Única USP). Em requisições
POST, é obrigatório enviar o token CSRF (X-CSRF-TOKENno cabeçalho ou_tokenno corpo). - Limite de Entrada: Todas as entradas textuais dos serviços possuem validação com limite de até 10.000 caracteres (e 2.000 caracteres para campos contextuais adicionais).
Normaliza e ajusta referências de acordo com a norma acadêmica especificada, extraindo termos para busca no catálogo Dedalus/USP e notas explicativas.
- Método:
GET(informa os parâmetros aceitos quandoAccept: application/json) ouPOST(processamento). - Parâmetros no POST:
message(string, obrigatório, máx. 10.000 caracteres): uma ou mais referências a serem formatadas.standard(string, obrigatório): norma desejada. Valores válidos disponíveis emBibliografiaAgent::standards():ABNT NBR 6023:2025APA 7th editionVancouverNLMISO 690:2021
POST /bibliografia HTTP/1.1
Host: localhost:8000
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <token>
{
"standard": "ABNT NBR 6023:2025",
"message": "SILVA, J. Inteligência artificial na educação. São Paulo: USP, 2024."
}{
"success": true,
"data": {
"respostas": [
"SILVA, J. Inteligência artificial na educação. São Paulo: USP, 2024."
],
"explicacoes": [
"Referência ajustada conforme a norma ABNT NBR 6023:2025."
],
"confiancas": [
"alta"
],
"buscaDedalus": [
"Inteligência artificial na educação SILVA"
],
"entrada": "SILVA, J. Inteligência artificial na educação. São Paulo: USP, 2024.",
"norma": "ABNT NBR 6023:2025",
"estatisticas": {
"prompt_tokens": 420,
"completion_tokens": 85,
"total_tokens": 505,
"provider": "litellm",
"model": "gemini-flash",
"cached": false
}
}
}Consulta assíncrona ao catálogo Dedalus/ABCD da USP para localização de exemplares no acervo físico ou digital.
- Método:
GET - Query Parameters:
search(string, obrigatório): termo de busca gerado peloBibliografiaAgentou digitado pelo usuário.library(string, opcional): sigla da biblioteca USP (ex.:EESC,FFLCH,IME). Se omitido, utilizaconfig('services.dedalus.library').
GET /bibliografia/dedalus?search=Inteligência+artificial+na+educação+SILVA&library=EESC HTTP/1.1
Host: localhost:8000
Accept: application/json{
"success": true,
"data": {
"total": 1,
"url": "https://app.abcd.usp.br/WSearch.php?base=DEDALUS&busca=...",
"items": [
{
"sysno": "001234567",
"title": "Inteligência artificial na educação",
"author": "Silva, João",
"year": "2024"
}
]
}
}Avalia a qualidade e coerência de ementas acadêmicas em português e inglês, sugerindo versões revisadas e traduzindo trechos faltantes.
- Método:
GET(informa os campos esperados) ouPOST(processamento). - Parâmetros no POST:
mensagem(string, obrigatório, máx. 10.000 caracteres): texto integral da ementa (em português e/ou inglês).
POST /ementa HTTP/1.1
Host: localhost:8000
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <token>
{
"mensagem": "Disciplina de Computação Quântica. Objetivos: introduzir conceitos básicos de portas quânticas."
}{
"success": true,
"data": {
"resposta": {
"pt": "Disciplina de Computação Quântica. Objetivos: introduzir conceitos básicos de circuitos e portas quânticas.",
"en": "Quantum Computing Course. Objectives: introduce fundamental concepts of quantum circuits and gates."
},
"score": {
"pt": 8,
"en": 7
},
"explicacoes": {
"pt": "Ementa bem estruturada; sugerida expansão dos conceitos abordados.",
"en": "Translated and adapted into academic English."
},
"analiseIngles": "ausente",
"entrada": "Disciplina de Computação Quântica...",
"estatisticas": {
"prompt_tokens": 580,
"completion_tokens": 120,
"total_tokens": 700,
"provider": "litellm",
"model": "gemini-flash",
"cached": false
}
}
}Elabora textos acadêmicos e institucionais estruturados a partir de tópicos, ideias soltas ou rascunhos.
- Método:
GET(informa os campos esperados) ouPOST(processamento). - Parâmetros no POST:
rascunho(string, obrigatório, máx. 10.000 caracteres): tópicos, rascunho ou pontos-chave.style(string, opcional, padrão:'Automático'): estilo desejado. Opções válidas emTextoAgent::styles():Automático(identifica o formato ideal com base no conteúdo e sugere assunto)ComunicadoOfícioDespachoParecerE-mail InstitucionalTexto Acadêmico
contexto(string, opcional, máx. 2.000 caracteres): informações complementares, público-alvo ou diretrizes específicas.
POST /texto HTTP/1.1
Host: localhost:8000
Accept: application/json
Content-Type: application/json
X-CSRF-TOKEN: <token>
{
"rascunho": "Avisar os docentes do departamento que o prazo para entrega dos relatórios semestrais termina na próxima sexta-feira às 18h.",
"style": "Comunicado",
"contexto": "Departamento de Engenharia"
}{
"success": true,
"data": {
"resposta": "Prezados(as) Docentes,\n\nInformamos que o prazo para envio dos relatórios de atividades semestrais encerra-se impreterivelmente na próxima sexta-feira, às 18h00...\n\nAtenciosamente,\nChefia de Departamento",
"estiloUtilizado": "Comunicado",
"assunto": "Prazo final para envio dos relatórios de atividades semestrais",
"perguntas": [],
"entrada": "Avisar os docentes...",
"estilo": "Comunicado",
"contexto": "Departamento de Engenharia",
"estatisticas": {
"prompt_tokens": 490,
"completion_tokens": 140,
"total_tokens": 630,
"provider": "litellm",
"model": "gemini-flash",
"cached": false
}
}
}Os agentes residem em app/Ai/Agents/, herdam de Laravel\Ai\Agent e implementam Laravel\Ai\Contracts\HasStructuredOutput. Eles utilizam o schema JSON definido em código para garantir a tipagem estrita da resposta da IA.
- Construtor:
new BibliografiaAgent(string $standard) - Schema de saída:
referencias(array de strings): referências normalizadas.explicacoes(array de strings): justificativas e apontamentos sobre cada item.busca_dedalus(array de strings): termos sintéticos para busca no catálogo.confiancas(array de strings):'alta','media'ou'baixa'.
- Construtor:
new EmentaAgent() - Schema de saída:
score(objeto { pt: int, en: int }): pontuação de 0 a 10 para clareza e estrutura.explicacoes(objeto { pt: string, en: string }): parecer técnico detalhado.texto_revisado(objeto { pt: string, en: string }): texto aprimorado da ementa.status_ingles(string):'presente','parcial'ou'ausente'.
- Construtor:
new TextoAgent(string $style = 'Automático', ?string $context = null) - Schema de saída:
texto_elaborado(string): texto formal redigido.estilo_utilizado(string): estilo efetivamente aplicado.assunto(string): sugestão de assunto ou título do documento.perguntas_esclarecimento(array de strings): dúvidas ou lacunas identificadas no rascunho.
O AiService orquestra a chamada ao agente, lida com versionamento de prompts via banco (AiPrompt), consulta o cache configurado e coleta métricas de execução:
use App\Ai\Agents\BibliografiaAgent;
use App\Ai\Agents\EmentaAgent;
use App\Ai\Agents\TextoAgent;
use App\Services\AiService;
$service = app(AiService::class);
// 1. Normalização Bibliográfica
$resultadoBibliografia = $service->submit(
new BibliografiaAgent('ABNT NBR 6023:2025'),
$textoReferencias
);
// 2. Revisão de Ementa
$resultadoEmenta = $service->submit(
new EmentaAgent(),
$textoEmenta
);
// 3. Elaboração de Texto
$resultadoTexto = $service->submit(
new TextoAgent('Ofício', 'Público: Diretoria da Unidade'),
$rascunhoTexto
);Após cada chamada $service->submit(), o método $service->statistics() disponibiliza as métricas da operação:
$stats = $service->statistics();
/*
[
'prompt_tokens' => 520,
'completion_tokens' => 110,
'total_tokens' => 630,
'provider' => 'litellm',
'model' => 'gemini-flash',
'id' => 'chatcmpl-9x...',
'finish_reason' => 'stop',
'duration' => 1.45,
'cached' => false,
'cached_at' => null
]
*/Em acertos de cache (cached === true), a resposta é retornada instantaneamente da memória/storage e cached_at indica a data da geração original.
As respostas de erro JSON seguem um envelope uniforme:
{
"success": false,
"message": "Mensagem detalhada do erro ou falha."
}| Código | Nome | Causa |
|---|---|---|
| 401 | Unauthorized | Requisição sem autenticação (sessão ausente ou inválida). |
| 419 | Page Expired / CSRF Error | Token CSRF ausente ou inválido em requisições POST. |
| 422 | Unprocessable Content | Falha na validação de entrada (ex.: campo obrigatório ausente, texto excedendo 10.000 caracteres, norma não suportada). |
| 429 | Too Many Requests | Limite de taxa de requisições do gateway LiteLLM ou do provedor LLM atingido. |
| 502 | Bad Gateway | Provedor retornou resposta inválida, não estruturada de acordo com o schema, ou falha de inferência. |
| 503 | Service Unavailable | Gateway LiteLLM inacessível, falha de rede ou chaves de API não configuradas no .env. |
| 504 | Gateway Timeout | Tempo limite de execução (60 segundos) excedido pelo provedor LLM. |