REST Resource: projects.locations.agents.playbooks.examples

Resource: Example

Example represents a sample execution of the playbook in the conversation.

An example consists of a list of ordered actions performed by end user or Dialogflow agent according the playbook instructions to fulfill the task.

JSON representation 
{
  "name": string,
  "playbookInput": {
    object (PlaybookInput)
  },
  "playbookOutput": {
    object (PlaybookOutput)
  },
  "actions": [
    {
      object (Action)
    }
  ],
  "displayName": string,
  "description": string,
  "tokenCount": string,
  "createTime": string,
  "updateTime": string,
  "conversationState": enum (OutputState),
  "languageCode": string
}
Fields
name

string

The unique identifier of the playbook example. Format: projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/playbooks/<PlaybookID>/examples/<ExampleID>.
playbookInput

object (PlaybookInput)

Optional. The input to the playbook in the example.
playbookOutput

object (PlaybookOutput)

Optional. The output of the playbook in the example.
actions[]

object (Action)

Required. The ordered list of actions performed by the end user and the Dialogflow agent.
displayName

string

Required. The display name of the example.
description

string

Optional. The high level concise description of the example. The max number of characters is 200.
tokenCount

string (int64 format)

Output only. Estimated number of tokes current example takes when sent to the LLM.
createTime

string (Timestamp format)

Output only. The timestamp of initial example creation.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Output only. Last time the example was updated.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
conversationState

enum (OutputState)

Required. Example's output state.
languageCode

string

Optional. The language code of the example. If not specified, the agent's default language is used. Note: languages must be enabled in the agent before they can be used. Note: example's language code is not currently used in dialogflow agents.

PlaybookInput

Input of the playbook.

JSON representation 
{
  "precedingConversationSummary": string,
  "actionParameters": {
    object
  }
}
Fields
precedingConversationSummary

string

Optional. Summary string of the preceding conversation for the child playbook invocation.
actionParameters

object (Struct format)

Optional. A list of input parameters for the action.

PlaybookOutput

Output of the playbook.

JSON representation 
{
  "executionSummary": string,
  "state": enum (State),
  "actionParameters": {
    object
  }
}
Fields
executionSummary

string

Optional. Summary string of the execution result of the child playbook.
state
(deprecated)

enum (State)

End state of the playbook.
actionParameters

object (Struct format)

Optional. A Struct object of output parameters for the action.

State

Playbook output state.

Enums
STATE_UNSPECIFIED Unspecified state.
OK Playbook succeeded.
CANCELLED Playbook cancelled.
FAILED Playbook failed.
ESCALATED Playbook failed due to escalation.

Action

Action performed by end user or Dialogflow agent in the conversation.

JSON representation 
{
  "displayName": string,
  "startTime": string,
  "completeTime": string,
  "subExecutionSteps": [
    {
      object (Span)
    }
  ],
  "status": {
    object (Status)
  },

  // Union field action can be only one of the following:
  "userUtterance": {
    object (UserUtterance)
  },
  "event": {
    object (Event)
  },
  "agentUtterance": {
    object (AgentUtterance)
  },
  "toolUse": {
    object (ToolUse)
  },
  "llmCall": {
    object (LlmCall)
  },
  "intentMatch": {
    object (IntentMatch)
  },
  "flowStateUpdate": {
    object (FlowStateUpdate)
  },
  "playbookInvocation": {
    object (PlaybookInvocation)
  },
  "flowInvocation": {
    object (FlowInvocation)
  },
  "playbookTransition": {
    object (PlaybookTransition)
  },
  "flowTransition": {
    object (FlowTransition)
  },
  "tts": {
    object (TTS)
  },
  "stt": {
    object (STT)
  }
  // End of list of possible types for union field action.
}
Fields
displayName

string

Output only. The display name of the action.
startTime

string (Timestamp format)

Output only. Timestamp of the start of the agent action.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
completeTime

string (Timestamp format)

Output only. Timestamp of the completion of the agent action.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
subExecutionSteps[]

object (Span)

Optional. The detailed tracing information for sub execution steps of the action.
status

object (Status)

Optional. Output only. The status of the action.
Union field action. Action details. action can be only one of the following:
userUtterance

