Construção de Agents

Os Agents são sistemas inteligentes que podem interagir com usuários, executar ações específicas e utilizar habilidades para realizar tarefas complexas. Esta seção apresenta um guia completo sobre como criar, configurar e gerenciar seus Agents no Tech4AI, desde os primeiros passos até funcionalidades avançadas de integração.

Arquitetura da Interface

A interface de gestão de Agents está organizada em uma estrutura hierárquica:

Estrutura de Rotas:

• Listagem: /agents/builder - Página principal com visualização de todos os agents em abas (Conversacional e Tarefas)
• Criação: Modal de diálogo acessado através do botão "+ Novo Agente" - Permite criar agents de ambos os tipos
• Edição: /agents/builder/agent/[agentId] - Página de edição completa com sidebar de navegação e área de conteúdo

Componentes Principais:

• Sidebar de Navegação: Permite navegar entre Dados Gerais, Habilidades, Ações e Versões
• Área de Conteúdo: Exibe formulários de edição com estrutura em abas (Config. Gerais e Código)
• Botões de Ação: Salvamento e descarte de alterações sempre visíveis no topo

Criando um Novo Agent

Visualizando os Agents Existentes

Na página principal de Agents (/agents/builder), você encontrará uma interface organizada com abas para visualizar os diferentes tipos de agentes:

• Aba "Conversacional": Lista todos os agentes conversacionais em formato de tabela
• Aba "Tarefas": Lista todos os agentes de tarefas em formato de tabela

Cada linha da tabela apresenta informações sobre o agent, incluindo nome, descrição, data de criação e ações disponíveis.

Criando um Novo Agent

Para criar um novo Agent:

1. Clique no botão "+ Novo Agente" localizado no canto superior direito da tela

2. Selecione o tipo de agente no modal que será exibido (Conversacional ou Tarefas)

3. Preencha o formulário de criação com as seguintes informações:

   • Nome (obrigatório): Identificação do Agent
   • Descrição (obrigatório): Explicação detalhada do propósito e funcionalidades do Agent
   • Modelo: Selecione o modelo LLM que será utilizado pelo Agent (dropdown). O padrão é o gpt-4o mini
   • Instruções (opcional): Instruções específicas que guiam o comportamento e respostas do Agent

4. Clique em "Criar" para finalizar o processo

5. Clique em "Cancelar" se desejar descartar as alterações

Após a criação, você será redirecionado automaticamente para a página de edição do Agent (/agents/builder/agent/[agentId]), onde poderá configurar habilidades, ações e outras opções avançadas.

Configurações Avançadas do Agent

Após criar o Agent, você pode configurar opções avançadas através da página de edição do Agent (/agents/builder/agent/[agentId]). A página de edição possui uma estrutura com sidebar lateral e área de conteúdo principal:

Sidebar de Navegação:

• Dados Gerais: Configurações básicas e instruções do Agent
• Habilidades: Lista de habilidades vinculadas ao Agent (cada habilidade pode ser selecionada para edição)
• Ações: Lista de ações vinculadas às habilidades (cada ação pode ser selecionada para edição)
• Versões: Gerenciamento de versões do Agent (HOMOL/PROD)

Dados Gerais

Na seção "Dados Gerais", você pode editar as configurações básicas do Agent:

Informações Básicas:

• Nome: Identificação do Agent
• Descrição: Explicação detalhada do propósito e funcionalidades do Agent
• Instruções Gerais: Diretrizes, capacidades, limitações e contexto específico que o Agent deve seguir durante as conversas

As instruções gerais são fundamentais para definir o propósito do Agent, seu público-alvo, suas capacidades e como ele deve se comportar em diferentes situações.

Exemplo de Instruções

Abaixo está um exemplo de instruções para um Agent conversacional de atendimento:

Você é um Atendente da Seguradora Nova Era, especialista em atender Segurados, Corretores e outros perfis relacionados da Nova Era.

Público Alvo: Segurados, Corretores, Prestadores de saúde, Oficinas Auto, Terceiros (Sinistro) e potenciais clientes.

Linguagem: Utilize palavras de fácil entendimento do público brasileiro. Não use expressões muito formais ou que possam parecer robóticas.

Limitações:

- Não responda ou faça comparações com outras empresas e concorrentes.

- Converse somente sobre a Nova Era e seus serviços.

- Siga rigorosamente as etapas definidas em suas habilidades sem deduzir informações que não estejam explicitamente descritas nos tópicos e instruções.

