Agente de IA para Documentação Dinâmica de Integrações de API

Consolidar insumos de integrações de API (OpenAPI/Swagger, coleções Postman, descrições textuais, exemplos) em um modelo canônico único, pronto para geração de documentação.

1.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente é o ponto de partida do fluxo e deve ser acionado pelo envio de uma lista de fontes de verdade das integrações de API via API. Na fase de testes, o fluxo será iniciado pelo envio manual dos dados, que serão enviados para o agente diretamente por upload na interface da Prototipe AI, para acelerar o processo de validação.
• Tipo do input: O input inicial para o fluxo é uma lista de fontes de verdade, como URLs de OpenAPI, arquivos JSON/YAML, e coleções Postman.
• Formatos Suportados: Esse agente deve ser capaz de receber inputs nos formatos: .json, .yaml, .postman_collection.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 100.000 caracteres.

1.3.2 Especificação do Output

• Formato de output: O output deve ser um objeto JSON contendo o modelo canônico único, denominado normalized_spec.
• Exemplo de Estrutura de Output:

   {
    "service_name": "ExemploAPI",
    "version_detected": "1.0.0",
    "base_urls": ["https://api.exemplo.com"],
    "endpoints": [
      {
        "method": "GET",
        "path": "/endpoint",
        "summary": "Descrição do endpoint",
        "responses": {
          "200": {"description": "Sucesso", "schema": {"type": "object"}},
          "404": {"description": "Não encontrado", "schema": {"type": "object"}}
        }
      }
    ]
  }

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 10.000 caracteres.

1.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

1.3.4 Ferramentas do Agente

• Documentos: Não consulta documentos externos.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não se conecta a sistemas externos.

1.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente.
• Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Execução de Chamada à API (RF 2).

1.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Execução de Chamada à API (RF 2).

Realizar chamadas às fontes remotas de especificação e metadados de API para obter os artefatos mais recentes.

2.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 1).
• Tipo do input: Este agente deve ser apto a receber um retrieval_plan contendo URLs e headers necessários para as chamadas de API.
• Formatos Suportados: Esse agente deve ser capaz de processar inputs no formato: .json.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de até 10.000 caracteres.

2.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON contendo os payloads brutos recuperados das URLs informadas, com status HTTP e corpo por item.
• Exemplo de Estrutura de Output:

   {
    "raw_remote_specs": [
      {
        "url": "https://api.exemplo.com/spec",
        "status": 200,
        "body": {"openapi": "3.0.0", "info": {"title": "Exemplo API"}}
      }
    ]
  }

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 5.000 caracteres.

2.3.3 Parâmetros de Geração

• Modelo: Não se aplica (uso de ferramenta)
• Temperatura: Não se aplica

2.3.4 Ferramentas do Agente

• Documentos: Não consulta documentos externos.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: O agente deverá realizar chamadas HTTP GET nas URLs especificadas no retrieval_plan.

2.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente.
• Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Execução de Consulta a Documento (RF 3).

2.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Execução de Consulta a Documento (RF 3).

Recuperar a versão anteriormente publicada da documentação e/ou changelog para comparação.

3.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 2).
• Tipo do input: Este agente deve ser apto a receber um doc_repo_query com parâmetros para localização de documentos anteriores.
• Formatos Suportados: Esse agente deve ser capaz de processar inputs no formato: .json.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de até 5.000 caracteres.

3.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON contendo previous_docs_bundle: previous_doc_markdown (se existir), previous_spec_extract (se disponível), previous_changelog e metadata.
• Exemplo de Estrutura de Output:

   {
    "previous_docs_bundle": {
      "previous_doc_markdown": "# Documentação Anterior",
      "previous_spec_extract": {"openapi": "3.0.0"},
      "previous_changelog": "- Atualização menor",
      "metadata": {"data_publicacao": "2025-12-01", "version": "1.0.0"}
    }
  }

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 3.000 caracteres.

3.3.3 Parâmetros de Geração

• Modelo: Não se aplica (uso de ferramenta)
• Temperatura: Não se aplica

3.3.4 Ferramentas do Agente

• Documentos: O agente deve acessar repositórios de documentação para recuperar versões anteriores.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não se conecta a sistemas externos.

3.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente.
• Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Controle de Versões e Detecção de Mudanças (RF 4).

3.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Controle de Versões e Detecção de Mudanças (RF 4).

Comparar a especificação normalizada atual com a versão anterior e classificar mudanças, determinando bump semântico e sinalizações de impacto.

4.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 3).
• Tipo do input: Este agente deve ser apto a receber a especificação normalizada atual e a versão anterior da documentação.
• Formatos Suportados: Esse agente deve ser capaz de processar inputs no formato: .json.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de até 15.000 caracteres.