object (UserUtterance)

Optional. Agent obtained a message from the customer.
event

object (Event)

Optional. The agent received an event from the customer or a system event is emitted.
agentUtterance

object (AgentUtterance)

Optional. Action performed by the agent as a message.
toolUse

object (ToolUse)

Optional. Action performed on behalf of the agent by calling a plugin tool.
llmCall

object (LlmCall)

Optional. Output only. LLM call performed by the agent.
intentMatch

object (IntentMatch)

Optional. Output only. Intent Match in flows.
flowStateUpdate

object (FlowStateUpdate)

Optional. Output only. The state machine update in flows.
playbookInvocation

object (PlaybookInvocation)

Optional. Action performed on behalf of the agent by invoking a child playbook.
flowInvocation

object (FlowInvocation)

Optional. Action performed on behalf of the agent by invoking a CX flow.
playbookTransition

object (PlaybookTransition)

Optional. Action performed on behalf of the agent by transitioning to a target playbook.
flowTransition

object (FlowTransition)

Optional. Action performed on behalf of the agent by transitioning to a target CX flow.
tts

object (TTS)

Optional. Text-to-speech action performed by the agent.
stt

object (STT)

Optional. Speech-to-text action performed by the agent.

UserUtterance

UserUtterance represents one message sent by the customer.

JSON representation 
{
  "text": string,
  "audioTokens": [
    integer
  ],
  "audio": string
}
Fields
text

string

Required. Message content in text.
audioTokens[]

integer

Optional. Tokens of the audio input.
audio

string (bytes format)

Optional. Audio input.

A base64-encoded string.

Event

Event represents the event sent by the customer.

JSON representation 
{
  "event": string,

  // Union field payload can be only one of the following:
  "text": string
  // End of list of possible types for union field payload.
}
Fields
event

string

Required. Name of the event.
Union field payload. Payload of the event. payload can be only one of the following:
text

string

Optional. Unstructured text payload of the event.

AgentUtterance

AgentUtterance represents one message sent by the agent.

JSON representation 
{
  "text": string,
  "requireGeneration": boolean
}
Fields
text

string

Required. Message content in text.
requireGeneration

boolean

Optional. True if the agent utterance needs to be generated by the LLM. Only used in webhook response to differentiate from empty text. Revisit whether we need this field or mark text as optional when we expose webhook interface to customer.

ToolUse

Stores metadata of the invocation of an action supported by a tool.

JSON representation 
{
  "tool": string,
  "displayName": string,
  "action": string,
  "inputActionParameters": {
    object
  },
  "outputActionParameters": {
    object
  },

  // Union field ToolTrace can be only one of the following:
  "dataStoreToolTrace": {
    object (DataStoreToolTrace)
  },
  "webhookToolTrace": {
    object (WebhookToolTrace)
  }
  // End of list of possible types for union field ToolTrace.
}
Fields
tool

string

Required. The tool that should be used. Format: projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/tools/<ToolID>.
displayName

string

Output only. The display name of the tool.
action

string

Optional. Name of the action to be called during the tool use.
inputActionParameters

object (Struct format)

Optional. A list of input parameters for the action.
outputActionParameters

object (Struct format)

Optional. A list of output parameters generated by the action.
Union field ToolTrace. The tracing information for different tools. ToolTrace can be only one of the following:
dataStoreToolTrace

object (DataStoreToolTrace)

Optional. Data store tool trace.
webhookToolTrace

object (WebhookToolTrace)

Optional. Webhook tool trace.

DataStoreToolTrace

The tracing information for the data store tool.

JSON representation 
{
  "dataStoreConnectionSignals": {
    object (DataStoreConnectionSignals)
  }
}
Fields
dataStoreConnectionSignals

object (DataStoreConnectionSignals)

Optional. Data store connection feature output signals.

WebhookToolTrace

The tracing information for the webhook tool.

JSON representation 
{
  "webhookTag": string,
  "webhookUri": string
}
Fields
webhookTag

string

Optional. The tag of the webhook.
webhookUri

string

Optional. The url of the webhook.

LlmCall

Stores metadata of the call of an LLM.

