Exemplos de playbook

Observação: o console do Vertex AI Agent Builder ainda se refere aos playbooks como agentes. Isso será atualizado para playbook em breve no console.

Cada playbook deve ter um ou mais exemplos. Esses exemplos são conversas entre um usuário final e o playbook, incluindo o diálogo e as ações realizadas pelo agente. Eles são, de fato, exemplos de comandos de poucos disparos (few-shot) para o LLM.

O console oferece uma interface para você inserir ações.

Agentes multilíngues

Se você quiser que o agente processe vários idiomas, os exemplos precisam usar cada um deles.

Exemplo de resumo de entrada e saída

Além dos parâmetros de entrada e saída, os playbooks aceitam um resumo de entrada e emitem um resumo de saída para trocar informações com outros playbooks. Os resumos são úteis para transmitir informações contextuais abstratas entre playbooks, enquanto os parâmetros são mais úteis para transmitir campos estruturados e bem definidos entre playbooks. Os parâmetros são a única maneira de trocar dados entre fluxos e playbooks.

Adicione resumos de entrada relevantes aos exemplos para condicionar o playbook a ajustar as ações com base nos resumos de entrada no momento da execução. Adicione resumos de saída, incluindo detalhes relevantes e precisos sobre a conversa de exemplo, para mostrar ao playbook quais detalhes são importantes para resumir.

Observação: os exemplos do playbook padrão não podem definir parâmetros de entrada ou um resumo de entrada. O playbook padrão serve como um ponto de entrada para conversas com usuários, então ele não tem como receber parâmetros de entrada.

Exemplo de estado

Em um determinado momento da conversa, um playbook estará em um dos seguintes estados:

• OK: o playbook atingiu a meta com sucesso e o controle será transferido para o playbook pai.
• CANCELLED: o usuário decidiu não prosseguir com a meta atribuída ao playbook. O controle será transferido para o playbook pai. Se o playbook pai for um fluxo de CX, a intenção da entrada do usuário será detectada antes da execução do fluxo.
• FAILED: o playbook não pode prosseguir com a meta devido a algum erro (por exemplo, a ferramenta retorna um erro 500). A sessão terminará com falha de status. Uma EndInteraction será adicionada à resposta.
• ESCALATED: o playbook decidiu que não pode atingir o objetivo e precisa escalar a situação para um humano. A sessão terminará com o status "escalado". Uma mensagem EndInteraction será adicionada à resposta.
• PENDING: a conversa ainda está em andamento no playbook.

O exemplo de nível superior e as invocações de playbook precisam ser indicados com um estado que corresponda ao playbook a que estão se referindo.

Estratégia de seleção

A configuração da estratégia de seleção controla se um exemplo é incluído no comando do playbook enviado ao LLM. As seguintes opções estão disponíveis:

• Selecionar dinamicamente: o exemplo é incluído condicionalmente, com base na relevância para o contexto da conversa atual. O exemplo pode ser omitido se o comando estiver se aproximando do limite de tokens.

• Sempre selecionar: o exemplo é sempre incluído, independente do contexto da conversa. O exemplo pode ser omitido se o comando estiver se aproximando do limite de tokens.

• Nunca selecionar: o exemplo nunca é incluído no comando. O exemplo não terá efeito no desempenho do playbook. Essa configuração é útil para excluir temporariamente um exemplo para teste.

Adicionar ação

Um exemplo fornecido em um playbook consiste em uma série de ações. Essas ações podem variar nas combinações, mas principalmente descrevem a interação entre o usuário e o playbook, além das ações realizadas para atender à consulta ou aos requisitos do usuário.

Há duas maneiras de adicionar ações a um exemplo:

• Para adicionar uma ação manualmente, clique no botão + na parte de baixo do painel direito ou no botão Adicionar ação ao manter o ponteiro sobre as ações atuais. Você pode usar essas opções ao criar um novo exemplo clicando na opção + Exemplo ou ao editar um exemplo atual.
• Para gerar ações automaticamente com base nas instruções do playbook, insira uma entrada do usuário no campo Inserir entrada do usuário na parte de baixo do painel direito. Você pode usar essa opção ao criar ou editar um exemplo. Como alternativa, você pode usar essa opção ao testar o playbook no momento da execução no painel Visualizar playbook à direita. Para salvar ações em um exemplo no painel Visualizar playbook , clique em Salvar exemplo depois de selecionar a invocação do playbook na lista de invocações à esquerda do painel Visualizar playbook.

Verifique a correção das ações geradas automaticamente e edite-as, se necessário. Isso é especialmente importante para os playbooks com poucos ou nenhum exemplo.

Os seguintes tipos de ações são aceitos pelo playbook:

Resposta do playbook

A resposta do playbook à consulta do usuário.

Entrada do usuário

A consulta do usuário.

Uso da ferramenta

Essa é uma ferramenta invocação para receber mais informações necessárias para atender à consulta do usuário. Essa ação precisa especificar os seguintes detalhes:

• Ferramenta: nome da ferramenta que precisa ser invocada.

• Ação: nome da operação da ferramenta OpenAPI que precisa ser invocada. Para ferramentas de repositório de dados e de função, o nome da ação é o mesmo que o nome da ferramenta.

• Entrada da ferramenta: entradas a serem incluídas na chamada da ferramenta. Elas geralmente são derivadas das conversas anteriores com o usuário.

  Para ferramentas da API Aberta, requestBody JSON é obrigatório para POST, PUT e PATCH tipos de método.

  Exemplo de entrada requestBody `requestBody` da ferramenta da API Aberta para a ação createPet:

  {
    "id": 1,
    "name": "Luna"
  }
  

  Para a ferramenta de repositório de dados, o exemplo requestBody em que a consulta é obrigatória e outros campos são opcionais.

  {
    "query": "Where is my nearest store?",
    "filter": "country: ANY(\"United States\")",
    "userMetadata": {
      "userCity": "San Francisco",
    },
    "fallback": "We don't have any stores in your area."
  }
  

• Saída da ferramenta: a resposta da invocação da ferramenta. Essa é uma resposta JSON válida da ferramenta para a entrada fornecida. Para ferramentas da API Aberta, também pode ser um erro de string (por exemplo, "404 não encontrado").

  Exemplo de saída da ferramenta da API Aberta para a ação listPets:

  {
    "pets": [
      {
        "id": 1,
        "name": "Luna"
      },
      {
        "id": 2,
        "name": "Charlie"
      }]
  }
  

  Exemplo de saída da ferramenta de repositório de dados:

  {
    "answer": "Here's the address to your nearest store ...",
    "snippets": [
      {
        "title": "San Francisco Downtown",
        "uri": "https://www.example.com/San_Francisco_Downtown",
        "text": "Address for San Francisco Downtown .."
      }
    ]
  }
  

Para garantir que o playbook seja à prova de falhas, inclua também exemplos de como o playbook precisa responder quando a invocação da ferramenta falha. A falha de invocação da ferramenta da API Aberta pode ser representada como uma string de erro ("404 não encontrado") na saída da ferramenta. Para ferramentas de repositório de dados a entrada fallback pode ser usada para especificar como responder se não houver uma resposta resumida.

Se você quiser que a ferramenta de repositório de dados inclua o URI na resposta do playbook, adicione exemplos que contenham o URI com que você quer que o playbook responda. Se esse URI vier da ferramenta de repositório de dados, a saída da ferramenta de repositório de dados precisará conter um URI que corresponda ao URI na resposta do playbook. A fallback não pode ser usada nesse cenário porque desativará a capacidade do playbook do LLM de reformular a resposta da ferramenta de repositório de dados para incluir URIs na resposta do playbook.

Exemplos que contêm ações de uso de ferramentas podem ser bastante detalhados e contribuir para o aumento do consumo do limite de tokens de entrada. Para garantir o uso eficiente de tokens, verifique se as saídas da ferramenta são concisas e contêm informações relevantes para as metas do playbook. Para ferramentas de repositório de dados, considere remover snippets de exemplos, já que eles podem contribuir para o alto consumo de tokens de entrada.

Invocação do playbook

Essa ação é usada quando o playbook precisa invocar outro playbook de tarefas para atender à consulta do usuário. Essa ação precisa especificar os seguintes detalhes:

• Playbook: nome do playbook a ser invocado.
• Resumo da entrada de invocação do playbook: Um resumo das partes relevantes da conversa anterior útil para o playbook que está sendo invocado.
• Parâmetros de entrada: parâmetros de entrada a serem transmitidos ao playbook.
• Resumo da saída de invocação do playbook: Um resumo do que o playbook precisa gerar após a conclusão da meta.
• Parâmetros de saída: Parâmetros de saída gerados pelo playbook após a conclusão da meta.

Transição do playbook

Uma ação de transição de playbook é uma ação terminal (não pode ser seguida por outras ações) que indica que o playbook de rotina decidiu sair e fazer a transição para um playbook de rotina de destino. Como essa ação indica que o playbook sai, adicione os parâmetros de saída do playbook à saída do playbook do exemplo.

Invocação de fluxo

Essa ação é usada quando o playbook de tarefas precisa invocar um fluxo. Essa ação precisa especificar os seguintes detalhes:

• Fluxo: nome do fluxo a ser invocado.
• Parâmetros de entrada de fluxo: Parâmetros de entrada a serem transmitidos ao fluxo.
• Parâmetros de retorno de fluxo: Parâmetros de saída retornados do fluxo.

Transição de fluxo

Uma ação de transição de fluxo é uma ação terminal (não pode ser seguida por outras ações) que indica que o playbook de rotina decidiu sair e fazer a transição para um fluxo de destino. Como essa ação indica que o playbook sai, adicione os parâmetros de saída do playbook à saída do playbook do exemplo.