Anatomia de um Agente: Agentes Passivos

José David Atualizado por José David

Um Agente Passivo é um trabalhador de IA que reage às entradas do usuário para resolver problemas. Sua definição é feita em um arquivo YAML, que atua como seu plano de construção.

Estrutura Geral

O arquivo agent_definition.yaml começa com a chave agents, que contém um ou mais agentes, cada um identificado por um slug exclusivo.

agents:
  cep_agent: # <--- Este é o slug do agente
    name: "CEP Agent"
    description: "Weni's CEP agent"
    instructions:
      - "You are an expert in providing addresses to the user based on a postal code provided by the user"
      - "The user will send a ZIP code (postal code) and you must provide the address corresponding to this code."
    guardrails:
      - "Don't talk about politics, religion or any other sensitive topic. Keep it neutral."
    tools:
      - get_address:
          name: "Get Address"
          source: 
            path: "tools/get_address"
            entrypoint: "main.GetAddress"
            path_test: "test_definition.yaml"
          description: "Function to get the address from the postal code"
          parameters:
            - cep:
                description: "postal code of a place"
                type: "string"
                required: true
                contact_field: true
slug do Agente (cep_agent): É o ID único do seu agente. Ele é usado para atualizar o agente em implantações futuras (push). Se o slug não existir, um novo agente será criado; se já existir, será atualizado.

Propriedades Principais do Agente

Essas chaves definem as características e a personalidade do agente.

  • name (string): O nome do agente exibido na interface da Plataforma Weni. Limite: 55 caracteres.
  • description (string): Uma breve descrição sobre o propósito do agente, também visível na interface.
  • instructions (lista de strings): Diretrizes e orientações que o agente deve seguir. Define seu papel, personalidade e modo de operação. Mínimo: 40 caracteres.
  • guardrails (lista de strings): Limites e tópicos que o agente deve evitar para manter a conversa focada e segura. Mínimo: 40 caracteres.
  • credentials (dict): Define as credenciais que as ferramentas do agente podem precisar para interagir com serviços externos.
    Para uma explicação detalhada, consulte o guia de Gerenciamento de Credenciais ######.

Definição da Ferramenta

tools:
  - get_address: # <--- Este é o slug da ferramenta
      name: "Get Address"
      # ... restante da configuração da ferramenta
slug da Ferramenta (get_address): É o ID exclusivo da ferramenta dentro do agente.
Propriedades da Ferramenta
  • name (string): O nome da ferramenta exibido na plataforma. Limite: 40 caracteres.
  • description (string): Uma explicação sobre o que a ferramenta faz.
  • source (dict): Conecta a definição ao código Python que executa a lógica.
    • path: Caminho para o diretório que contém o código da ferramenta (ex: tools/get_address).
    • entrypoint: O ponto de entrada, no formato nome_arquivo.NomeDaClasse (ex: main.GetAddress).
    • path_test: Caminho para o arquivo YAML que contém os casos de teste para o weni run.
Parâmetros da Ferramenta (parameters)

Define os dados de entrada que a ferramenta precisa para funcionar.

  • description (string): Explica o que é o parâmetro.
  • type (string): Tipo de dado (string, number, integer, boolean, array).
  • required (boolean): Se for true, o agente garantirá que esse dado seja obtido do usuário antes de executar a ferramenta.
  • contact_field (boolean): Se for true, o valor do parâmetro será salvo no perfil do contato na Plataforma Weni.
Para mais detalhes, leia o guia sobre Campos de Contato.

Como a gente se saiu?

Tutorial: Criando um Agente de Consulta de CEP

Anatomia de um Agente: Agentes Ativos

Contato