Manuais generativos

Observação: esse recurso tem acesso limitado. Entre em contato com sua equipe de conta do Google Cloud para solicitar acesso a esse recurso e acessar a documentação de referência da API.

Os playbooks generativos oferecem uma nova maneira de criar agentes do Dialogflow CX usando modelos de linguagem grandes (LLM). Em vez de definir fluxos, páginas, intents e transições, você fornece instruções de linguagem natural e dados estruturados na forma de manuais. Isso pode reduzir significativamente o tempo de criação e manutenção do agente, além de permitir novos tipos de experiências de conversa para sua empresa.

Se você ainda precisa do controle explícito fornecido pelos fluxos em determinados cenários de conversa, é possível combinar a eficiência dos playbooks e fluxos em um único agente híbrido.

Observação :o text-bison da Vertex AI é o modelo atual usado por manuais generativos.

Limitações

Considere as seguintes limitações:

• Apenas o inglês é compatível.
• Somente as regiões us-central1 e global são compatíveis.
• Os agentes do playbook não oferecem suporte ao envio de um SMS complementar de chamada da rota de intent de boas-vindas padrão no fluxo de início padrão, mas é possível ativar a opção de SMS complementar em fluxos padrão.

Visão geral do manual

Um playbook é o elemento básico de um agente playbook. Um agente normalmente tem muitos manuais, em que cada um deles é definido para lidar com tarefas específicas. Os dados do manual são fornecidos ao LLM para que ele tenha as informações necessárias para responder a perguntas e executar tarefas. Cada manual pode fornecer informações, enviar consultas a serviços externos ou adiar o tratamento de conversas para um fluxo tradicional ou outro manual para lidar com subtarefas.

Criar agentes do playbook

Ao criar um agente do Dialogflow, é possível permitir que ele inicie uma conversa com um playbook (agente playbook) ou um fluxo (agente tradicional).

Para criar um agente de playbook:

1. Siga as etapas para criar um agente, selecionando Criar seu próprio.
2. Selecione Generativo como o tipo de agente.
3. Clique em Save.

Há três novos seletores de recursos na navegação à esquerda. Com esses seletores, você pode escolher entre:

• Recursos de fluxo
• Recursos generativos
• Recursos compartilhados

Quando você cria um agente de playbook, um playbook padrão é criado automaticamente.

Dados do playbook

Nesta seção, descrevemos os dados que definem um playbook.

Nome do playbook

O Nome do manual é o nome de exibição do manual. Os playbooks podem fazer referência entre si com esse nome.

Meta do manual

Uma meta do manual é uma descrição de alto nível do que ele precisa realizar.

Exemplo:

Help customers to book flights and hotels.

Etapas do playbook

As etapas do playbook definem o processo que precisa ser realizado para atingir a meta do manual.

Cada etapa contém uma instrução de linguagem natural que pode conter qualquer um destes itens:

• Uma instrução básica que o LLM consegue entender.
• Uma instrução para encaminhar o usuário para outro playbook. Os playbooks são referenciados usando o formato ${PLAYBOOK: playbook_name}.
• uma instrução de uso de uma ferramenta específica; As ferramentas são referenciadas usando o formulário ${TOOL: tool_name}.
• Uma instrução para encaminhar o usuário a um fluxo do Dialogflow. Os fluxos são referenciados usando o formato ${FLOW: flow_name}.

Cada descrição de etapa começa com "- ", e você pode definir subetapas usando recuo.

Exemplo:

- greet the customer and ask them how you can help.
    - If the customer wants to book flights, route them to ${PLAYBOOK: flight_booking}.
    - If the customer wants to book hotels, route them to  ${PLAYBOOK: hotel_booking}.
    - If the customer wants to know trending attractions, use the ${TOOL: attraction_tool} to show them the list.
- help the customer to pay for their booking by routing them to ${FLOW: make_payment}.

Observação: ao editar as etapas, é possível que você veja um aviso indicando que uma referência de recurso não tem exemplos correspondentes. Ainda é possível salvar e usar o playbook com esse aviso, mas é improvável que ele funcione de maneira confiável até que exemplos que usem o recurso sejam adicionados.

Parâmetros do playbook

Os playbooks podem aceitar e emitir informações de contexto usando parâmetros explicitamente definidos. Os parâmetros são definidos por manual, usando a guia Parâmetros, depois que você cria um manual.