- Se o assunto não for relacionado a um dos tópicos de suas habilidades, pergunte se o usuário deseja falar com um especialista.

Formatação das respostas:

- Evite fragmentação excessiva. Agrupe parágrafos relacionados na mesma mensagem. Ao apresentar menus, mantenha o cabeçalho, a lista de opções e a instrução de escolha juntos em um único bloco de mensagem final para facilitar a leitura.

Informações Gerais:

- Assistência 24h:

Se o usuário pedir informações sobre Assistência 24h, informe:

Para veículos: WhatsApp (11 98888-0000), 0800 555 1234 ou https://novaeraauto.assistenciaexemplo.com.br/ | Para residência/empresa: 0800 555 4321.

Configurações de Inicialização:

• Modelo: Dropdown para selecionar qual modelo LLM será usado pelo Agent. O padrão é "padrão" (utiliza o modelo configurado por padrão na plataforma)
• Habilidade Inicial: Dropdown para selecionar qual habilidade deve ser usada para iniciar a conversa. Você pode selecionar "Nenhuma habilidade" se não desejar uma habilidade inicial específica
• Ação Inicial: Dropdown para selecionar qual ação da habilidade deve ser executada para iniciar a conversa (este campo só aparece quando uma habilidade inicial é selecionada). Você pode selecionar "Nenhuma ação" se não desejar executar uma ação específica no início

Configurações de Funcionalidades:

• Ativar guardrails para validação de entrada do usuário: Toggle switch que, quando ativado, protege contra conteúdo inseguro ou inadequado nas mensagens dos usuários
• Ativar transcrição automática de áudio: Toggle switch que, quando habilitado, transcreve automaticamente arquivos de áudio enviados pelos usuários para texto
• Roteamento Inteligente: Toggle switch que habilita a seleção automática da melhor fonte de informação de acordo com a pergunta do usuário

Mensagens Personalizadas:

• Mensagem de Processamento: Mensagem exibida ao usuário enquanto o sistema processa webhooks ou operações assíncronas
• Mensagem de Erro: Mensagem personalizada exibida ao usuário quando ocorre um erro no processamento

Após fazer alterações, clique no botão "Salvar" no canto superior direito para persistir as mudanças. Você também pode clicar em "Descartar" para reverter as alterações não salvas.

Versões

No topo da tela, você encontrará um botão de "Versões" onde pode gerenciar o ciclo de vida do Agent através de versões.

Funcionalidades:

• Versão atual: Exibe a versão atual do Agent (ex: v.1.0.0), nome da versão e data de criação
• Tag de ambiente: Indicação visual do ambiente (ex: "HOMOL" em azul, "PROD" em verde)
• Criar nova versão: Botão para criar versões de homologação (HOMOL) para testar o Agent antes de promover para produção

Fluxo de versionamento:

1. Desenvolva e teste o Agent no ambiente de desenvolvimento
2. Crie uma versão HOMOL para testes controlados
3. Após validação, promova a versão para PROD

Importante: Lembre-se sempre de salvar o Agent ao alterar alguma configuração antes de criar uma nova versão.

Gerenciando Habilidades

As habilidades são capacidades específicas que podem ser atribuídas aos Agents para que eles possam executar tarefas especializadas. Esta seção explica como criar e gerenciar habilidades na plataforma Tech4AI.

Criando uma Nova Habilidade

As habilidades são gerenciadas diretamente na página de edição do Agent. Para criar uma nova habilidade:

1. Acesse a página de edição do Agent (/agents/builder/agent/[agentId])

2. Na sidebar lateral, localize a seção "Habilidades" e clique no botão "+ Nova Habilidade"

3. Preencha o formulário de criação que será exibido em um modal:

   • Nome (obrigatório): Identificação da habilidade. Digite o nome que descreve a funcionalidade da habilidade
   • Descrição (obrigatório): Explicação detalhada do propósito e funcionalidades da habilidade. Descreva o que a habilidade faz e quando deve ser utilizada

4. Clique em "Criar" para finalizar o processo e criar a habilidade

5. Clique em "Cancelar" se desejar descartar as alterações

Após a criação, a habilidade aparecerá na lista de habilidades na sidebar e será automaticamente selecionada para edição.

Configurando uma Habilidade

Para configurar uma habilidade existente, clique sobre a habilidade desejada na sidebar. A área de conteúdo principal exibirá a interface de edição da habilidade organizada em abas.

Estrutura de Edição

A interface de edição da habilidade é dividida em duas abas principais:

