--- name: desenhar-agentes-e-sistemas description: >- Produz o Design do Agente: mapa navegável com visão inicial simples, expansão por níveis e consulta a rotinas, Skills, pastas, fontes e entregas. Também representa relações do agente no sistema, com percurso, fontes e leitura textual. metadata: version: "0.3.1" status: "experimental" --- # Desenhar agentes e sistemas Entregue um documento-mapa que ajude a pessoa a explicar como o trabalho acontece: o que sustenta o agente, como ele participa do conjunto e por onde uma entrega passa. O mapa mostra a organização funcional das contribuições; não descreve o mecanismo interno do modelo de linguagem. ## Compreender antes de desenhar Recupere pergunta, público, resultado, fronteira, fontes e edição do objeto. Leia a orientação, as capacidades, os meios e a condição do agente quando existirem. Um endereço ou nome de arquivo não demonstra conteúdo recebido; um desenho de operação não demonstra operação realizada. Preserve nomes e identidades existentes. Distinga, em cada componente **e em cada relação**, condição arquitetural e sustentação da afirmação. Duas peças documentadas não demonstram uma integração entre elas. Relate divergência material e lacuna; não preencha uma conexão por plausibilidade. Para uma proposta, comece pelo trabalho e explicite o que precisa ser provado. O acesso, a autoridade e o início da execução são condições distintas. Uma seta entre projetos não significa que um chama o outro: mostre conversa, intervenção humana, fila, consulta periódica ou mecanismo efetivamente demonstrado. ## Design do Agente **Design do Agente** é a entrega visual e navegável que permite compreender um agente e consultar os componentes que tornam seu trabalho realizável. Use o mesmo nome na apresentação ao usuário, no título da entrega e na orientação de uso. O identificador técnico desta Skill permanece `desenhar-agentes-e-sistemas`. Ao produzir essa entrega, leia [contrato e construção do Design do Agente](references/design-do-agente.md). Comece com contribuição e eixo **Entradas → Agente → Entregas**. Revele grupos conforme a pessoa expande e mantenha o detalhe recolhido até a consulta. Inclua nomes/funções das Skills e árvore/propósito das pastas efetivas. Para proposta, identifique o que ainda será preparado. Ligue unidades de trabalho aos recursos pertinentes: rotina/frente → Skill → fonte/pasta → entrega. Responsável, início, autoridade e condição de continuação entram quando mudam a passagem. O leitor deve chegar ao recurso que precisa, além de reconhecer uma categoria. Vínculo de navegação não aciona operação externa. Use o gerador específico com modelo versionado: ```bash python3 scripts/gerar_design_do_agente.py modelo.json design-do-agente.html ``` A saída é autocontida, sem dependência do aplicativo da autoria, CDN ou biblioteca externa; gera Markdown equivalente e leitura completa no próprio HTML para uso sem JavaScript. O template está em `assets/design-do-agente.html`. O exemplo `examples/design-do-agente-trafego-financeiro.modelo.json` mostra dois cenários hipotéticos e os vínculos entre componentes. Um mapa de um único agente usa o mesmo contrato e não apresenta seletor vazio. ## IPO e requisitos do agente entregue Quando o objeto for o agente que o Couto-IAS está entregando à pessoa, comece por [mapa mental pelo IPO](references/mapa-mental-ipo.md). Mostre o trabalho em conteúdo → transformação → resultado e os requisitos que o tornam realizável. É o IPO de operação desse agente; construir o agente é outro ciclo. Identifique fontes, pastas, possíveis entradas, saídas, modelos de entrega, conectores e operações necessárias. Dê a cada entrega função gerencial, destinatário, formato, destino e aceitação. A pessoa deve reconhecer o que precisa disponibilizar, o que precisa preparar e o que é expansão possível, com evidência própria para disponibilidade. Use [a biblioteca local](references/biblioteca-de-icones.md) para identificar sistemas e aplicativos pelo logo padrão e pelo nome. Ícone identifica plataforma; não demonstra acesso ou operação. Use símbolo de tipo com nome quando a marca não estiver na biblioteca; não invente logos. Os recursos viajam no pacote. O exemplo `examples/mapa-mental-do-agente.modelo.json` demonstra esse perfil, com percurso explícito por entrega. Pode ser usado como estrutura, sem converter sua composição ou aplicativos fictícios em requisito do usuário. Outros desenhos, como conjunto, fluxo e rotina, são possibilidades a definir conforme a pergunta; não são um catálogo obrigatório. ## Construir o modelo Para outras vistas de arquitetura, leia [modelo de dados e decisões de representação](references/modelo-de-dados.md). O Design do Agente segue o contrato específico acima. Crie o JSON antes do HTML e conserve os IDs entre vistas: - **Agente por dentro:** orientação, conhecimento e critérios, fontes do caso, transformações reutilizáveis, meios e continuidade, agrupados pelo papel que exercem. Explique o conteúdo que muda o julgamento, além do nome do arquivo. - **Agente no sistema:** pessoa, agente, destinatário, fontes ou registros compartilhados, ferramentas e entrega pertinentes. Contenção representa pertencimento; setas representam relações direcionais com verbo e objeto. - **Percurso de uma entrega:** etapas concretas com entrada, transformação, saída, mecanismo de início, limite e tratamento de exceção. Cada etapa aponta para uma vista e uma relação já modeladas. Trata-se de uma leitura explicativa; não impõe um roteiro fixo a toda demanda. Uma pergunta focal pode pedir uma única vista. Quando a pergunta incluir o agente no sistema, represente ambas as perspectivas com aprofundamento pertinente; não obrigue duas telas em todo Design do Agente. Mantenha de três a sete protagonistas por vista; abra outra vista quando rótulos e linhas competirem. Relações e fontes também precisam estar acessíveis em texto. Os exemplos em `examples/` são cenários fictícios de composição. Reutilize a forma, nunca os fatos como evidência da instalação do usuário. ## Outras representações de arquitetura Para vistas de relações, componentes ou percursos que peçam o traçado geométrico anterior, use o gerador de arquitetura, Python 3.9+ sem bibliotecas externas: ```bash python3 scripts/gerar_mapa.py /caminho/modelo.json /caminho/documento.html ``` Os caminhos acima são relativos à pasta desta Skill. A execução cria HTML offline e Markdown equivalente ao lado. Recusa entrada incoerente e sobrescrita; `--substituir` só se aplica aos derivados que a ordem permite atualizar. Edite o modelo ou o template e regenere, preservando a edição anterior quando necessária. O template em `assets/documento-mapa.html` oferece seleção coordenada por ID, detalhe imediato com fonte, fechamento/Escape com retorno de foco, vistas e etapas por teclado, leitura sem JavaScript e impressão. A base clara e azul diferencia foco; linha tracejada e estado escrito identificam proposta. Logos e símbolos locais podem ser incorporados; sem recursos remotos ou movimento contínuo. Se mídia real for indispensável, preserve origem, finalidade, texto alternativo e alternativa textual; esta versão não possui importador de capturas ou fotografias. Para usar ou entregar no Cowork, leia [uso no Cowork](references/uso-no-cowork.md). Se não houver execução de Python, produza o modelo e o documento textual e adapte o template com o HTML essencial já presente. Declare que o gerador não foi executado. Não peça à pessoa que programe para obter a entrega. Uma prévia PNG opcional do perfil geométrico anterior pode ser renderizada diretamente de seu modelo: ```bash python3 scripts/gerar_previa.py modelo.json previa.png --fonte /caminho/fonte.ttf ``` Esse comando requer ImageMagick já disponível; não instala componentes. O nome de fonte padrão é Arial e pode exigir caminho explícito no ambiente. A imagem não é captura do HTML e não prova cliques, responsividade ou foco. HTML/Markdown continuam sendo gerados só com Python. ## Conferir e concluir Antes de entregar: 1. Leia cada relação como frase e confira fonte, mecanismo, autoridade, destino e falha. Diferencie proposta, configuração documentada e execução observada. 2. Gere e examine HTML e texto: componentes, relações, fontes e etapas devem corresponder. No Design do Agente, confira também grupos, alvos de navegação, detalhe útil e volta à visão geral. Conteúdo essencial não pode depender de JavaScript. 3. Abra o HTML em tela ampla, intermediária e estreita. Selecione peças e etapas; confirme mudança no viewport, teclado, fechamento, foco, legibilidade e ausência de corte. Confira modo sem JavaScript, impressão e redução de movimento no alcance disponível. 4. Corrija o que encontrou. Entregue HTML, modelo JSON, equivalente Markdown e um recibo curto do que foi conferido por código, observado em navegador, confirmado pela pessoa e ainda não observado. A conferência automática não prova fidelidade, compreensão humana ou funcionamento do agente. Pare quando o documento responde à pergunta com evidência proporcional; uma eventual implantação ou publicação é outro efeito, com autorização e prova próprias.