Blocos de código

Pré-visualização

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Quando define um plano de ação, pode, opcionalmente, fornecer blocos de código, que são código Python incorporado que pode ser usado para controlar melhor o comportamento do agente. Este código é composto por funções com decoradores especiais e quaisquer funções de utilidade necessárias.

Ao escrever o seu código, pode usar a biblioteca do sistema de blocos de código para controlar o comportamento do agente.

Problemas Conhecidos

Aplicam-se os seguintes problemas conhecidos:

• Os projetos em perímetros do VPC-SC que restringem o acesso ao Artifact Registry também rejeitam implementações de blocos de código

Limitações

Aplicam-se as seguintes limitações:

• Os blocos de código não podem conter objetos que persistam dados. No entanto, pode usar ferramentas para persistir dados e manter o estado.
• Os blocos de código não podem fazer chamadas remotas diretamente. Por exemplo, não pode usar a biblioteca de pedidos Python. No entanto, pode usar ferramentas para fazer chamadas remotas indiretamente.
• Os nomes de recursos convertidos em nomes Python têm de ser nomes Python legais.
• Os blocos de código não podem escrever parâmetros de sessão, a menos que ocorra uma transição de fluxo.

Ações inline

As ações inline comportam-se de forma semelhante às ações de ferramentas. Têm um esquema de entrada e saída definido, que é determinado pela assinatura da função Python, incluindo anotações de tipo e docstring. Semelhante às chamadas de ferramentas, o MDG não tem conhecimento do código que implementa a ação.

Exemplo:

@Action
def is_prime(n: int) -> bool:
  """Returns true if n is prime."""
  if not isinstance(n, int) or n < 2:
    return False

  for i in range(2, int(n ** 0.5) + 1):
    if n % i == 0:
      return False

  return True

Para esta função, o MDI/CE recebe informações sobre a ação, a respetiva entrada e a respetiva saída.

Para fazer referência a uma ação inline nas instruções do seu manual, basta fazer referência ao nome da ação entre acentos graves e descrever como deve ser usada.

Exemplo de uma ação inline place_order:

Take the customer's order, then call the `place_order` action when the order is ready.

Para criar exemplos que usam ações inline, use o tipo de ferramenta inline-action na secção Entrada e saída.

Para mais informações, consulte a documentação de referência de @Action.

Funções de acionador

As funções de acionador são usadas para definir ações condicionais no código.

As funções de acionador são declaradas através de decoradores. Pode usar os seguintes decoradores de funções de acionador:

Decorator	Parâmetros do decorator	Descrição
@EventTrigger	event: str, condition: str, onde a condição é opcional	Acionada por um evento
@BeforeModelTrigger	condition: str, onde a condição é opcional	Acionado sempre antes de o MDG prever a ação seguinte.
@BeforeActionTrigger	condition: str, onde a condição é opcional	Acionado sempre antes de o GML executar uma ação.
@BeforePlaybookTrigger	condition: str, onde a condição é opcional	Acionado quando um manual é iniciado pela primeira vez.

Por exemplo, estas funções mostram como usar estes decoradores e parâmetros de decoradores, bem como como usar a função respond da biblioteca do sistema de blocos de código.

# No decorator parameter
@PlaybookStartTrigger
def my_playbook_conditional_action():
  respond("How can I help?")

# With a condition decorator parameter
@BeforeActionTrigger('$next-action.name = "search"')
def my_before_action_conditional_action():
  respond("One moment please")

# Event
@EventTrigger(event="welcome")
def my_welcome_event():
  respond("hi")

# Event with a condition:
@EventTrigger(event="welcome",
              condition="$sys.func.NOW().hours < 10")
def my_good_morning_event():
  respond("Good morning ☕")

Referenciar fluxos, guias interativos e ferramentas

No bloco de código, pode fazer referência a fluxos, manuais de procedimentos e ferramentas específicos através das variáveis globais flows, playbooks e tools.

Cada um destes objetos tem membros que correspondem aos nomes dos recursos correspondentes. Estes nomes têm de ser nomes Python legais.

