Instruções

As instruções do agente fornecem orientações detalhadas ao modelo sobre o que ele deve fazer. Essas instruções são fornecidas em linguagem natural.

Escrever instruções

As instruções podem conter qualquer uma das seguintes opções:

• Meta geral.
• Como se comportar.
• Perfil a ser usado.
• Uma lista de subagentes, referenciados pelo nome de exibição no formato: {@AGENT: Agent Name}.
• Uma instrução para usar uma ferramenta específica, referenciada pelo nome de exibição no formato: {@TOOL: tool_name}.
• Referência a uma variável, em que o nome da variável usando snake case está entre chaves: {variable_name}.

Exemplo de um agente raiz:

CURRENT CUSTOMER: {username}

You are the main Weather Agent coordinating multiple agents.
Your primary responsibility is to provide weather information.
Use {@TOOL: get_weather} ONLY for specific weather requests 
(for example, 'weather in London').

If you know the user's name, always greet them by their name.

You have specialized sub-agents:
  1. Greeting Agent: Handles simple greetings like 'Hi', 'Hello'.
  2. Farewell Agent: Handles simple farewells like 'Bye', 'See you'.

Analyze the user's query. 
If it's a greeting, call {@AGENT: Greeting Agent} 
If it's a farewell, call {@AGENT: Farewell Agent} 
If it's a weather request, handle it yourself using {@TOOL: get_weather} 

For anything else, respond appropriately or state you cannot handle it.

Destaque de sintaxe

Quando uma variável, uma ferramenta ou um agente é referenciado no editor de instruções com a sintaxe adequada ({variable_name}, {@TOOL: tool_name} ou {@AGENT: Agent Name}), ele é destacado com um "chip" colorido, indicando que a sintaxe foi reconhecida.

Para facilitar a inserção dessas referências, o editor de instruções oferece dois atalhos:

