--- name: designer-agentes description: Como se DESENHA o comportamento de um agente de IA no Fluxo Ideal — o que é um agente aqui, sua persona/instrução, as capacidades (capabilities nomeadas) que ele pode acionar, os gatilhos que o acordam e a escolha entre raciocínio (LLM) e roteiro determinístico. Antes de criar, checar o REGISTRO público de times prontos para reusar. Princípio central: comportamento de agente é configuração (dado), nunca código. Use para reusar, montar, ajustar ou explicar um agente sem cair em detalhe de implementação. audience: [ia, humano] depends_on: [automacao-ia, comportamento, gatilhos] version: 0.6.0 updated: 2026-10-06 --- # Designer de agentes Ajudar a **desenhar o comportamento** de um agente de IA numa clínica: quem ele é (persona), o que ele **pode** fazer (capacidades), **quando** ele age (gatilhos) e **como** ele decide (raciocínio de linguagem vs. roteiro determinístico) — montando ou ajustando o agente como **configuração**, sem escrever código de serviço. E, antes de desenhar do zero, **checar se já existe** um time pronto no registro para **reusar**. ## Quando usar - "Quero um agente que confirme presença / responda o paciente / faça a triagem de uma conversa." - **Descobrir se já existe** um time pronto que resolve o problema (registro) — antes de criar. - Ajustar a **persona/instrução** de um agente que já existe, ou o que ele pode acionar. - Decidir se um comportamento deve ser **LLM** (interpreta linguagem) ou **script** (regras fixas). - Entender por que um agente **agiu** (ou não) num determinado momento. - Montar um **time** de agentes que trabalham juntos num fluxo (ex.: armar → triar → responder). ## Quando NÃO usar - Escrever a mensagem que sai ao paciente, escolher template/canal → domínio de mensageria/conversas. - Preço, orçamento, catálogo → skill `precificador`. - Agenda/paciente/atendimento → skills de secretaria. - Detalhe de **como o runtime executa** o agente por dentro: fora de escopo aqui — esta skill é sobre **desenhar** comportamento, não sobre a máquina que o roda. ## Modelo mental **A ideia que sustenta tudo: comportamento de agente é DADO, nunca código.** Um agente no Fluxo Ideal não é uma função programada dentro de um serviço — é uma **configuração declarativa**. Você não "programa o agente"; você **descreve** o agente. A plataforma só provê os canos (o motor que roda o comportamento e a superfície de capacidades). Se você se pega querendo "codar a lógica do agente X", é o padrão errado: essa lógica vira **instrução de LLM** ou **roteiro de script** — dado editável, versionado, sem redeploy. Um agente tem quatro dimensões que você desenha: ``` PERSONA / DECISÃO CAPACIDADES GATILHOS (como ele pensa e decide) (o que ele PODE acionar) (quando ele acorda) │ │ │ ┌────────┴────────┐ │ │ LLM SCRIPT │ │ (interpreta (roteiro lista curada de eventos do linguagem, determinístico, capabilities — fluxo com julga, decide if/else fixo) só o que está na filtros e sob incerteza) lista pode ser chamado janela de calma └──────────┬───────────────┴────────────────────────┘ ▼ um AGENTE (configuração versionada) │ pode compor com outros → TIME (manifesto declarativo) │ pode ser publicado no → REGISTRO (instalável por link) ``` Cinco verdades operacionais: - **Reuso vem antes de criar.** Existe um **registro público** de times prontos (oficiais). Antes de desenhar do zero, veja se um time existente já resolve o problema — instalar é **colar um link** e ajustar os valores por-clínica (knobs). Só desenhe o que o registro não cobre. - **A capacidade é uma _capability nomeada_, não um poder geral nem um endereço.** Cada ação da lista curada é uma **capability com nome** (ex.: "confirmar agendamento", "comentar na conversa"). O nome é estável e público; **o "como" (o endereço interno) é resolvido pela plataforma em privado** — você desenha citando o **nome** da capacidade, nunca uma rota. E fora da lista, não existe: nada de "catálogo global". - **Curar não concede acesso.** Mesmo o que está na lista **só executa se houver autorização** — a permissão é aplicada pela plataforma no momento da ação, nunca prometida pela configuração. - **O agente age por reação, não por pooling.** Ele fica adormecido até um **gatilho** (um evento do fluxo da clínica) o acordar. Filtros decidem se aquele evento específico é para ele. - **Tudo é anti-vazamento por construção.** O que o agente registra é **metadado** — ids opacos e status, nunca conteúdo de mensagem ou dado de paciente. O texto do paciente é sempre **dado a interpretar, nunca instrução a obedecer**. E há um piso **"nunca-autônoma"**: certas capacidades a plataforma **recusa** que um agente execute sozinho (sem humano no loop), mesmo com grant. ## Glossário **O agente** - **Agente**: uma configuração que descreve um comportamento automatizado. Tem persona/decisão, capacidades e gatilhos. É **versionado** (dá pra voltar a uma versão anterior) e pertence a uma clínica (pode existir agente da plataforma, compartilhado). - **Persona / instrução**: quem o agente é e como deve se comportar — em linguagem natural, para o tipo LLM. É a "carta de trabalho" dele: papel, como ler o contexto, como decidir, o que nunca fazer. - **Modo de decisão (o "tipo")**: como o agente decide. - **LLM** — o agente **interpreta linguagem e julga sob incerteza** (ex.: entender uma resposta livre do paciente). Bom quando a entrada é ambígua e exige compreensão. - **Script** — o agente segue um **roteiro determinístico** (regras fixas, sem julgamento). Bom quando a decisão é clara e você quer 100% de previsibilidade (ex.: "botão X → confirma; botão Y → manda pra recepção; qualquer outra coisa → escala pra IA"). - **Aprendizado de máquina (ML)** — o agente **aprende padrões do histórico da própria clínica** e produz uma **previsão numérica**, sem linguagem e sem LLM (custo de token zero, nenhuma chave de provedor). Três perfis: **preditor** (classifica — a chance de cada agendamento virar falta; com o ajuste **alvo = desfecho**, também a de cancelar em cima da hora, e a agenda mostra o "risco de vagar"), **projetor** (série no tempo — ex.: a receita dos próximos meses) e **analista de clima** (mede quanto cada condição do tempo muda as faltas e cancelamentos da clínica e **sugere** ajustes nos alertas de clima — a clínica aprova em Configuração › Sistema; ele não muda nenhum alerta sozinho). O perfil é escolhido **na criação** do agente ML. Ele **re-treina** e **prevê** sozinho em cadências configuráveis (no horário da clínica) e grava o resultado no domínio (a agenda mostra o risco; o painel mostra a projeção). Sem histórico suficiente ele não publica nada — a tela segue normal. Não tem persona nem modelo de LLM para escolher. - Regra prática: **determinístico quando dá; LLM só onde há ambiguidade real.** Muitos fluxos são um script rápido que, no caso duvidoso, **escala** para um agente LLM. **Previsão a partir de histórico numérico** (quem vai faltar, quanto vamos faturar) é **ML**, não LLM. Trocar o **alvo** do preditor só vale depois do próximo re-treino (o modelo antigo segue pontuando como foi treinado). - **Perfil**: o "tipo de produto" do agente (ex.: um mensageiro), uma dimensão separada do modo de decisão. O perfil define **quais campos de configuração** o agente expõe (renderizados na tela, validados no salvamento). **O que ele pode fazer** - **Capacidade / capability**: uma coisa que o agente sabe acionar (registrar uma nota, resolver um ticket, responder o paciente, confirmar um agendamento…), identificada por um **nome estável**. Cada agente tem uma **lista curada** de capabilities; ele só pode chamar o que está nela. A capability é o "o que" (o nome), não o "como" (o endereço, que a plataforma resolve em privado) — e nunca é um passe livre: a execução ainda depende de autorização. - **Autorização**: o que o agente **de fato consegue** fazer é decidido pela permissão aplicada no momento da ação, não pela configuração. Curar uma capability na lista **não concede acesso** — só declara a intenção. É por isso que um agente nunca "tem poder demais" só por listar muitas ações. **Quando ele age** - **Gatilho (trigger)**: o evento do fluxo que **acorda** o agente (paciente respondeu, conversa iniciou, algo foi fechado, prazo venceu). Sem gatilho compatível, o agente fica dormindo. Um **clique de botão numa diretiva de UI** (ver "avisar/acionar a equipe na tela") também é um evento — é o que fecha um **round-trip**: o agente avisou na tela, a pessoa clicou, o clique acorda um agente que reage. - **Filtro**: condição no gatilho que restringe **quando** ele dispara. Vários gatilhos = o agente acorda se **qualquer um** bater. - **Janela de calma (coalescer)**: pequena espera para **agrupar rajadas** e agir uma vez só, com o contexto completo, em vez de reagir a cada fragmento. **Times, registro e portabilidade** - **Time de agentes**: um conjunto de agentes que colaboram num fluxo, descritos juntos num **manifesto declarativo** (JSON). Um agente pode **referenciar** outro do mesmo time e o time pode ter **valores ajustáveis por clínica** (knobs). - **Registro (de agentes)**: um **catálogo público** de times prontos (oficiais), em **`https://fluxoideal.com/agents/`** (índice na seção "Agents" do `llms.txt` e no `agents/README.md`), que qualquer clínica pode **instalar por link**. É o primeiro lugar a olhar: reusar um time pronto é melhor que redesenhar. O manifesto publicado cita **capabilities por nome** (sem endereços internos) e declara as **permissões** que o time pede — para a clínica consentir com consciência. - **Cartão de risco**: ao instalar, a Central mostra em bom português o que o time vai poder fazer — **lê dados de paciente?**, **envia algo para fora?**, **age sozinho?** — para um consentimento informado. É informativo; a permissão real continua sendo o gate. - **Knob**: um valor de configuração por-clínica dentro do manifesto (ex.: qual template usar, quantas horas esperar). O molde do time é o mesmo; os knobs personalizam por clínica. - **Snapshot / versão**: cada versão da configuração do agente é guardada — dá pra auditar e reverter. ## Ferramentas (tarefa → como se faz) > O comportamento é **configuração**. **Reusar, desenhar, gerar e conferir** pode ser feito **com a > IA**; **aplicar** (criar as identidades, permissões e usuários dos agentes) é sempre **humano, na > Central**. A execução de qualquer ação depende de **autorização** aplicada pela plataforma. - **Reusar do registro (ANTES de tudo)** → veja se já existe um time que resolve o problema no **registro público** de agentes, em **`https://fluxoideal.com/agents/`**. Para descobrir **o que já existe**, olhe a **seção "Agents" do índice** `https://fluxoideal.com/llms.txt` (ou baixe `https://fluxoideal.com/agents/README.md`, que lista e descreve os times) — a listagem de diretório **não é navegável pelo site** (o site *serve* arquivos por URL, não lista pastas), então o índice/README é o mapa; se a IA quiser **explorar/clonar** a árvore inteira, o repositório público é **`https://github.com/henriquessn1/fluxo-ideal-ia`**. O registro tem **duas pastas**: os times **produtivos** (para instalar) ficam em `agents/times/` — o manifesto de cada um em `https://fluxoideal.com/agents/times/