1. Aba "Config. Gerais" Esta aba contém o formulário com as configurações básicas da habilidade:

• Nome da habilidade: Título da habilidade
• Descrição: Descrição detalhada da habilidade
• Outros campos de configuração conforme necessário

2. Aba "Código" Esta aba contém o editor YAML onde você define a lógica e comportamento da habilidade.

No topo das abas, você encontrará:

• Botão "Salvar": Salva todas as alterações realizadas na habilidade
• Botão "Descartar": Descarta as alterações não salvas

Na parte inferior da página, há um botão "Excluir" que permite remover permanentemente a habilidade (ação irreversível).

Código (YAML)

Na aba "Código", você encontrará um editor de código YAML onde pode definir a lógica e o comportamento da habilidade. Esta é a área principal de configuração da habilidade, onde você define:

• instructions: Instruções gerais que guiam o comportamento da habilidade. Aqui você define o papel do assistente, regras de ouro, regras de contexto e diretrizes específicas que a habilidade deve seguir.

• topics: Tópicos de conversação que definem diferentes fluxos e cenários. Cada tópico contém:

  • description: Descrição do propósito do tópico
  • steps: Passos que definem o fluxo de conversação, incluindo:
    • Definições de termos e análise de input
    • Execução de ações específicas
    • Lógica condicional baseada no contexto da conversa

O editor YAML possui recursos como:

• Redimensionamento: Ícone de redimensionamento no canto inferior direito para ajustar o tamanho do editor
• Sintaxe destacada: Destaque de sintaxe para facilitar a leitura e edição do código
• Validação: O sistema valida a sintaxe YAML para garantir que o código está correto

Exemplo de Código YAML

Abaixo está um exemplo de código YAML para uma habilidade:

instructions: Gerencie o atendimento ao usuário autenticado (Cliente ou Parceiro Comercial), focando em status financeiro, emissão de boletos e consulta de vigência.

topics:
  - Boas-vindas e Legal:
      description: |
        Apresentação e avisos regulatórios. Envie exatamente a sequência de mensagens abaixo:

        Olá, sou o assistente virtual da Nova Era Seguros. Estou aqui para agilizar seu atendimento.

        Aviso importante: Ao prosseguir, você concorda com os Termos de Uso e nossa Política de Privacidade.

        Para solicitações relacionadas aos seus dados pessoais (LGPD), acesse o Portal de Privacidade em nosso site.

        Como posso auxiliar você agora?

  - Identificação do Contrato:
      description: Gerencia o processo de localização e seleção do contrato ou apólice.
      steps:
        - Fluxo para Cliente: |
            Caso o usuário seja o Titular (Cliente): use a ação [listar_contratos_ativos].
        - Fluxo para Parceiro: |
            Caso o usuário seja um Parceiro Comercial: 
                - Solicite o CPF ou CNPJ do cliente que o parceiro deseja consultar.
                - Use a ação [buscar_contrato_por_documento].

Importante: Step para Consulta à Base de Conhecimento

Ao criar uma habilidade que utiliza ações para consultar bases de conhecimento, o step que contém a chamada à ação deve ter o nome exato "Consulta à Base de Conhecimento". Este é um requisito obrigatório para que o Router Knowledge funcione corretamente e possa rotear as consultas para as bases de conhecimento apropriadas.

Exemplo correto:

topics:
  - Dúvidas:
      description: Utilize este tópico para responder QUALQUER dúvida do cliente.
      steps:
        - Formular Pergunta: Analise o contexto da conversa e formule uma pergunta clara.
        - Consulta à Base de Conhecimento: SEMPRE utilize a ação [consultar_bases_de_conhecimento] para encontrar a resposta.
        - Formular Resposta: Responda o usuário de forma natural com base na resposta retornada pela ação.

Importante: O nome do step deve ser exatamente "Consulta à Base de Conhecimento" (com maiúsculas e minúsculas conforme mostrado).

Exemplo completo com múltiplas bases de conhecimento:

topics:
  - Esclarecimento de Dúvidas sobre Produtos:
      description: Utilize este tópico para responder a todas as perguntas do cliente sobre produtos, abrangendo temas como regulamentos, contratos, seguros, processos e outras dúvidas gerais. SE O USUÁRIO FIZER UMA SOLICITAÇÃO ESPECÍFICA (diferente de apenas ter uma dúvida sobre o processo), transfira para um atendente.

      steps:
        - Análise e Coleta de Informação Adicional: |
            Antes de consultar a base de conhecimento, verifique a real necessidade do cliente. 
            Se a dúvida for sobre um processo específico, pergunte primeiro qual é o tipo de produto (Tipo A, Tipo B, Tipo C ou Serviços) para refinar a busca. 
            Se a pergunta for sobre resultados de processos ou status, informe diretamente que a consulta pode ser feita no site https://www.exemplo.com.br/consultas.

        - Consulta à Base de Conhecimento: |
            Com base no assunto específico da dúvida do cliente, formule uma pergunta clara e utilize a ação correspondente. As ações para cada tema são:

            - Regulamento: [consultar_regulamento] Utilize esta base para responder qualquer dúvida do cliente sobre o regulamento do produto. Perguntas típicas são diretas e focam em valores mensais, taxas existentes, funcionamento de processos, prazos, documentos necessários, análises solicitadas, consequências de atrasos e políticas de cancelamento.

            - Contrato de Adesão: [consultar_contrato_adesao] Utilize esta base para responder qualquer dúvida do cliente sobre o contrato de adesão.

            - Seguros: [consultar_seguro] Utilize esta base para responder qualquer dúvida do cliente sobre seguro do produto. Sobre importância do seguro e razão para contrata-lo.

            - Funcionamento de Processos: [consultar_processos] Utilize esta base para responder perguntas sobre processos, como funcionam, formas de aprovação, datas e prazos, etc.

            - Pós-Aprovação: [consultar_pos_aprovacao] Utilize esta base para responder perguntas de clientes que informam que já foram aprovados. As possíveis dúvidas podem ser relação de documentos necessários no processo, informações sobre cada tipo de produto (Tipo A, Tipo B, Tipo C ou Serviços). Se não souber o produto, pergunte ao cliente antes de buscar a resposta.

            - Dúvidas Gerais: [consultar_duvidas_gerais] Utilize esta base para responder perguntas sobre funcionamento geral do produto (definições, processos, formas de aprovação e tipos), informações sobre vantagens, grupos e reajustes. SE O USUÁRIO FIZER UMA SOLICITAÇÃO ESPECÍFICA (Diferente de dúvidas sobre o processo), VOCÊ DEVE TRANSFERIR PARA A FILA DE ATENDIMENTO.

        - Formular Resposta: Responda o usuário de forma natural com base na resposta retornada pela ação.

        - Tratar erros e transferir para atendente: Se a ação retornar uma mensagem de erro ou indicar que não há informação, diga 'Peço desculpas, mas não encontrei a informação que você precisa em minha base de dados. Gostaria de falar com um de nossos atendentes?'

        - Finalizar Atendimento: "Fico feliz em ajudar. Você tem mais alguma dúvida?"

Ações Vinculadas

As ações vinculadas à habilidade selecionada aparecem na sidebar direita, que se torna visível quando você seleciona uma habilidade. Esta sidebar organiza as ações em duas seções: "Ações" (vinculadas) e "Ações não vinculadas".

Funcionalidades:

• Lista de ações vinculadas: Cada ação vinculada à habilidade selecionada aparece como um item clicável na seção "Ações"
• Adicionar ação: Botão "+ Nova Ação" permite criar uma nova ação vinculada à habilidade
• Vincular/desvincular: Cada ação possui um ícone de corrente ou corrente quebrada que permite vincular ou desvincular a ação da habilidade
• Reutilizar ações: Ações não vinculadas podem ser vinculadas a outras habilidades, promovendo reutilização

Vinculação e Desvinculação de Ações

Para informações detalhadas sobre como vincular e desvincular ações, consulte a seção Vinculando e Desvinculando Ações.

Referenciando ações no código YAML: As ações vinculadas podem ser referenciadas no código YAML da habilidade usando colchetes, por exemplo: [consultar_acervo_historico], [transbordo_atendimento_oficial], etc.

Ao clicar em uma ação, a área de conteúdo principal exibe a interface de edição da ação (veja mais detalhes na seção Configurando uma Ação).

Importante: Após configurar a habilidade, não se esqueça de clicar no botão "Salvar" para persistir todas as alterações.

Boas Práticas e Desafios Comuns

Ao configurar habilidades e instruções para seus Agents, é importante estar ciente de alguns desafios fundamentais relacionados ao funcionamento dos modelos de linguagem (LLMs):

Natureza Interpretativa do LLM

Importante: O LLM Interpreta