• Ao digitar @, um menu de contexto com três opções é aberto: Agente, Ferramenta ou Variável. Você pode navegar nesse menu com as teclas de seta e Tab ou clicando. Ao selecionar uma opção, outras vão aparecer até que a referência seja concluída, quando ela se tornará um ícone.
• Ao digitar {, um menu de contexto é aberto mostrando as variáveis disponíveis para inserção rápida.

Observação: para a opção Ferramenta, apenas as ferramentas adicionadas ao agente atual aparecem no menu de contexto.

Suporte ao idioma

Ao criar comandos e instruções para o agente, use sempre o inglês para que ele entenda com a mais alta qualidade. Quando seus agentes interagem com os usuários, eles conseguem detectar o idioma da entrada do usuário final e responder automaticamente usando o mesmo idioma, a menos que seja instruído de outra forma.

Se você quiser que o agente fale (ou não fale) em determinados idiomas, inclua uma instrução descrevendo o suporte. Por exemplo, se o agente só puder responder em italiano, inclua "você só fala italiano e nenhum outro idioma" nas instruções.

Para conferir a lista de idiomas disponíveis, consulte a referência de idiomas.

Instruções de reestruturação

Você pode inserir instruções em linguagem natural, mas seu agente pode ter um desempenho melhor se você formatar as instruções usando uma estrutura XML, o que ajuda o modelo a seguir melhor as instruções. Fornecemos uma estrutura XML padrão com tags que podem ser usadas para estruturar suas instruções. Depois de inserir instruções em linguagem natural, clique no botão Reestruturar instruções acima do painel de instruções para formatar as instruções na estrutura XML recomendada.

A tabela a seguir descreve as tags XML recomendadas e como elas podem ser usadas:

Tag	Descrição
role	Define a função ou responsabilidade principal do agente.
persona	Descreve a personalidade, o tom e as diretrizes comportamentais do agente.
primary_goal	Em <persona>, especifica o objetivo principal do agente.
constraints	Lista as regras ou limitações que o agente precisa seguir.
taskflow	Descreve fluxos de conversa como uma série de subtarefas.
subtask	Dentro de <taskflow>, uma parte específica do fluxo de conversa, que contém uma ou mais etapas.
step	Dentro de <subtask>, uma etapa individual que inclui um acionador e uma ação.
trigger	Em <step>, a condição ou entrada do usuário que inicia uma etapa.
action	Em <step>, a ação que o agente precisa realizar quando uma etapa é acionada.
examples	Contém exemplos de few-shot para orientar o comportamento do agente em cenários específicos.

Confira um exemplo das mesmas instruções usando a estrutura XML recomendada:

CURRENT CUSTOMER: {username}

<role>The main Weather Agent coordinating multiple agents.</role>

<persona>
    <primary_goal>To provide weather information.</primary_goal>
    How to handle prohibited topics and violations: Respond appropriately or
    state inability to handle the request.
    General guidelines: Follow the constraints and task flow precisely.
</persona>

<constraints>
    1. Use {@TOOL: get_weather} ONLY for specific weather requests 
      (for example, 'weather in London').
    2. If the user's name is known (from the 'CURRENT CUSTOMER' context), always
      greet them by their name.
</constraints>

<taskflow>
    These define the conversational subtasks that you can take. Each subtask
    has a sequence of steps that should be taken in order.
    <subtask name="Initial Greeting">
        <step name="Check for Username and Greet">
            <trigger>Start of conversation or new user interaction.</trigger>
            <action>If a username is provided in the 'CURRENT CUSTOMER' context,
              greet the user by their name. Otherwise, proceed without a 
              personalized greeting.
            </action>
        </step>
    </subtask>
    <subtask name="Query Analysis and Routing">
        <step name="Analyze User Query">
            <trigger>User provides a query.</trigger>
            <action>Determine the intent of the user's query 
              (greeting, farewell, weather request, or other).
            </action>
        </step>
        <step name="Handle Greeting">
            <trigger>User query is identified as a simple greeting
              (e.g., 'Hi', 'Hello').
            </trigger>
            <action>Call {@AGENT: Greeting Agent}.</action>
        </step>
        <step name="Handle Farewell">
            <trigger>User query is identified as a simple farewell
              (e.g., 'Bye', 'See you').
            </trigger>
            <action>Call {@AGENT: Farewell Agent}.</action>
        </step>
        <step name="Handle Weather Request">
            <trigger>User query is identified as a specific weather request
              (e.g., 'weather in London').
            </trigger>
            <action>Use {@TOOL: get_weather} to retrieve weather information and
              provide it to the user.
            </action>
        </step>
        <step name="Handle Other Queries">
            <trigger>User query does not fall into greeting, farewell, or
              specific weather request categories.
            </trigger>
            <action>Respond appropriately to the query or state that the request
              cannot be handled.
            </action>
        </step>
    </subtask>
</taskflow>
<examples>
</examples>

Exemplos few-shot inline

O comando de poucos disparos (few-shot) é uma técnica em que um modelo de linguagem grande (LLM) recebe um pequeno conjunto de exemplos para orientar o comportamento, o tom ou a lógica dele. No contexto dos agentes, "exemplos inline com poucos disparos" se referem à colocação desses exemplos diretamente nas instruções do agente, em vez de em um painel separado da UI. Esse método ajuda o modelo a entender requisitos complexos mostrando em vez de apenas dizendo, essencialmente preenchendo a lacuna entre instruções abstratas e execução concreta.

Quando usar exemplos few-shot

Os exemplos few-shot são uma ferramenta poderosa para calibragem, mas precisam ser usados de forma estratégica. Considere adicioná-los nos seguintes cenários:

• Resolver problemas de qualidade: use exemplos principalmente para corrigir falhas específicas em que o modelo entende mal as instruções de forma consistente.
• Formatação complexa: quando o agente precisa gerar dados em um formato muito específico e não padrão.
• Lógica sutil: quando as instruções "se-então" não são suficientes para capturar a sutileza de um processo de tomada de decisão.

Práticas recomendadas e avisos

Embora sejam eficazes, os exemplos few-shot precisam ser selecionados com cuidado para não prejudicar o desempenho do agente.

• Use com moderação: adicionar muitos exemplos pode fazer com que o agente apresente overfitting, ou seja, siga os exemplos de forma rígida e perca a capacidade de generalizar para consultas de usuários novas e não vistas.
• Descritivo, não exaustivo: não é necessário enumerar todas as consultas possíveis do usuário. Os exemplos servem como orientação para o padrão de raciocínio do modelo, não como um banco de dados de pesquisa.
• Comece com instruções: sempre tente resolver problemas de comportamento com instruções claras e descritivas primeiro. Só adicione exemplos se as instruções não forem suficientes para alcançar o resultado desejado.

Componentes de um exemplo few-shot

Um exemplo padrão de few-shot para agentes consiste em quatro componentes distintos que simulam um turno de conversa.

Componente	Tag / Sintaxe	Descrição
Usuário	[user]	Representa a entrada ou consulta do usuário final.
Modelo	[model]	Representa a resposta textual ou o processo de criação do agente.
Entrada de ferramenta	tool_code	Demonstra como o agente deve estruturar a entrada ou "chamada" para uma ferramenta ou função externa (por exemplo, argumentos/sintaxe específicos).
Resposta da ferramenta	tool_outputs	Simula os dados retornados pela ferramenta, ensinando o agente a interpretar e usar esses dados na resposta final.

O formato a seguir deve ser usado para exemplos de few-shot:

<examples>
  EXAMPLE 1:
  Begin example
  [user]
  What's the weather in London?
  [model]
  ```tool_code
  get_weather(location="London")
  ```
  ```tool_outputs
  {"temperature": "15 C", "condition": "Cloudy"}
  ```
  [model]
  The weather in London is 15 C and Cloudy.
  End example
</examples>

Refinar instruções

Selecione uma parte do conteúdo das instruções e um botão Refinar vai aparecer. Clique nesse botão para usar a IA e melhorar o conteúdo selecionado. No campo Requisitos, insira informações sobre como você quer melhorar o conteúdo selecionado.

Formatar respostas do agente

Você pode instruir o agente sobre como formatar as respostas de texto para melhorar a legibilidade. Confira a seguir as práticas recomendadas para instruções de formatação:

Divisão em partes e espaços em branco

• Nunca escreva parágrafos densos. Os usuários fazem uma leitura rápida, não leem.
• Limite os blocos de texto a no máximo uma ou duas frases.
• Insira uma quebra de linha entre cada ideia distinta para criar espaço em branco.

Negrito estratégico

• Você precisa colocar em negrito os pontos de dados mais importantes para que eles se destaquem instantaneamente.
• Sempre em negrito: nomes de produtos, preços, datas, números de pedidos e prazos.
• Exemplo: "A camiseta clássica custa US$25,00".

Listas sobre texto

• Se você mencionar mais de dois itens ou etapas, converta automaticamente em uma lista com marcadores ou numerada.
• Use marcadores padrão (-) para opções e listas numeradas (1.) para instruções.

Instruções globais

Além de definir instruções específicas do agente, é possível definir instruções globais nas configurações avançadas do aplicativo do agente.

Todos os agentes no aplicativo herdam as instruções globais, que são enviadas ao modelo em todos os turnos de conversa, além das instruções específicas do agente.

As instruções globais são adequadas para informações genéricas que todos os agentes precisam saber. Por exemplo: tom da marca, "O QUE FAZER E O QUE NÃO FAZER" gerais, variáveis compartilhadas globalmente e perfis de clientes.