SessionEvent

An event represents a message from either the user or agent.

Fields
namestring

Identifier. The resource name of the event. Format:projects/{project}/locations/{location}/reasoningEngines/{reasoningEngine}/sessions/{session}/events/{event}.

authorstring

Required. The name of the agent that sent the event, or user.

contentobject (Content)

Optional. Content of the event provided by the author.

invocationIdstring

Required. The invocation id of the event, multiple events can have the same invocation id.

actionsobject (EventActions)

Optional. Actions executed by the agent.

timestampstring (Timestamp format)

Required. timestamp when the event was created on client side.

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".

errorCodestring

Optional. Error code if the response is an error. code varies by model.

errorMessagestring

Optional. Error message if the response is an error.

eventMetadataobject (EventMetadata)

Optional. metadata relating to this event.

JSON representation
{"name":string,"author":string,"content":{object (Content)},"invocationId":string,"actions":{object (EventActions)},"timestamp":string,"errorCode":string,"errorMessage":string,"eventMetadata":{object (EventMetadata)}}

EventActions

Actions are parts of events that are executed by the agent.

Fields
skipSummarizationboolean

Optional. If true, it won't call model to summarize function response. Only used for functionResponse event.

stateDeltaobject (Struct format)

Optional. Indicates that the event is updating the state with the given delta.

artifactDeltamap (key: string, value: integer)

Optional. Indicates that the event is updating an artifact. key is the filename, value is the version.

escalateboolean

Optional. The agent is escalating to a higher level agent.

requestedAuthConfigsobject (Struct format)

Optional. Will only be set by a tool response indicating tool request euc. Struct key is the function call id since one function call response (from model) could correspond to multiple function calls. Struct value is the required auth config, which can be another struct.

transferAgentstring

Optional. If set, the event transfers to the specified agent.

JSON representation
{"skipSummarization":boolean,"stateDelta":{object},"artifactDelta":{string:integer,...},"escalate":boolean,"requestedAuthConfigs":{object},"transferAgent":string}

EventMetadata

metadata relating to a LLM response event.

Fields
groundingMetadataobject (GroundingMetadata)

Optional. metadata returned to client when grounding is enabled.

partialboolean

Optional. Indicates whether the text content is part of a unfinished text stream. Only used for streaming mode and when the content is plain text.

turnCompleteboolean

Optional. Indicates whether the response from the model is complete. Only used for streaming mode.

interruptedboolean

Optional. Flag indicating that LLM was interrupted when generating the content. Usually it's due to user interruption during a bidi streaming.

longRunningToolIds[]string

Optional. Set of ids of the long running function calls. Agent client will know from this field about which function call is long running. Only valid for function call event.

branchstring

Optional. The branch of the event. The format is like agent_1.agent_2.agent_3, where agent_1 is the parent of agent_2, and agent_2 is the parent of agent_3. Branch is used when multiple child agents shouldn't see their siblings' conversation history.

customMetadataobject (Struct format)

The custom metadata of the LlmResponse.

JSON representation
{"groundingMetadata":{object (GroundingMetadata)},"partial":boolean,"turnComplete":boolean,"interrupted":boolean,"longRunningToolIds":[string],"branch":string,"customMetadata":{object}}

GroundingMetadata

Information about the sources that support the content of a response.

When grounding is enabled, the model returns citations for claims in the response. This object contains the retrieved sources.

Fields
webSearchQueries[]string

Optional. The web search queries that were used to generate the content. This field is populated only when the grounding source is Google Search.

retrievalQueries[]string

Optional. The queries that were executed by the retrieval tools. This field is populated only when the grounding source is a retrieval tool, such as Vertex AI Search.

groundingChunks[]object (GroundingChunk)

A list of supporting references retrieved from the grounding source. This field is populated when the grounding source is Google Search, Vertex AI Search, or Google Maps.

groundingSupports[]object (GroundingSupport)