O maior desafio ao trabalhar com Agents é entender que o LLM interpreta as instruções. Ele não segue comandos de forma literal, mas sim interpreta o contexto e a intenção.

Princípios fundamentais:

• Seja direto: Quanto mais direto e objetivo você for nas instruções, melhor será a interpretação do LLM
• Menos é mais: Quanto menos instruções, melhor. Instruções excessivamente longas ou complexas podem confundir o modelo
• Evite ambiguidade: Instruções ambíguas ou com múltiplas interpretações podem levar a comportamentos inesperados
• Teste e refine: Sempre teste suas instruções e ajuste com base nos resultados observados

Exemplo de instrução direta:

✅ BOM: "Quando o usuário solicitar o status do pedido, use a ação [consultar_status_pedido]"
❌ EVITE: "Em situações onde o cliente demonstra interesse em saber informações sobre o andamento de suas compras, você pode considerar utilizar a funcionalidade de consulta de status..."

Transições entre Tópicos

Cuidado com Transições Excessivas

Muitas transições entre tópicos podem fazer o Agent se perder durante a conversa. O LLM pode ter dificuldade em gerenciar contextos complexos com múltiplas mudanças de assunto.

Recomendações:

• Limite o número de transições: Evite criar habilidades com muitos tópicos que transitam entre si de forma complexa
• Quebre em habilidades separadas: Se você perceber que está expandindo a complexidade de uma habilidade, considere quebrar em outras habilidades mais específicas
• Mantenha o foco: Cada habilidade deve ter um propósito claro e bem definido
• Simplifique o fluxo: Fluxos lineares e diretos são mais fáceis para o LLM gerenciar do que fluxos com muitas ramificações

Exemplo de organização:

✅ BOM:
- Habilidade "Consulta de Pedidos" (foco: apenas consultas)
- Habilidade "Cancelamento de Pedidos" (foco: apenas cancelamentos)
- Habilidade "Alteração de Dados" (foco: apenas alterações)

❌ EVITE:
- Uma única habilidade "Gestão Completa" que tenta fazer tudo: consultas, cancelamentos, alterações, reembolsos, trocas, etc.

Conscientização sobre Limitações

É fundamental que todos que trabalham com a configuração de Agents estejam cientes dessas limitações e desafios:

• O LLM não é determinístico: O mesmo input pode gerar outputs ligeiramente diferentes
• Contexto é limitado: O modelo tem limitações de contexto, então instruções muito longas podem perder informações importantes
• Testes são essenciais: Sempre teste suas configurações em diferentes cenários antes de colocar em produção

Ao seguir essas práticas, você aumentará significativamente a qualidade e a confiabilidade dos seus Agents.

Vinculando e Desvinculando Habilidades

As habilidades podem ser vinculadas ou desvinculadas do Agent através da interface do builder. A sidebar organiza as habilidades em duas seções distintas:

Seção "Habilidades" (Vinculadas)

Esta seção exibe todas as habilidades ativas e vinculadas ao Agent. Quando uma habilidade está vinculada, ela está disponível para uso pelo Agent durante as conversas.

Características:

• Localizada no topo da área de habilidades na sidebar
• Cada habilidade vinculada possui um ícone de corrente quebrada à direita
• Ao clicar no ícone, um popup de confirmação aparece para desvincular a habilidade

Seção "Habilidades não vinculadas"

Esta seção exibe todas as habilidades inativas e não vinculadas ao Agent. Essas habilidades existem no sistema, mas não estão disponíveis para uso pelo Agent.

Características:

• Localizada na parte inferior da área de habilidades na sidebar
• Cada habilidade não vinculada possui um ícone de corrente à direita
• Ao clicar no ícone, um popup de confirmação aparece para vincular a habilidade

Como Vincular/Desvincular Habilidades

Para criar uma nova habilidade vinculada:

1. Acesse a página de edição do Agent (/agents/builder/agent/[agentId])
2. Na sidebar, localize a seção "Habilidades"
3. Clique em "+ Nova Habilidade" para criar uma nova habilidade
4. A habilidade criada ficará automaticamente vinculada ao Agent (aparecerá na seção "Habilidades")

Para desvincular uma habilidade:

1. Na seção "Habilidades", localize a habilidade que deseja desvincular
2. Clique no ícone de corrente quebrada à direita do nome da habilidade
3. Um popup de confirmação aparecerá: "Tem certeza que deseja desabilitar esta habilidade no agente?"
4. Clique em "Confirmar" para desvincular a habilidade
5. A habilidade será movida para a seção "Habilidades não vinculadas"

