Skip to main content

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.

Interface Principal​

A plataforma Tech4AI oferece uma interface visual e intuitiva para gerenciar seus Agents, habilidades e ações. A navegação principal é feita através de três abas no topo da tela:

  • Agents: Gerencie seus Agents
  • Habilidades: Gerencie as habilidades disponíveis
  • Ações: Gerencie as ações executáveis

Criando um Novo Agent​

Visualizando os Agents Existentes​

Na página principal de Agents, você encontrará uma visualização em cards (cartões) de todos os Agents existentes. Cada card apresenta as seguintes informações:

  • Nome do Agent: Identificação do Agent
  • Descrição: Propósito e funcionalidades do Agent
  • Data de criação: Data em que o Agent foi criado
  • Ícone de ação: Botão para executar ou acessar o Agent

Criando um Novo Agent​

Para criar um novo Agent:

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

Botão Novo Agent

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

    • 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

  2. Clique em "Criar Agent" para finalizar o processo

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

Após a criação, o Agent aparecerá na lista de Agents e estará disponível para configuração adicional.

Configurações Avançadas do Agent​

Após criar o Agent, você pode configurar opções avançadas através da página de detalhes do Agent (clicando sobre o Agent desejado). A página de detalhes apresenta as seguintes seções:

Configurações Avançadas

Instruções​

Na seção "Instruções", você pode editar e definir as instruções que guiam o comportamento do Agent. Esta é uma área de texto editável onde você pode escrever diretamente as diretrizes, capacidades, limitações e contexto específico que o Agent deve seguir durante as conversas.

As instruções 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. Você pode editar essas instruções a qualquer momento e as alterações serão salvas automaticamente.

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ção​

Na seção "Configuração", você encontra os seguintes campos:

  • Habilidade Inicial: Um dropdown que permite selecionar qual habilidade deve ser usada para iniciar a conversa.
  • Ação Inicial: Um dropdown que permite selecionar qual ação da habilidade deve ser executada para iniciar a conversa. Você pode selecionar "Nenhuma" se não desejar executar uma ação específica no início.
  • Modelo: Um dropdown que permite selecionar qual modelo de IA será usado pelo Agent. O padrão é o gpt-4o mini. A opção "Padrão" utiliza o modelo configurado por padrão na plataforma.
  • Input Guardrails: Um toggle switch que permite ativar ou desativar guardrails para validação de entrada do usuário. Quando ativado (verde), o sistema protege contra conteúdo inseguro ou inadequado nas mensagens dos usuários.
  • Transcrição de Áudio: Um toggle switch que permite ativar ou desativar a transcrição automática de áudio. Quando habilitado, arquivos de áudio enviados pelos usuários serão automaticamente transcritos para texto.

Habilidades​

Na seção "Habilidades", você visualiza todas as habilidades vinculadas ao Agent. Para cada habilidade vinculada, são exibidas as seguintes informações:

  • Nome da habilidade: Identificação da habilidade
  • Status de vinculação: Indicação visual com ícone de check e tag "Vinculado" (em verde) mostrando que a habilidade está vinculada ao Agent
  • Data de vinculação: Data em que a habilidade foi associada ao Agent

As habilidades aparecem listadas verticalmente, com a habilidade ativa ou selecionada destacada em verde. Você pode vincular novas habilidades ou gerenciar as existentes diretamente nesta seção.

Versões​

Na seção "Versões", você pode gerenciar o ciclo de vida do Agent através de versões. Esta seção exibe:

  • Versão atual: A versão atual do Agent é exibida (ex: v.1.0.0), junto com o nome da versão e a data de criação
  • Botão "Criar Versão Homol": Um botão verde que permite criar uma versão de homologação (HOMOL) para testar o Agent antes de promover para produção
  • Tag de ambiente: Uma tag indicando o ambiente atual (ex: "HOMOL" em azul)

Após criar a versão HOMOL e testá-la, você pode promover a versão para produção (PROD) quando estiver satisfeito com os resultados. Para mais detalhes sobre o gerenciamento de versões, consulte a seção Versões. Lembre-se sempre de salvar o Agent ao alterar alguma configuraçã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 visualizar, criar e gerenciar habilidades na plataforma Tech4AI.

Visualizando as Habilidades Existentes​

Na página principal de Habilidades, você encontrará uma visualização em grid (grade) de todas as habilidades disponíveis. Cada card de habilidade apresenta as seguintes informações:

  • Ícone de habilidade: Um ícone de raio (⚡) em verde no canto superior esquerdo do card
  • Nome da habilidade: Título da habilidade em destaque
  • Descrição: Explicação breve do propósito e funcionalidades da habilidade
  • Data de criação: Data em que a habilidade foi criada ou última atualização, exibida com um ícone de relógio

As habilidades são organizadas em um layout de grid responsivo, geralmente com três colunas, facilitando a visualização e navegação entre as diferentes habilidades disponíveis.

