Method: projects.locations.virtualDbxAgent.query

virtualDbxAgent.query runs the agent.

HTTP request

POST https://databaseinsights.googleapis.com/v1beta/{parent=projects/*/locations/*}/virtualDbxAgent:query

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Request body

The request body contains data with the following structure:

JSON representation 
{
  "userQuery": string,
  "sessionId": string,
  "projectId": string,
  "productType": string,
  "engineType": string,
  "location": string,
  "databaseChatContext": {
    object (DatabaseChatContext)
  },
  "additionalContext": {
    string: string,
    ...
  },
  "agentOptions": {
    object (AgentOptions)
  }
}
Fields
userQuery

string

Required. The user query to be used for the agent.
sessionId

string

Required. The session id of the user query. This is used to identify the user query and the agent response.
projectId

string

Optional. The project id of the database.
productType

string

Optional. The product type of the database. This is a string representation of the product type
engineType

string

Optional. The engine type of the database. This is a string representation of the engine type.
location

string

Optional. The location of the database resource
databaseChatContext

object (DatabaseChatContext)

Optional. The database chat context to be used for database chat tools.
additionalContext

map (key: string, value: string)

Optional. The additional context to be used for the agent.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
agentOptions

object (AgentOptions)

Optional. The options for processing the request on the agent.

Response body

If successful, the response body contains data with the following structure:

JSON representation 
{
  "response": string,
  "visualizations": [
    {
      object (Visualization)
    }
  ],
  "sduiRequests": [
    {
      object (SduiRequest)
    }
  ]
}
Fields
response

string

The agent's response to the user query.
visualizations[]

object (Visualization)

A list of visualizations generated by the agent.
sduiRequests[]

object (SduiRequest)

Output only. The SDUI requests for UI widgets. The number of elements is limited to 100.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • databaseinsights.virtualDbxAgent.query

For more information, see the IAM documentation.

DatabaseChatContext

JSON representation 
{
  "taskCompletionRequest": {
    object (TaskCompletionRequest)
  }
}
Fields
taskCompletionRequest

object (TaskCompletionRequest)

The task completion request to be used for the database chat.

TaskCompletionRequest

Input for task completion.

JSON representation 
{
  "messageId": string,
  "topic": string,
  "contents": [
    {
      object (TaskCompletionContent)
    }
  ],
  "instance": string,
  "input": {
    object (TaskCompletionInput)
  },
  "experienceContext": {
    object (ExperienceContext)
  },
  "inputDataContext": {
    object (InputDataContext)
  },
  "clientContext": {
    object (ClientContext)
  },
  "backendResourcesContext": {
    object (BackendResourcesContext)
  }
}
Fields
messageId

string