Para vincular uma habilidade:

1. Na seção "Habilidades não vinculadas", localize a habilidade que deseja vincular
2. Clique no ícone de corrente à direita do nome da habilidade
3. Um popup de confirmação aparecerá: "Tem certeza que deseja habilitar esta habilidade no agente?"
4. Clique em "Confirmar" para vincular a habilidade
5. A habilidade será movida para a seção "Habilidades"

Dica: Alternando entre Seções

Você pode clicar no título de cada seção ("Habilidades" ou "Habilidades não vinculadas") para expandir ou recolher a lista, facilitando a navegação quando há muitas habilidades.

Importante: Salvamento Automático

A vinculação e desvinculação de habilidades é salva automaticamente no banco de dados. Você não precisa clicar no botão "Salvar" após vincular ou desvincular uma habilidade.

Gerenciando Ações

As ações são funções executáveis que podem ser chamadas pelos Agents através das habilidades. Elas permitem que os Agents realizem operações específicas, integrem com sistemas externos e executem processamentos customizados. Esta seção explica como criar e gerenciar ações na plataforma Tech4AI.

Criando uma Nova Ação

As ações são gerenciadas diretamente na página de edição do Agent, vinculadas a uma habilidade específica. Para criar uma nova ação:

1. Acesse a página de edição do Agent (/agents/builder/agent/[agentId])

2. Na sidebar, selecione a habilidade à qual deseja vincular a ação

3. Na seção "Ações" da sidebar (que aparece abaixo das habilidades), clique no botão "+ Nova Ação"

4. Preencha o formulário de criação que será exibido em um modal:

   • Nome (obrigatório): Identificação da ação. Digite o nome que descreve a funcionalidade da ação (recomenda-se usar snake_case, por exemplo: validar_cpf_segurado)
   • Descrição (opcional): Explicação do que a ação faz. Em casos normais, é necessário apenas descrever a funcionalidade da ação. O contexto de uso da ação é determinado pela habilidade, e os detalhes dos parâmetros são definidos na seção de parâmetros. Uma menção de alto nível sobre os tipos de parâmetros esperados pode ser útil para uma compreensão rápida da funcionalidade

Nome e Descrição da Ação

O nome e a descrição da ação são fundamentais para que o LLM escolha corretamente qual ação utilizar durante a conversa.

• Nome: Use nomes claros e descritivos que indiquem a funcionalidade da ação (ex: validar_cpf_segurado, consultar_status_pedido, gerar_boleto). O LLM utiliza o nome para identificar e referenciar a ação.

• Descrição: Em casos normais, é necessário apenas descrever o que a ação faz. O contexto de uso da ação é determinado pela habilidade, e os detalhes dos parâmetros são definidos na seção de parâmetros. Uma menção de alto nível sobre os tipos de parâmetros esperados pode ser útil para uma compreensão rápida da funcionalidade

Um nome e uma descrição bem escritos ajudam o LLM a decidir quando chamar a ação correta, melhorando a precisão e relevância das respostas do Agent.

5. Clique em "Criar" para finalizar o processo e criar a ação

6. Clique em "Cancelar" se desejar descartar as alterações

Após a criação, a ação aparecerá na lista de ações na sidebar e será automaticamente selecionada para edição, onde você poderá configurar parâmetros e código Python.

Configurando uma Ação

Para configurar uma ação existente:

1. Na sidebar, selecione a habilidade que contém a ação
2. Clique sobre a ação desejada na seção "Ações" da sidebar

A área de conteúdo principal exibirá a interface de edição da ação organizada em abas.

Estrutura de Edição

A interface de edição da ação é dividida em duas abas principais:

1. Aba "Config. Gerais" Esta aba contém:

• Formulário com as configurações básicas da ação (nome, descrição, etc.)
• Seção de Parâmetros para definir os parâmetros de entrada da ação

2. Aba "Código" Esta aba contém o editor Python onde você define a lógica que será executada quando a ação for chamada.

No topo das abas, você encontrará:

• Informações de última atualização: Nome do usuário e data da última modificação
• Botão "Salvar": Salva todas as alterações realizadas na ação
• Botão "Descartar": Descarta as alterações não salvas

No cabeçalho da página:

• Nome da ação: Título da ação em destaque

Na parte inferior da página, há um botão "Excluir" que permite remover permanentemente a ação (ação irreversível).

Parâmetros