Os parâmetros do playbook têm tipo, nome e descrição. Depois de definir os parâmetros, use-os nos exemplos do manual para mostrar ao manual como ler, gravar e usar os valores de parâmetro de maneira confiável. Consulte os exemplos de entrada e saída de manuais e como transmitir parâmetros para mais orientações.

Parâmetros de entrada do playbook

Os parâmetros de entrada permitem que os playbooks usem valores transmitidos de fluxos e outros playbooks. Por exemplo, um playbook pode receber o nome preferido de um usuário como parâmetro e usá-lo para agradecer ao usuário pessoalmente, ou um playbook pode receber um identificador de pedido como parâmetro e usá-lo para recuperar detalhes do pedido usando uma ferramenta.

Os parâmetros de entrada do playbook são definidos por manual, e esses manuais não têm visibilidade de outros tipos de parâmetros do Dialogflow CX por padrão. Quando um fluxo muda para um manual, os parâmetros de página e sessão são propagados para o manual de destino, caso ele tenha um parâmetro de entrada com o mesmo nome. Para comunicar informações de um fluxo para um manual durante uma transição, defina os parâmetros de entrada do manual com o mesmo nome de um parâmetro de sessão ou página presente antes da transição.

Observação: o manual padrão não aceita parâmetros de entrada. O playbook padrão serve como um ponto de entrada para conversas de usuários, portanto, não tem como receber parâmetros de entrada.

Crie exemplos para controlar como o valor do parâmetro de entrada afetará as ações do manual. Por exemplo, se um parâmetro de entrada afetar a maneira como o agente se refere ao usuário, crie exemplos que definam um valor para o parâmetro e use o mesmo valor em ações de fala no exemplo. Veja como transmitir parâmetros para mais detalhes.

Parâmetros de saída do playbook

Os parâmetros de saída permitem que os playbooks emitam informações para serem usadas por outros fluxos ou manuais. Por exemplo, um playbook pode coletar um número de pedido de um usuário e emiti-lo por meio de um parâmetro de saída, ou um playbook pode usar uma ferramenta para reservar um voo e emitir o número de confirmação por um parâmetro de saída.

Crie exemplos para controlar como o manual precisa decidir o valor de cada parâmetro de saída. Por exemplo, se um parâmetro de saída que representa um número de confirmação derivar o valor dele a partir do resultado de um uso de ferramenta, crie exemplos em que o resultado do uso da ferramenta corresponda ao valor do parâmetro de saída do playbook.

Como transmitir parâmetros

Ao contrário dos fluxos, os playbooks não oferecem suporte à injeção de valores de parâmetro com uma sintaxe específica. Em vez disso, os playbooks contam com instruções e alguns exemplos de prompt para determinar como os valores de parâmetro precisam ser usados e como eles devem ser decididos ao especificar valores de parâmetro.

Considere um agente desenvolvido para a venda de ingressos de eventos com os seguintes manuais:

1. Um playbook chamado Ticket ordering que faz pedidos usando uma ferramenta chamada Ticket sales API.
   1. Este playbook aceita um parâmetro de entrada com o tipo number e o nome event_id.
   2. A ferramenta Ticket sales API espera uma solicitação que inclua um event_id.
2. Um playbook chamado Event selection, que ajuda os usuários a selecionar um evento e os encaminha para Ticket ordering com o parâmetro event_id para comprar ingressos.

Neste exemplo, para garantir que event_id seja transmitido de forma confiável de Event selection para Ticket ordering e de Ticket ordering para Ticket sales API, são necessários vários exemplos.

O manual Ticket ordering precisa incluir vários exemplos que:

• Especifique o parâmetro de entrada event_id com um valor realista, diferente em cada exemplo.
• Inclua uma ação de uso da ferramenta com um corpo de solicitação que inclua o mesmo valor realista de event_id, conforme especificado no parâmetro de entrada.

O manual Event selection precisa incluir vários exemplos que:

• Inclua uma fala do usuário em que o usuário seleciona um evento com um event_id realista, diferente em cada exemplo.
• Inclua uma invocação manual de Ticket ordering que defina o parâmetro event_id como o mesmo event_id realista de acordo com a seleção do usuário.

Além de adicionar exemplos, tente adicionar instruções específicas às etapas do manual, à meta do manual ou os detalhes da ferramenta explicando como os parâmetros precisam ser usados. Por exemplo, o manual Ticket ordering inclui a seguinte etapa:

- Use parameter event_id to send a buy_tickets request with ${TOOL: Ticket sales API}

Com os exemplos e as instruções descritos presentes, o manual Event selection decide corretamente um event_id com base na seleção do usuário e o transmite como um parâmetro de entrada chamado event_id para o Ticket ordering playbook. Em seguida, Ticket ordering transmite o mesmo event_id no corpo de uma solicitação para o Ticket sales API. Os manuais dependem de exemplos com valores de parâmetro distintos para ajudar a inferir como os parâmetros precisam ser usados.

Exemplos de playbooks

Cada playbook precisa ter um ou mais exemplos. Esses exemplos são conversas de amostra entre um usuário final e o agente, incluindo o diálogo e as ações realizadas pelo agente. Esses são, na prática, exemplos de comandos few-shot para o LLM.

O console fornece uma interface para você inserir ações. Exemplo:

Exemplo de resumo de entrada e de saída

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

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

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

Exemplo de parâmetros de entrada e saída

Além de um resumo de entrada e um resumo de saída, se um manual define parâmetros de entrada ou saída, todos os exemplos dele também precisam definir esses parâmetros de entrada ou saída para ajudar o modelo de linguagem a inferir como usar os valores de parâmetro de maneira confiável.

Cada exemplo do manual precisa especificar e usar valores para cada parâmetro definido no manual, conforme mostrado neste manual com dois parâmetros de entrada e um de saída:

Exemplo de estado de saída do manual

Para cada exemplo criado, selecione o estado do playbook que melhor representa o estado final da conversa de exemplo:

• OK: a meta do manual foi alcançada.
• CANCELLED: o manual parou sem atingir a meta devido às circunstâncias na conversa. Por exemplo, esse estado pode ser apropriado se a conversa inclui um usuário mudando de ideia sobre o que precisa de ajuda.
• FAILED: o manual parou sem atingir a meta devido a um erro ou circunstância não processável. Por exemplo, esse estado pode ser apropriado se a meta não puder ser alcançada devido a problemas de rede durante uma invocação de ferramenta.
• ESCALATED: o manual parou sem atingir a meta porque o usuário solicitou encaminhamento para um agente humano.

Estratégia de recuperação

A estratégia de recuperação controla se cada exemplo é incluído na solicitação do playbook.

• DEFAULT: o exemplo pode ser omitido se a solicitação se aproximar do limite de tokens.
• STATIC: o exemplo é sempre incluído.
• NEVER: o exemplo nunca é incluído no comando. O exemplo não terá nenhum efeito no desempenho do manual.

Observação :a estratégia de recuperação "Nunca" pode ser útil para excluir temporariamente um exemplo de teste e entender os efeitos no desempenho do manual.

Criar um manual

Para criar um playbook:

1. Selecione os recursos generativos na navegação à esquerda.
2. Clique em Manuais.
3. Selecione Criar novo.
4. Forneça os dados conforme descrito acima.

Manual padrão

Quando você cria um agente generativo, um manual padrão é criado automaticamente.

O playbook padrão é o ponto de partida para conversas, por isso tem algumas distinções importantes de outros manuais:

• O manual padrão não recebe um resumo dos turnos de conversas anteriores.
• O playbook padrão não pode definir nem receber parâmetros de entrada.

Versões do manual

É possível salvar versões de playbooks, que são snapshots imutáveis de playbooks.

Para salvar uma versão do playbook:

1. Carregue o playbook no console.
2. Clique em Histórico de versões.
3. Clique em Criar versão.
4. Forneça um nome para a versão e clique em Salvar.

Para visualizar o histórico de versões:

1. Carregue o playbook no console.
2. Clique em Histórico de versões.
3. Clique em Ver histórico de versões.
4. O painel do histórico de versões é aberto no lado direito. Clique em cada versão para ver seu conteúdo.

Ferramentas

As etapas do playbook podem fazer referência a ferramentas que precisam ser usadas para concluir a etapa. Para cada ferramenta usada pelos manuais, você fornece os detalhes da ferramenta fornecendo um esquema OpenAPI.

No momento, as chamadas da API HTTP ou as consultas do armazenamento de dados são compatíveis.

É possível fornecer um ID de sessão como caminho ou parâmetro de consulta. Exemplo:

parameters:
  - name: petId
    in: path
    description: ID of pet that needs to be updated
    required: true
    schema:
      $ref: '@dialogflow/sessionId'
  - name: petName
    in: query
    description: ID of pet that needs to be updated
    required: true
    schema:
      $ref: '@dialogflow/sessionId'

As seguintes limitações se aplicam a chamadas de API HTTP:

• Parâmetros de consulta não são compatíveis com exceção do ID da sessão.
• O corpo da solicitação e da resposta precisa estar vazio ou em JSON.
• Recursos de esquema avançados, como oneOf, não são compatíveis.

O exemplo abaixo mostra como fazer referência a um repositório de dados:

"dataStoreConnections": [
    {
       "dataStoreType": "DATA_STORE_TYPE",
       "dataStore": "projects/PROJECT_ID/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID"
    }
]

O valor de DATA_STORE_TYPE pode ser um dos seguintes:

• PUBLIC_WEB: repositório de dados com conteúdo público da Web.
• UNSTRUCTURED: um repositório de dados que contém dados particulares não estruturados.
• STRUCTURED: um repositório de dados que contém dados estruturados (por exemplo, perguntas frequentes).

O exemplo a seguir mostra como fazer referência a uma ferramenta API HTTP:

openapi: 3.0.2
info:
  title: Search Attraction Tool
  description: >-
    This API search for attractions for travel purposes
  version: 1.0
servers:
  - url: https://search-attraction.app
paths:
  /search:
    post:
      summary: Search for attractions given a query
      operationId: search
      requestBody:
        description: Query
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Query'
      responses:
        '200':
          description: Successfully got results (may be empty)
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: string
components:
  schemas:
    Query:
      required:
        - text
      type: object
      properties:
        text:
          type: string

Práticas recomendadas

As práticas recomendadas a seguir podem ajudar você a criar agentes robustos.

Pelo menos um exemplo para cada playbook

É preciso ter pelo menos um example em cada playbook. Sem exemplos suficientes, um manual provavelmente resultará em um comportamento imprevisível. Se o agente não estiver respondendo ou se comportando da maneira esperada, a causa provavelmente será a falta de exemplos ou a definição incorreta. Tente melhorar seus exemplos ou adicionar novos.

Precisão de instruções e exemplos

Embora ajude a escrever etapas de instrução claras e descritivas, é na verdade a qualidade e a quantidade dos exemplos que determinam a precisão do comportamento do agente. Em outras palavras, gaste mais tempo escrevendo exemplos completos do que escrevendo instruções perfeitamente precisas.

Campo "OperationId" do esquema da ferramenta

Ao definir esquemas para suas ferramentas, o valor operationId é importante. Suas instruções do playbook vão fazer referência a esse valor. Veja a seguir recomendações de nomenclatura para esse campo:

• Somente letras, números e sublinhados.
• Precisa ser exclusivo entre todos os operationIds descritos no esquema.
• Precisa ser um nome significativo que reflita a funcionalidade fornecida.

Validação do esquema da ferramenta

É preciso validar o esquema da ferramenta. Use o Editor Swagger para verificar a sintaxe do esquema da openAPI 3.0.

Gerar um esquema com o Bard

O Bard pode gerar um esquema para você. Por exemplo, tente "Você pode criar um exemplo de esquema da openAPI 3.0 para o Google Agenda?".

Playbooks focados

Evite criar playbooks muito grandes e complexos. Cada manual precisa cumprir uma tarefa específica e clara. Se você tiver um manual complexo, considere dividi-lo em sub-playbooks menores.

Casos de teste

O recurso existente de caso de teste foi aprimorado para oferecer suporte a manuais.

Foi adicionado um campo obrigatório de resultado esperado de caso de teste, que fornece uma lista de ações na forma de exemplos de manual. O caso de teste verifica se as ações foram realizadas conforme o esperado.

Ao visualizar uma versão do manual ou do manual, clique na guia Casos de teste acima dos dados para ver os resultados dos casos de teste e executar um caso de teste sob demanda.

Também é possível comparar resultados de casos de teste para diferentes versões de um manual. Selecione um caso de teste e clique em Comparar.

Para ver todos os casos de teste do agente, clique em Casos de teste na navegação à esquerda.

Histórico de conversas

O recurso atual de histórico de conversas foi aprimorado para oferecer suporte a manuais.

Foram adicionadas informações sobre a execução de ferramentas, invocação de playbooks e invocação de fluxo de um agente de manual.