Optional. A list of grounding supports that connect the generated content to the grounding chunks. This field is populated when the grounding source is Google Search or Vertex AI Search.

sourceFlaggingUris[]object (SourceFlaggingUri)

Optional. Output only. A list of URIs that can be used to flag a place or review for inappropriate content. This field is populated only when the grounding source is Google Maps.

searchEntryPointobject (SearchEntryPoint)

Optional. A web search entry point that can be used to display search results. This field is populated only when the grounding source is Google Search.

retrievalMetadataobject (RetrievalMetadata)

Optional. Output only. metadata related to the retrieval grounding source.

googleMapsWidgetContextTokenstring

Optional. Output only. A token that can be used to render a Google Maps widget with the contextual data. This field is populated only when the grounding source is Google Maps.

JSON representation
{"webSearchQueries":[string],"retrievalQueries":[string],"groundingChunks":[{object (GroundingChunk)}],"groundingSupports":[{object (GroundingSupport)}],"sourceFlaggingUris":[{object (SourceFlaggingUri)}],"searchEntryPoint":{object (SearchEntryPoint)},"retrievalMetadata":{object (RetrievalMetadata)},"googleMapsWidgetContextToken":string}

SearchEntryPoint

An entry point for displaying Google Search results.

ASearchEntryPoint is populated when the grounding source for a model's response is Google Search. It provides information that you can use to display the search results in your application.

Fields
renderedContentstring

Optional. An HTML snippet that can be embedded in a web page or an application's webview. This snippet displays a search result, including the title, URL, and a brief description of the search result.

sdkBlobstring (bytes format)

Optional. A base64-encoded JSON object that contains a list of search queries and their corresponding search URLs. This information can be used to build a custom search UI.

A base64-encoded string.

JSON representation
{"renderedContent":string,"sdkBlob":string}

GroundingChunk

A piece of evidence that supports a claim made by the model.

This is used to show a citation for a claim made by the model. When grounding is enabled, the model returns aGroundingChunk that contains a reference to the source of the information.

Fields
chunk_typeUnion type
The source of the grounding chunk, which can be from Google Search, Vertex AI Search, or Google Maps.chunk_type can be only one of the following:
webobject (Web)

A grounding chunk from a web page, typically from Google Search. See theWeb message for details.

retrievedContextobject (RetrievedContext)

A grounding chunk from a data source retrieved by a retrieval tool, such as Vertex AI Search. See theRetrievedContext message for details

mapsobject (Maps)

A grounding chunk from Google Maps. See theMaps message for details.

JSON representation
{// chunk_type"web":{object (Web)},"retrievedContext":{object (RetrievedContext)},"maps":{object (Maps)}// Union type}

Web

AWeb chunk is a piece of evidence that comes from a web page. It contains the URI of the web page, the title of the page, and the domain of the page. This is used to provide the user with a link to the source of the information.

Fields
uristring

The URI of the web page that contains the evidence.

titlestring

The title of the web page that contains the evidence.

domainstring

The domain of the web page that contains the evidence. This can be used to filter out low-quality sources.

JSON representation
{"uri":string,"title":string,"domain":string}

RetrievedContext

Context retrieved from a data source to ground the model's response. This is used when a retrieval tool fetches information from a user-provided corpus or a public dataset.

Fields
context_detailsUnion type
Provides tool-specific details about the retrieved context. This allows for different types of retrieval tools to return their own specific metadata.context_details can be only one of the following:
ragChunkobject (RagChunk)

Additional context for a Retrieval-Augmented Generation (RAG) retrieval result. This is populated only when the RAG retrieval tool is used.

uristring

The URI of the retrieved data source.

titlestring

The title of the retrieved data source.

textstring

The content of the retrieved data source.

documentNamestring

Output only. The full resource name of the referenced Vertex AI Search document. This is used to identify the specific document that was retrieved. The format isprojects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}/branches/{branch}/documents/{document}.