Na aba "Config. Gerais", você encontrará a seção "Parâmetros" que permite definir os parâmetros de entrada que a ação aceita. Cada parâmetro possui:

• Nome: Identificação do parâmetro
• Tipo: Tipo de dado do parâmetro (Texto, Número, Verdadeiro ou Falso, Lista e Valores Fixos.)
• Descrição: Explicação do propósito do parâmetro
• Obrigatório: Indicação se o parâmetro é obrigatório ou opcional
• Valor padrão: Valor padrão para parâmetros opcionais (se aplicável)

Para adicionar um novo parâmetro, clique no botão "+ Adicionar Parâmetro" e preencha as informações necessárias.

Os parâmetros definidos estarão disponíveis no código Python da ação através de um dicionário de parâmetros, permitindo que você acesse os valores passados quando a ação for chamada.

Importante: Parâmetro para Base de Conhecimento

Ao criar uma action para consultar uma base de conhecimento, o parâmetro que receberá a consulta do usuário deve ter o nome exato "consulta". Este é um requisito obrigatório para que o Router Knowledge funcione corretamente e possa rotear as consultas para as bases de conhecimento apropriadas.

Exemplo:

• ✅ Correto: Parâmetro com nome consulta (tipo: Texto)
• ❌ Incorreto: Parâmetros com nomes como pergunta, query, busca, etc.

Código

Na aba "Código", você encontrará um editor de código Python onde escreve a lógica que será executada quando a ação for chamada. O editor possui:

• Sintaxe destacada: Destaque de sintaxe Python para facilitar a leitura e edição do código
• Numeração de linhas: Numeração das linhas para facilitar a referência
• Redimensionamento: Ícone de redimensionamento no canto inferior direito para ajustar o tamanho do editor

No código Python, você tem acesso a:

• Parâmetros da ação: Um dicionário contendo todos os parâmetros definidos na seção de Parâmetros
• SDK de Actions: Ferramentas e utilitários do Actions SDK para facilitar o desenvolvimento (consulte a documentação do SDK para mais detalhes)

Importação de Bibliotecas

O uso de bibliotecas externas é limitado por questões de segurança. Caso receba um erro ao importar uma biblioteca, pode ser que ela não esteja disponível no ambiente. Neste caso, você deve solicitar a viabilidade da biblioteca para o time de produto.

Exemplo de Código Python

Abaixo está um exemplo completo de código Python para uma ação de consulta de status de pedido:

def consultar_status_pedido(numero_pedido: str = None):
    # Verifica se o usuário já passou pela identificação
    cliente_identificado = state_manager.get("cliente_identificado")

    # Validação de segurança / fluxo
    if not cliente_identificado:
        return ResponseToAgent(
            instruction="Não é possível consultar o pedido pois o cliente não foi identificado. Solicite o CPF ou E-mail antes de prosseguir.",
            functions=[
                RedirectToSkill(
                    skill_name="Identificação do Cliente",
                    reason="Usuário anônimo tentou consultar pedido"
                )
            ]
        )

    # Validação do parâmetro de entrada
    if not numero_pedido:
        return ResponseToAgent(
            instruction="O número do pedido não foi fornecido. Pergunte ao cliente qual é o código do pedido (ex: PED-123).",
        )
    # SIMULA os dados do pedido retornado pelo sistema de logística
    pedido_encontrado = {
        "id": numero_pedido,
        "data_compra": "2024-05-10",
        "valor_total": "R$ 259,90",
        "status_atual": "Em trânsito",
        "transportadora": "LogFast Express",
        "codigo_rastreio": "BR123456789",
        "previsao_entrega": "2024-05-15",
        "itens": [
            {"produto": "Tênis Esportivo Runner", "quantidade": 1},
            {"produto": "Par de Meias", "quantidade": 3}
        ],
        "endereco_entrega": {
            "rua": "Av. das Américas, 500",
            "cidade": "Rio de Janeiro",
            "uf": "RJ"
        }
    }

    # Atualiza o state com o objeto do pedido completo (para uso imediato)
    state_manager.update("pedido_ativo", pedido_encontrado)

    # Atualiza a memória de longo prazo com o contexto do rastreio
    memory_manager.update("historico_interacao", {
        "ultimo_pedido_consultado": pedido_encontrado["id"],
        "status_ultimo_pedido": pedido_encontrado["status_atual"]
    })

    # Retorna instrução para o Agente formatar a resposta ao usuário
    return ResponseToAgent(
        instruction=f"Pedido localizado com sucesso.\nID: {pedido_encontrado['id']}\nStatus: {pedido_encontrado['status_atual']}\nPrevisão: {pedido_encontrado['previsao_entrega']}\n\nInforme o status ao cliente e pergunte se ele deseja o código de rastreio da transportadora {pedido_encontrado['transportadora']}.",
    )