Exemplo:

  add_override(playbooks.troubleshooting, {})
  add_override(flows.billing)
  add_override(tools.weather_api.get_weather, {"location": "San Francisco"})

Quando fizer referência a fluxos e manuais de soluções num bloco de código, também tem de fazer referência aos mesmos nas instruções do manual de soluções com a seguinte sintaxe:

${RESOURCE_TYPE: my_resource_name}

Por exemplo, se o seu bloco de código contiver flows.myflow e playbooks.myplaybook, as instruções do manual de soluções devem incluir:

${FLOW: myflow}
${PLAYBOOK: myplaybook}

Substituições de ações

Pode usar blocos de código para criar uma fila de ações que ocorrem antes de quaisquer outras ações determinadas pelo MDG e, potencialmente, substituí-las. Crie substituições de ações através da função global add_override.

Todas as ações de substituição em fila são executadas sequencialmente e o resultado da ação fica disponível para o MDG. Quando a fila estiver vazia, a operação regressa ao MDG para seleção de ações e entradas, a menos que uma substituição termine o turno com respond ou outra função que conclua o turno.

Argumentos de funções:

• action: a ação a realizar. Para uma ação inline, use my_function_name. Para uma ação da ferramenta, use tools.my_tool_name.my_tool_action. Para uma ação de fluxo, use flows.my_flow_name.
• inputs: entradas opcionais para a ação. Por exemplo: {"location": "Omaha"}.

Samples:

# Assuming remote tool named "dmv" with operationId "search_offices"
# remote tool with only requestBody
add_override(tools.dmv.search_offices,{"address": "95030"})

# remote tool with only parameters
add_override(tools.pets.get_pet, {"id": "123"})

# remote tool with requestBody + parameters:
add_override(tools.pets.create_pet, {"requestBody": {"arg1":"foo"}, "param1": "bar"})

# datastore. Assumes existing datastore tool named "Menu".
add_override(tools.menu.Menu, {"query": "what is the menu"})

# code block action. Assumes another code block @Action my_action.
add_override(my_action)

Substituições de respostas

Semelhante às substituições de ações, mas especificamente para respostas do agente, pode usar a função global respond para forçar o agente a responder ao utilizador com conteúdo específico.

Exemplo:

respond("Hello")

Ferramentas de chamadas

Nas funções do bloco de código, pode chamar as ferramentas definidas para o seu agente. Ao contrário do que acontece quando substitui uma ação de ferramenta, quando chama uma ferramenta diretamente, os resultados da execução da ferramenta não estão disponíveis para o MDI/CE.

Samples:

# Assumes existing tool named "DMV" with operationId "search_offices"
# remote tool with only request body.
offices = tools.dmv.search_offices({"address": "95030"})

# remote tool with parameters and request body
offices = tools.dmv.search_offices({"requestBody": {"address":"95030"}, "param1":"foo"})

# datastore actions. Assumes existing datastore tool named "Menu".
data = tools.menu.Menu({"query": "get the menu"})["snippets"]

Corresponder à intenção

Os blocos de código podem corresponder programaticamente a uma intenção para um determinado fluxo usando a função Flow.match_intent.

Exemplo:

matches = flows.flow1.match_intent(history.last_user_utterance).matches
if matches and matches[0].intent == "some_intent":
  to_country = matches[0].parameters.get("to_country")
  if to_country:
    respond(f"To confirm, you're going to {to_country}, right?")

Ler parâmetros de sessão

Os blocos de código podem ler parâmetros que estão disponíveis no momento da execução.

Exemplo:

state["$session.params.my-param"]
state["$request.session-id"]

Depuração

Pode usar o simulador para depurar as funções do bloco de código. Estas funções são apresentadas como ações no simulador e fornecem os nossos detalhes conforme necessário.

Controlo adicional

Este guia aborda algumas utilizações comuns da biblioteca do sistema de blocos de código. Para ver outros tipos de controlo, consulte a documentação da biblioteca.