JSON representation 
{
  "retrievedExamples": [
    {
      object (RetrievedExample)
    }
  ],
  "tokenCount": {
    object (TokenCount)
  },
  "model": string,
  "temperature": number
}
Fields
retrievedExamples[]

object (RetrievedExample)

A list of relevant examples used for the LLM prompt.
tokenCount

object (TokenCount)

The token counts of the LLM call.
model

string

The model of the LLM call.
temperature

number

The temperature of the LLM call.

RetrievedExample

Relevant example used for the LLM prompt.

JSON representation 
{
  "exampleId": string,
  "exampleDisplayName": string,
  "retrievalStrategy": enum (RetrievalStrategy),
  "matchedRetrievalLabel": string
}
Fields
exampleId

string

The id of the example.
exampleDisplayName

string

The display name of the example.
retrievalStrategy

enum (RetrievalStrategy)

Retrieval strategy of the example.
matchedRetrievalLabel

string

Optional. The matched retrieval label of this LLM call.

RetrievalStrategy

Retrieval strategy on how the example is selected to be fed to the prompt.

Enums
RETRIEVAL_STRATEGY_UNSPECIFIED Not specified. DEFAULT will be used.
DEFAULT Default retrieval strategy.
STATIC Static example will always be inserted to the prompt.
NEVER Example will never be inserted into the prompt.

TokenCount

Stores token counts of the LLM call.

JSON representation 
{
  "totalInputTokenCount": string,
  "conversationContextTokenCount": string,
  "exampleTokenCount": string,
  "totalOutputTokenCount": string
}
Fields
totalInputTokenCount

string (int64 format)

The total number of tokens used for the input to the LLM call.
conversationContextTokenCount

string (int64 format)

The number of tokens used for the conversation history in the prompt.
exampleTokenCount

string (int64 format)

The number of tokens used for the retrieved examples in the prompt.
totalOutputTokenCount

string (int64 format)

The total number of tokens used for the output of the LLM call.

IntentMatch

Stores metadata of the intent match action.

JSON representation 
{
  "matchedIntents": [
    {
      object (MatchedIntent)
    }
  ]
}
Fields
matchedIntents[]

object (MatchedIntent)

The matched intent.

MatchedIntent

Stores the matched intent, which is the result of the intent match action.

JSON representation 
{
  "intentId": string,
  "displayName": string,
  "score": number,
  "generativeFallback": {
    object
  }
}
Fields
intentId

string

The ID of the matched intent.
displayName

string

The display name of the matched intent.
score

number

The score of the matched intent.
generativeFallback

object (Struct format)

The generative fallback response of the matched intent.

FlowStateUpdate

Stores metadata of the state update action, such as a state machine execution in flows.

JSON representation 
{
  "eventType": string,
  "pageState": {
    object (PageState)
  },
  "updatedParameters": {
    object
  },
  "destination": string,
  "functionCall": {
    object (FunctionCall)
  }
}
Fields
eventType

string

The type of the event that triggered the state update.
pageState

object (PageState)

The updated page and flow state.
updatedParameters

object (Struct format)

The updated parameters.
destination

string

The destination of the transition. Format: projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>/pages/<PageID> or projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/playbooks/<PlaybookId>.
functionCall

object (FunctionCall)

The function call to execute.

PageState

Stores the state of a page and its flow.

JSON representation 
{
  "page": string,
  "displayName": string,
  "status": string
}
Fields
page

string

The ID of the page. Format: projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>/pages/<PageID>.
displayName

string

The display name of the page.
status

string

The status of the page.

FunctionCall

Stores the metadata of a function call to execute.

JSON representation 
{
  "name": string
}
Fields
name

string

The name of the function call.

PlaybookInvocation

Stores metadata of the invocation of a child playbook. Playbook invocation actions enter the child playbook.

JSON representation 
{
  "playbook": string,
  "displayName": string,
  "playbookInput": {
    object (PlaybookInput)
  },
  "playbookOutput": {
    object (PlaybookOutput)
  },
  "playbookState": enum (OutputState)
}
Fields
playbook

string