Optional. An ID for this TaskCompletionRequest, used for persistence and for correlating it with the TaskCompletionResponse received from the Agent (the response carries the id of the TaskCompletionRequests it consumed).

  • If the 'topic' field is set, a Message object wrapping this TaskCompletionRequest is created under the specified Topic and persisted with this ID (if it's not set, the ID will be generated server-side). The persisted Message objects in a Topic can be retrieved using the MessageService API.
  • If the 'topic' field is not set, this TaskCompletionRequest is not persisted and messageId is a no-op.

To update a previously persisted message, set the 'topic' field and the 'messageId' field to the same value, while changing the contents. Only the last request to the Agent in the Topic can be updated. Updating the request will cause all its responses to be recreated.
topic

string

Optional. The topic to file this message under. Format: projects/*/locations/*/topics/{topic_id}

Setting this field implies an intent to persist messages. The entire request fails if this field is set but the user doesn't have the IAM permissions to persist messages. The value of this field is ignored if the 'instance' resource associated with the API call does not have storage option set.
contents[]

object (TaskCompletionContent)

Optional. Content of the task completion/chat input. This field is used to replace the input field above. It is repeated because it can contain the history of the conversation. Most recent content is the last element of the list.
instance

string

Required. The full name of the Instance resource for this generation request. Format: projects/{project}/locations/{location}/instances/{instance} Use the special 'default' name to refer to the default instance.
input

object (TaskCompletionInput)

Optional. Represents the raw input for inference. It will be modified as part of prompt engineering and other transforms before it is consumed by the LLM. Deprecated. Use contents field instead for multimodal input.
experienceContext

object (ExperienceContext)

Duet product context -- required
inputDataContext

object (InputDataContext)

Optional. Additional user content not captured in the input field above
clientContext

object (ClientContext)

Optional. Client context (e.g. IDE name, version, etc)
backendResourcesContext

object (BackendResourcesContext)

Optional. The GCP resources that the code generation process needs to reference

TaskCompletionInput

Natural language messages making up the task completion conversation.

JSON representation 
{
  "messages": [
    {
      object (TaskCompletionMessage)
    }
  ],
  "preamble": string
}
Fields
messages[]

object (TaskCompletionMessage)

Optional. Last few messages of the conversation. The most recent message is the last element in the list.
preamble

string

Optional. Preamble for the task completion conversation.

TaskCompletionMessage

Represents a single message.

JSON representation 
{
  "content": string,
  "author": string
}
Fields
content

string

Optional. Text content of the task completion/chat message.
author

string

Optional. Author tag for the turn.

TaskCompletionContent

Content of the task completion/chat input.

JSON representation 
{
  "parts": [
    {
      object (Part)
    }
  ],
  "role": string
}
Fields
parts[]

object (Part)

Required. The parts of the content.
role

string

Required. Either "user" or "model".

Part

A part of the content.

JSON representation 
{

  // Union field data can be only one of the following:
  "text": string,
  "inlineData": {
    object (Blob)
  }
  // End of list of possible types for union field data.
}
Fields
Union field data. The data of the part. data can be only one of the following:
text

string

Optional. Text content.
inlineData

object (Blob)

Optional. Inline blob content.

Blob

Content blob.

JSON representation 
{
  "mimeType": string,
  "data": string
}
Fields
mimeType

string

Required. The MIME type of the blob.
data

string (bytes format)

Required. The raw bytes of the blob.

A base64-encoded string.

ExperienceContext

The specific Duet product and flow a request belongs to. E.g. Appsheet code generation (“/appsheet/generate”).

JSON representation 
{
  "agent": string,
  "task": string,
  "experience": string
}
Fields
agent

string

Optional. The Backend Agent to route this request to (if known).
task

string

Optional. The backend Task(s) this request maps to (if known).
experience

string

Required. The Duet experience that this request belongs to.

InputDataContext

Intended to hold customer content over and above what is present in the input field.

JSON representation 
{
  "additionalContext": {
    "@type": string,
    field1: ...,
    ...
  }
}
Fields
additionalContext

object

Optional. Represents additional customer content over the input field.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

ClientContext

Represents context about the UI client. Must NOT contain customer content.

JSON representation 
{
  "additionalContext": {
    "@type": string,
    field1: ...,
    ...
  },
  "name": string,
  "version": string
}
Fields
additionalContext

object

Optional. Represents GCP product-specific UI/client context.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.
name

string

Optional. Name of the Duet plugin/UI running in the client space
version

string

Optional. Duet plugin/UI version

BackendResourcesContext

Represents ids of resources that the operation needs to reference or target. E.g. for BigQuery SQL generation, this could reference the Dataset or Table names (go/backend-resources-context-eg).

JSON representation 
{
  "fullResourceNames": [
    string
  ],
  "additionalContext": {
    "@type": string,
    field1: ...,
    ...
  }
}
Fields
fullResourceNames[]

string

The full resource names (https://cloud.google.com/apis/design/resourceNames) of the GCP resources that are referenced or relevant to the Duet query. For example, a BigQuery SQL generation in the context of a particular BigQuery table would set this to: //bigquery.googleapis.com/bigquery/v2/projects/{projectId}/datasets/{datasetId}/tables/{tableId}
additionalContext

object

Optional. Represents GCP product-specific backend resources context.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

AgentOptions

Options for processing the request on the agent.

JSON representation 
{
  "visualizationDisabled": boolean
}
Fields
visualizationDisabled

boolean

Optional. If true, visualizations are disabled in the agent response.

Visualization

Represents a visualization generated by the agent.

JSON representation 
{
  "summary": string,
  "visualizationType": enum (VisualizationType),

  // Union field data can be only one of the following:
  "promqlQuery": string
  // End of list of possible types for union field data.
}
Fields
summary

string

A summary or description of the visualization.
visualizationType

enum (VisualizationType)

The type of the visualization.
Union field data. The data for the visualization. data can be only one of the following:
promqlQuery

string

The PromQL query string for a PROMQL_QUERY type visualization. See: https://prometheus.io/docs/prometheus/latest/querying/basics/

VisualizationType

The type of the visualization. New values may be added in the future.

Enums
VISUALIZATION_TYPE_UNSPECIFIED The default value. This value is unused.
PROMQL_QUERY The visualization is a PromQL query.

SduiRequest

Client-side request type for GetSdui. See go/cloud-sdui for more details.

JSON representation 
{
  "componentId": string,
  "sduiService": string,
  "payload": {
    object
  },
  "description": string
}
Fields
componentId

string

Required unique identifier for the SDUI component.
sduiService

string

The name of the SduiService to send the request to.
payload

object (Struct format)

Payload to the SDUI component.
description

string

The description of the SDUI component. To be used for LLM context.