# Design do Agente

**Design do Agente** é a entrega que permite compreender um agente e consultar, por expansão progressiva, os componentes que sustentam seu trabalho. O nome identifica o resultado entregue ao usuário. O mapa navegável é sua forma de representação; IPO organiza sua lógica.

## Compor pelo trabalho

Comece com nome, contribuição e três elementos: **Entradas → Agente → Entregas**. A primeira tela não abre listas de arquivos nem todas as informações de sustentação.

Ao expandir, revele grupos pertinentes. Skills abre nomes e funções, depois ocasião, insumos, transformação, saída e identificação. Pastas abre a árvore e o propósito, depois conteúdo relevante e localização. Rotinas/frentes ligam o que se faz aos recursos, participantes, resultado e continuidade. Outros grupos entram pela necessidade, sem formulário fixo.

A hierarquia organiza consulta; os vínculos entre componentes explicam o trabalho. Uma Skill pode servir a várias rotinas. Não copie o mesmo componente como se fossem objetos independentes; use sua identidade para reencontrá-lo.

Use fontes e componentes efetivos quando o objeto existir. Inventário pelo nome não comprova propósito. Leia o conteúdo que governa função, alcance e uso; conserve o que é observado, documentado, declarado ou proposto. Quando faltar uma contribuição necessária, preserve a lacuna e a parte que pode prosseguir. Cenário fictício conserva essa condição visível.

## Construir o modelo

O gerador recebe JSON de esquema `design-do-agente-1`. Consulte `examples/design-do-agente-trafego-financeiro.modelo.json` para a estrutura completa. Um único agente usa `casos` com um item e não gera seletor de comparação.

| Objeto | Conteúdo obrigatório |
| --- | --- |
| Raiz | `schema_version`, `titulo`, `versao`, `data`, `condicao`, `casos`. Use Design do Agente como título da entrega. |
| Caso/agente | `id`, `nome`, `contribuicao`, `entrada`, `trabalho`, `saida`, `condicao`, `fontes`, `groups`, `inputs`, `outputs`. As três frases curtas alimentam a visão geral. |
| Fonte do caso | `id`, `titulo`, `localizador`, `edicao`, `alcance`. Fonte pode ser documento, configuração, decisão ou descrição identificada do cenário. |
| Grupo | `id`, `nome`, `resumo`, `icone`, `itens`. A pergunta do trabalho governa quais grupos entram. |
| Componente/item | `id`, `nome`, `resumo`, `campos`, `links`. Campos é lista de pares [rótulo, conteúdo]. Links pode ser lista vazia. |
| Vínculo de consulta | `rotulo`, `area`, `grupo`, `item`. Aponta para componente existente, sem executar efeito externo. |

IDs usam letras minúsculas, números e hífen, começando por letra. Casos têm identidade própria; componentes são reconhecidos por área/grupo/id. `area` aceita `inputs`, `agent` ou `outputs`. Grupos de entradas e saídas são, respectivamente, `fontes` e `entregas`; os do agente são os IDs declarados em `groups`.

Ícones de grupo disponíveis: workflow, blocks, folder-tree, folder, plug, users, history, inbox, package-check, book-open. Esses identificadores selecionam os símbolos locais do pacote, sem biblioteca remota. Marcas seguem a referência de biblioteca quando forem necessárias ao desenho; símbolo de tipo não simula um logo.

O componente pode acrescentar `condicao` e `fontes` (IDs das fontes do caso). Sem esses campos, a condição e as fontes do caso sustentam a descrição geral. Com eles, a evidência daquele componente é específica. A consulta revela a proveniência sem colocá-la no primeiro plano da leitura.

## Dar conteúdo útil ao aprofundamento

Escolha campos pelo objeto. As seguintes composições orientam o julgamento:

- **Skill:** transformação/função, quando usar, entradas, saída, fontes e localização. Use nome de apresentação e preserve o identificador técnico. Versão e condição de instalação ficam no detalhe pertinente.
- **Pasta:** propósito, o que se encontra ou se guarda, subpastas/arquivos relevantes e sua relação com as fontes. Represente a estrutura real suficiente; a árvore proposta do exemplo não se impõe ao usuário.
- **Rotina/frente:** entrada, trabalho, resultado, início, responsabilidade, exceção e retomada. Aponte para os recursos correspondentes.
- **Sistema/conector:** objeto e operação de leitura/escrita, alcance e prova disponível. Se conteúdo fornecido bastar, não torne um conector obrigatório.
- **Entrega:** função gerencial, destinatário, modelo, destino e aceitação. Um nome de arquivo não basta para reconhecer a utilidade.
- **Responsabilidade:** contribuição e autoridade por operação material. Acesso, mandato e decisão recebida são condições distintas.

Campos são conteúdo de consulta, não novos nós de diagrama. Não converta cada frase em ramo. Preserve uma rota clara de volta ao conjunto e confirmação perceptível de onde a pessoa está.

O gerador verifica identidades e alvos de navegação. Ele não julga a pertinência de um vínculo declarado pelo autor nem prova que uma integração acontece. Leia cada passagem e confira seu fundamento antes de entregar.

## Produzir

A partir da pasta da Skill:

```bash
python3 scripts/gerar_design_do_agente.py modelo.json design-do-agente.html
```

Python 3.9+ e biblioteca padrão bastam. O programa usa template e símbolos locais, produz HTML autocontido e Markdown equivalente e recusa sobrescrita por padrão. `--substituir` atualiza derivados somente no alcance autorizado.

O HTML contém leitura completa e fontes já renderizadas, além do conteúdo de exploração. Sem JavaScript, essa leitura permanece acessível. O detalhe recolhível é nativo; o aprofundamento interativo também permite seguir vínculos e voltar à visão geral. A impressão pode usar a leitura completa. Não há CDN, API externa ou dependência do aplicativo da autoria para navegar.

A posição de exploração permanece em memória durante o uso; o ambiente hospedeiro pode oferecer estado adicional. Não prometa persistência entre sessões, atualização da pasta ou sincronização automática. O modelo é uma fotografia versionada.

## Conferir a entrega

Confronte o modelo com as fontes. Verifique se a pessoa consegue reconhecer a função do agente, localizar uma Skill adequada, encontrar a pasta pertinente, seguir uma rotina até a entrega e voltar à visão geral. Exposição de dados e operações externas não fazem parte de um clique de consulta.

Confira os alvos de navegação, campos, condições e fontes nos dois derivados. Observe teclado, foco, expansão/retração, retorno, telas e impressão quando o ambiente permitir. A leitura sem JavaScript precisa conservar a informação, não apenas os nomes. Diga separadamente código conferido, interface observada e compreensão confirmada.

Os exemplos de tráfego e financeiro são hipotéticos. A aprovação da apresentação pelo usuário não transforma seus recursos em instalados nem comprova operação ou resultado do trabalho.