Required. The unique identifier of the playbook. Format: projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/playbooks/<PlaybookID>.
displayName

string

Output only. The display name of the playbook.
playbookInput

object (PlaybookInput)

Optional. Input of the child playbook invocation.
playbookOutput

object (PlaybookOutput)

Optional. Output of the child playbook invocation.
playbookState

enum (OutputState)

Required. Playbook invocation's output state.

OutputState

Output state.

Enums
OUTPUT_STATE_UNSPECIFIED Unspecified output.
OUTPUT_STATE_OK Succeeded.
OUTPUT_STATE_CANCELLED Cancelled.
OUTPUT_STATE_FAILED Failed.
OUTPUT_STATE_ESCALATED Escalated.
OUTPUT_STATE_PENDING Pending.

FlowInvocation

Stores metadata of the invocation of a child CX flow. Flow invocation actions enter the child flow.

JSON representation 
{
  "flow": string,
  "displayName": string,
  "inputActionParameters": {
    object
  },
  "outputActionParameters": {
    object
  },
  "flowState": enum (OutputState)
}
Fields
flow

string

Required. The unique identifier of the flow. Format: projects/<ProjectID>/locations/<LocationID>/agents/<Agentflows/<FlowID>.
displayName

string

Output only. The display name of the flow.
inputActionParameters

object (Struct format)

Optional. A list of input parameters for the flow.
outputActionParameters

object (Struct format)

Optional. A list of output parameters generated by the flow invocation.
flowState

enum (OutputState)

Required. Flow invocation's output state.

PlaybookTransition

Stores metadata of the transition to another target playbook. Playbook transition actions exit the caller playbook and enter the target playbook.

JSON representation 
{
  "playbook": string,
  "displayName": string,
  "inputActionParameters": {
    object
  }
}
Fields
playbook

string

Required. The unique identifier of the playbook. Format: projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/playbooks/<PlaybookID>.
displayName

string

Output only. The display name of the playbook.
inputActionParameters
(deprecated)

object (Struct format)

A list of input parameters for the action.

FlowTransition

Stores metadata of the transition to a target CX flow. Flow transition actions exit the caller playbook and enter the child flow.

JSON representation 
{
  "flow": string,
  "displayName": string,
  "inputActionParameters": {
    object
  }
}
Fields
flow

string

Required. The unique identifier of the flow. Format: projects/<ProjectID>/locations/<LocationID>/agents/<Agentflows/<FlowID>.
displayName

string

Output only. The display name of the flow.
inputActionParameters
(deprecated)

object (Struct format)

A list of input parameters for the action.

TTS

This type has no fields.

Stores metadata of the Text-to-Speech action.

STT

This type has no fields.

Stores metadata of the Speech-to-Text action.

Span

A span represents a sub execution step of an action.

JSON representation 
{
  "name": string,
  "tags": [
    string
  ],
  "metrics": [
    {
      object (NamedMetric)
    }
  ],
  "startTime": string,
  "completeTime": string
}
Fields
name

string

The name of the span.
tags[]

string

The metadata tags of the span such as span type.
metrics[]

object (NamedMetric)

The unordered collection of metrics in this span.
startTime

string (Timestamp format)

Timestamp of the start of the span.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
completeTime

string (Timestamp format)

Timestamp of the completion of the span.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

NamedMetric

A named metric is a metric with name, value and unit.

JSON representation 
{
  "name": string,
  "value": value,
  "unit": string
}
Fields
name

string

The name of the metric.
value

value (Value format)

The value of the metric.
unit

string

The unit in which this metric is reported. Follows The Unified Code for Units of Measure standard.

Status

The status of the action.

JSON representation 
{
  "exception": {
    object (ExceptionDetail)
  }
}
Fields
exception

object (ExceptionDetail)

Optional. The exception thrown during the execution of the action.

ExceptionDetail

Exception thrown during the execution of an action.

JSON representation 
{
  "errorMessage": string
}
Fields
errorMessage

string

Optional. The error message.

Methods

create

 Creates an example in the specified playbook.

delete

 Deletes the specified example.

get

 Retrieves the specified example.

list

 Returns a list of examples in the specified playbook.

patch

 Update the specified example.