JSON representation
{// context_details"ragChunk":{object (RagChunk)}// Union type"uri":string,"title":string,"text":string,"documentName":string}

Maps

AMaps chunk is a piece of evidence that comes from Google Maps. It contains information about a place, such as its name, address, and reviews. This is used to provide the user with rich, location-based information.

Fields
placeAnswerSourcesobject (PlaceAnswerSources)

The sources that were used to generate the place answer. This includes review snippets and photos that were used to generate the answer, as well as URIs to flag content.

uristring

The URI of the place.

titlestring

The title of the place.

textstring

The text of the place answer.

placeIdstring

This Place's resource name, inplaces/{placeId} format. This can be used to look up the place in the Google Maps API.

JSON representation
{"placeAnswerSources":{object (PlaceAnswerSources)},"uri":string,"title":string,"text":string,"placeId":string}

PlaceAnswerSources

The sources that were used to generate the place answer. This includes review snippets and photos that were used to generate the answer, as well as URIs to flag content.

Fields
reviewSnippets[]object (ReviewSnippet)

Snippets of reviews that were used to generate the answer.

JSON representation
{"reviewSnippets":[{object (ReviewSnippet)}]}

ReviewSnippet

A review snippet that is used to generate the answer.

Fields
reviewIdstring

The id of the review that is being referenced.

googleMapsUristring

A link to show the review on Google Maps.

titlestring

The title of the review.

JSON representation
{"reviewId":string,"googleMapsUri":string,"title":string}

GroundingSupport

A collection of supporting references for a segment of the model's response.

Fields
groundingChunkIndices[]integer

A list of indices into thegroundingChunks field of theGroundingMetadata message. These indices specify which grounding chunks support the claim made in the content segment.

For example, if this field has the values[1, 3], it means thatgroundingChunks[1] andgroundingChunks[3] are the sources for the claim in the content segment.

confidenceScores[]number

The confidence scores for the support references. This list is parallel to thegroundingChunkIndices list. A score is a value between 0.0 and 1.0, with a higher score indicating a higher confidence that the reference supports the claim.

For Gemini 2.0 and before, this list has the same size asgroundingChunkIndices. For Gemini 2.5 and later, this list is empty and should be ignored.

segmentobject (Segment)

The content segment that this support message applies to.

JSON representation
{"groundingChunkIndices":[integer],"confidenceScores":[number],"segment":{object (Segment)}}

Segment

A segment of the content.

Fields
partIndexinteger

Output only. The index of thePart object that this segment belongs to. This is useful for associating the segment with a specific part of the content.

startIndexinteger

Output only. The start index of the segment in thePart, measured in bytes. This marks the beginning of the segment and is inclusive, meaning the byte at this index is the first byte of the segment.

endIndexinteger

Output only. The end index of the segment in thePart, measured in bytes. This marks the end of the segment and is exclusive, meaning the segment includes content up to, but not including, the byte at this index.

textstring

Output only. The text of the segment.

JSON representation
{"partIndex":integer,"startIndex":integer,"endIndex":integer,"text":string}

RetrievalMetadata

metadata related to the retrieval grounding source. This is part of theGroundingMetadata returned when grounding is enabled.

Fields
googleSearchDynamicRetrievalScorenumber

Optional. A score indicating how likely it is that a Google Search query could help answer the prompt. The score is in the range of[0, 1]. A score of 1 means the model is confident that a search will be helpful, and 0 means it is not. This score is populated only when Google Search grounding and dynamic retrieval are enabled. The score is used to determine whether to trigger a search.

JSON representation
{"googleSearchDynamicRetrievalScore":number}

SourceFlaggingUri

A URI that can be used to flag a place or review for inappropriate content. This is populated only when the grounding source is Google Maps.

Fields
sourceIdstring

The id of the place or review.

flagContentUristring

The URI that can be used to flag the content.

JSON representation
{"sourceId":string,"flagContentUri":string}

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-02 UTC.