Após escrever o código, não se esqueça de clicar no botão "Salvar" para persistir todas as alterações.

Vinculando e Desvinculando Ações

As ações podem ser vinculadas ou desvinculadas de uma habilidade específica através da interface do builder. Quando você seleciona uma habilidade na sidebar, a seção de "Ações" aparece ao lado direito, organizada em duas seções distintas:

Seção "Ações" (Vinculadas)

Esta seção exibe todas as ações vinculadas à habilidade selecionada. Quando uma ação está vinculada a uma habilidade, ela pode ser referenciada e executada no código YAML dessa habilidade.

Características:

• Localizada no topo da área de ações na sidebar direita
• Aparece somente quando uma habilidade está selecionada
• Exibe ações que possuem vínculo com a habilidade selecionada
• Cada ação vinculada possui um ícone de corrente quebrada à direita
• Ao clicar no ícone, um popup de confirmação aparece para desvincular a ação

Seção "Ações não vinculadas"

Esta seção exibe todas as ações que não estão vinculadas à habilidade selecionada. Essas ações existem no sistema, mas não podem ser usadas pela habilidade atual até serem vinculadas.

Características:

• Localizada na parte inferior da área de ações na sidebar direita
• Aparece somente quando uma habilidade está selecionada
• Exibe ações que não possuem vínculo com a habilidade selecionada
• Cada ação não vinculada possui um ícone de corrente à direita
• Ao clicar no ícone, um popup de confirmação aparece para vincular a ação

Como Vincular/Desvincular Ações

Para criar uma nova ação vinculada:

1. Selecione a habilidade desejada na sidebar principal (à esquerda)
2. Na sidebar de ações (à direita), localize a seção "Ações"
3. Clique em "+ Nova Ação" para criar uma nova ação
4. A ação criada ficará automaticamente vinculada à habilidade selecionada (aparecerá na seção "Ações")

Para desvincular uma ação:

1. Selecione a habilidade que contém a ação que deseja desvincular
2. Na seção "Ações", localize a ação que deseja desvincular
3. Clique no ícone de corrente quebrada à direita do nome da ação
4. Um popup de confirmação aparecerá: "Tem certeza que deseja desvincular esta ação da habilidade?"
5. Clique em "Confirmar" para desvincular a ação
6. A ação será movida para a seção "Ações não vinculadas"

Para vincular uma ação existente:

1. Selecione a habilidade à qual deseja vincular a ação
2. Na seção "Ações não vinculadas", localize a ação que deseja vincular
3. Clique no ícone de corrente à direita do nome da ação
4. Um popup de confirmação aparecerá: "Tem certeza que deseja vincular esta ação à habilidade?"
5. Clique em "Confirmar" para vincular a ação
6. A ação será movida para a seção "Ações"

Dica: Reutilização de Ações

As ações não vinculadas podem ser reutilizadas entre diferentes habilidades. Por exemplo, se você tem uma ação consultar_cpf que já foi criada para uma habilidade, pode vinculá-la a outras habilidades sem precisar recriar a ação.

Isso promove a reutilização de código e facilita a manutenção, pois uma alteração na ação afetará todas as habilidades que a utilizam.

Dica: Alternando entre Seções

Você pode clicar no título de cada seção ("Ações" ou "Ações não vinculadas") para expandir ou recolher a lista, facilitando a navegação quando há muitas ações.

Importante: Salvamento Automático

A vinculação e desvinculação de ações é salva automaticamente no banco de dados. Você não precisa clicar no botão "Salvar" após vincular ou desvincular uma ação.

Referenciando Ações no Código YAML

Para executar uma ação vinculada dentro do código YAML da habilidade, referencie a ação usando colchetes:

steps:
  - Consultar dados: |
      Use a ação [nome_da_acao] para buscar as informações necessárias.

Importante: Você só pode referenciar ações que estejam vinculadas à habilidade. Se tentar referenciar uma ação não vinculada, o Agent não conseguirá executá-la durante a conversa.

A ação será executada quando o fluxo da habilidade chegar ao ponto onde ela está referenciada. Para mais detalhes sobre como usar ações no código YAML das habilidades, consulte a seção Ações Vinculadas na documentação de Habilidades.