Lista de Habilidades

Criando uma Nova Habilidade​

Para criar uma nova habilidade:

  1. Clique no botão "+ Nova Habilidade" localizado no canto superior direito da tela, na aba de Habilidades:

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

Modal Criar Nova Habilidade

  • 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

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

  2. Clique em "Cancelar" ou no ícone "X" no canto superior direito do modal se desejar descartar as alterações

Após a criação, a habilidade aparecerá na lista de habilidades e estará disponível para ser vinculada aos Agents através da seção de configurações do Agent.

Configurando uma Habilidade​

Para configurar uma habilidade existente, clique sobre o card da habilidade desejada na lista de habilidades. Isso abrirá a página de detalhes da habilidade, onde você pode configurar sua lógica e vincular ações.

Configuração de Habilidade

Informações Básicas​

No topo da página de detalhes, você encontrará:

  • Nome da habilidade: Título da habilidade em destaque

  • Descrição: Descrição da habilidade

  • ID da habilidade: Identificador único da habilidade com um botão de copiar ao lado para facilitar a referência

  • Botões de ação:

    • "← Voltar para Habilidades": Retorna à lista de habilidades
    • "Salvar": Salva todas as alterações realizadas na habilidade

Código (YAML)​

A seção "Código (YAML)" é um editor de código onde você pode definir a lógica e o comportamento da habilidade usando a sintaxe YAML. 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 a integração funcione corretamente.

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​

A seção "Ações" exibe todas as ações que estão vinculadas à habilidade. Cada ação listada mostra:

  • Nome da ação: Identificação da ação
  • Data de criação: Data de criação da ação

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

Para vincular uma nova ação à habilidade, você pode:

  1. Acessar a seção de Ações na plataforma
  2. Criar ou selecionar a ação desejada
  3. Vincular a ação à habilidade através da interface de gerenciamento de ações

Após configurar a habilidade, não se esqueça de clicar no botão "Salvar" no canto superior direito 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 Habilidades aos Agents​

Para vincular uma habilidade a um Agent, acesse a página de detalhes do Agent e navegue até a seção "Habilidades". Lá você poderá adicionar habilidades existentes ao Agent.

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 visualizar, criar e gerenciar ações na plataforma Tech4AI.

Visualizando as Ações Existentes​

Na página principal de Ações, você encontrará uma visualização em grid (grade) de todas as ações disponíveis. Cada card de ação apresenta as seguintes informações:

  • Ícone de ação: Um ícone de documento em verde no canto superior esquerdo do card
  • Nome da ação: Título da ação em destaque (geralmente em snake_case)
  • Descrição: Explicação breve do propósito e funcionalidades da ação
  • Data de criação: Data em que a ação foi criada ou última atualização, exibida com um ícone de relógio

As ações são organizadas em um layout de grid responsivo, geralmente com três colunas, facilitando a visualização e navegação entre as diferentes ações disponíveis.

Visualização

Criando uma Nova Ação​

Para criar uma nova ação:

  1. Clique no botão "+ Nova Ação" localizado no canto superior direito da tela, na aba de Ações:

  2. 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.

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

  2. Clique em "Cancelar" ou no ícone "X" no canto superior direito do modal se desejar descartar as alterações

Nova ação

Após a criação, a ação aparecerá na lista de ações e estará disponível para configuração adicional, incluindo a definição de parâmetros e código Python.

Configurando uma Ação​

Para configurar uma ação existente, clique sobre o card da ação desejada na lista de ações. Isso abrirá a página de detalhes da ação, onde você pode configurar parâmetros e escrever o código Python que será executado.

Informações Básicas​

No topo da página de detalhes, você encontrará:

  • Nome da ação: Título da ação em destaque
  • Descrição: Descrição da ação
  • ID da ação: Identificador único da ação com um botão de copiar ao lado para facilitar a referência
  • Botões de ação:
    • "← Voltar para Ações": Retorna à lista de ações
    • "Salvar": Salva todas as alterações realizadas na ação

Configurar Ação

Parâmetros​

A seção "Parâmetros" 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 a integração com a base de conhecimento funcione corretamente.

Exemplo:

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

Parâmetros

Código​

A seção "Código" é um editor de código Python onde você 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" no canto superior direito para persistir todas as alterações.

Deletar Ação​

Na parte inferior da página de detalhes, você encontrará um botão "Deletar" (com ícone de lixeira) que permite excluir permanentemente a ação. Esta ação é irreversível, então certifique-se de que deseja deletar a ação antes de confirmar.

Vinculando Ações às Habilidades​

As ações podem ser referenciadas e executadas dentro do código YAML das habilidades. Para vincular uma ação a uma habilidade:

  1. Certifique-se de que a ação já foi criada e configurada
  2. Acesse a página de detalhes da habilidade desejada
  3. No código YAML, referencie a ação usando colchetes, por exemplo: [nome_da_acao]
  4. 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.