4.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON contendo change_analysis: change_set, breaking_changes, semver_bump, mudancas_detectadas, changelog_entries, e pronto_para_geracao.
• Exemplo de Estrutura de Output:

   {
    "change_analysis": {
      "change_set": {"added": [], "modified": [], "removed": []},
      "breaking_changes": false,
      "semver_bump": "minor",
      "mudancas_detectadas": true,
      "changelog_entries": [],
      "pronto_para_geracao": true
    }
  }

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 4.000 caracteres.

4.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

4.3.4 Ferramentas do Agente

• Documentos: Não consulta.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não utiliza.

4.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente.
• Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Geração de Documentação de API (RF 5).

4.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Geração de Documentação de API (RF 5).

Produzir documentação completa, clara e acessível em português, a partir da especificação normalizada e da análise de mudanças.

5.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 4).
• Tipo do input: Este agente deve ser apto a receber a especificação normalizada e a análise de mudanças.
• Formatos Suportados: Esse agente deve ser capaz de processar inputs no formato: .json.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de até 20.000 caracteres.

5.3.2 Especificação do Output

• Formato de output: O output deve ser um doc_draft com markdown principal estruturado, anexos de exemplos por endpoint, índice, seções de autenticação, paginação, limites, erros, webhooks, SDKs (se houver), além de doc_metadata e changelog atualizado.
• Exemplo de Estrutura de Output:

   {
    "doc_draft": "# Documentação de API\n## Visão Geral\nEsta API permite...",
    "doc_metadata": {
      "service_name": "ExemploAPI",
      "version_final": "1.0.1",
      "last_updated_iso": "2025-12-14T04:09:00Z",
      "owner": "Cheila Portela",
      "coverage_metrics": {
        "percent_endpoints_documentados": 100,
        "percent_endpoints_com_exemplo_sucesso": 100,
        "percent_endpoints_com_exemplo_erro": 100
      }
    },
    "changelog": "- docs: revisão sem alterações funcionais"
  }

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 10.000 caracteres.

5.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

5.3.4 Ferramentas do Agente

• Documentos: Não consulta.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não utiliza.

5.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente.
• Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Validação de Qualidade e Consistência (RF 6).

5.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Validação de Qualidade e Consistência (RF 6).

Auditar o rascunho de documentação para assegurar completude, consistência terminológica e qualidade dos exemplos, indicando se está pronto para publicação.

6.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 5).
• Tipo do input: Este agente deve ser apto a receber o doc_draft e a especificação normalizada para referência cruzada.
• Formatos Suportados: Esse agente deve ser capaz de processar inputs no formato: .json.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de até 25.000 caracteres.

6.3.2 Especificação do Output

• Formato de output: O output deve ser um quality_report contendo: scores, missing_items, inconsistencias, recomendacoes de ajuste e pronto_para_publicacao.
• Exemplo de Estrutura de Output:

   {
    "quality_report": {
      "scores": {"claridade": 90, "completude": 95, "consistência": 88},
      "missing_items": [],
      "inconsistencias": [],
      "recomendacoes": "Ajustar terminologia nos exemplos.",
      "pronto_para_publicacao": true
    }
  }

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 3.500 caracteres.

6.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

6.3.4 Ferramentas do Agente

• Documentos: Não consulta.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não utiliza.

6.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente.
• Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Atualização Contínua de Documentação (RF 7).

6.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Atualização Contínua de Documentação (RF 7).

Aplicar as atualizações na documentação final, versionar conforme análise de mudanças e registrar o histórico de alterações.

7.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 6).
• Tipo do input: Este agente deve ser apto a receber o doc_draft aprovado e o quality_report.
• Formatos Suportados: Esse agente deve ser capaz de processar inputs no formato: .json.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de até 30.000 caracteres.

7.3.2 Especificação do Output

• Formato de output: O output deve ser um doc_final pronto, changelog_final, publish_artifacts com índices/anchors atualizados, e flags: updated_sections[], no_update e version_publicada.
• Exemplo de Estrutura de Output:

   {
    "doc_final": "# Documentação de API Atualizada\n## Visão Geral\nEsta API permite...",
    "changelog_final": "- Atualização de versão para 1.0.2",
    "publish_artifacts": {"updated_sections": ["/payments POST"], "no_update": false, "version_publicada": "1.0.2"}
  }

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 8.000 caracteres.

7.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

7.3.4 Ferramentas do Agente

• Documentos: Não consulta.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não utiliza.

7.3.5 Memória

• Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente.
• Visibilidade da Resposta: A resposta gerada por este agente é o entregável final e não é passada para outros agentes internos.

7.3.6 Regras de Orquestração e Transição

A execução deste agente finaliza o fluxo. A documentação final gerada é o resultado que deve ser disponibilizado ao usuário.