google.cloud.gcp_vertexai_reasoning_engine module – Manages a VertexAI.ReasoningEngine resource
Note
This module is part of the google.cloud collection (version 1.15.0).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install google.cloud.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: google.cloud.gcp_vertexai_reasoning_engine.
Synopsis
ReasoningEngine provides a customizable runtime for models to determine which actions to take and in which order.
Requirements
The below requirements are needed on the host that executes this module.
python >= 3.8
requests >= 2.18.4
google-auth >= 2.25.1
Parameters
Parameter |
Comments |
|---|---|
The access token used to authenticate. |
|
The type of credential used. Choices:
|
|
Configuration for how Agent Engine sub-resources should manage context. |
|
Specification for an Example Store, which manages few-shot examples for the Agent Engine. |
|
Configuration for how to perform similarity search on examples. |
|
The Gemini model used to generate embeddings to lookup similar examples. |
|
Specification for a Memory Bank, which manages memories for the Agent Engine. |
|
Customization configs for how Agent Engine sub-resources manage context at different scope levels. |
|
Configuration for how many memory revisions Memory Bank considers when consolidating each memory candidate. |
|
Number of revisions to consider per candidate count. |
|
Indicates whether natural language memory generation should be disabled. Choices:
|
|
Generate memories in the third person if set to true. Choices:
|
|
Provides examples of how to generate memories for a particular scope. |
|
A conversation source for the example. |
|
Represents the input conversation events for the example. |
|
Represents the content of the event. |
|
A list of Part objects that make up a single message. |
|
Audio (input or output) transcription. This is only set when this Part contains audio data. |
|
A label identifying the speaker of this audio segment (e.g. spk_1, spk_2). Present when diarization is set. |
|
The transcription text of this audio segment. |
|
Detailed word-level transcriptions and timing details. Present when word_timestamp is set. |
|
End offset in time of the word relative to the start of the audio. |
|
Start offset in time of the word relative to the start of the audio. |
|
Transcript of the word. |
|
Result of executing the ExecutableCode. |
|
The identifier of the ExecutableCode part this result is for. |
|
Outcome of the code execution. Possible values: [“OUTCOME_UNSPECIFIED”, “OUTCOME_OK”, “OUTCOME_FAILED”, “OUTCOME_DEADLINE_EXCEEDED”]. |
|
Contains stdout when code execution is successful, stderr or other description otherwise. |
|
Code generated by the model that is intended to be executed. |
|
The code to be executed. |
|
Unique identifier of the ExecutableCode part. |
|
Supported programming languages for the generated code. Possible values: [“LANGUAGE_UNSPECIFIED”, “PYTHON”, “BASH”]. |
|
URI based data. |
|
The URI of the file in Google Cloud Storage. |
|
The IANA standard MIME type of the source data. |
|
A predicted function call returned from the model. |
|
The function parameters and values in JSON object format. |
|
The unique id of the function call. |
|
The name of the function to call. |
|
The result of a function call. |
|
The id of the function call this response is for. |
|
The name of the function to call. |
|
The function response in JSON object format. |
|
The inline data content of the part. |
|
Raw bytes, which should be base64-encoded. |
|
The IANA standard MIME type of the source data. |
|
The text content of the part. |
|
Indicates whether the part represents the model’s thought process or reasoning. Choices:
|
|
Video metadata. |
|
The end offset of the video. |
|
The start offset of the video. |
|
The producer of the content. Must be either ‘user’ or ‘model’. If not set, the service will default to ‘user’. |
|
Represents the memories that are expected to be generated from the input conversation. |
|
Represents the fact to generate a memory from. |
|
Represents the list of topics that the memory should be associated with. |
|
Represents the custom memory topic label. |
|
Represents the managed memory topic. Possible values: [“USER_PERSONAL_INFO”, “USER_PREFERENCES”, “KEY_CONVERSATION_DETAILS”, “EXPLICIT_INSTRUCTIONS”]. |
|
List of topics that the memory should be associated with. |
|
Custom memory topic. |
|
Description of custom memory topic. |
|
Label of custom memory topic. |
|
Managed memory topic. |
|
Managed topic enum (e.g. USER_PREFERENCES, EXPLICIT_INSTRUCTIONS). |
|
List of scope keys that this customization config applies to. |
|
If true, no memory revisions will be created for any requests to the Memory Bank. Choices:
|
|
Configuration for how to generate memories for the Memory Bank. |
|
Configuration for triggering memory generation. |
|
The active rule that determines when to flush the buffer. If not set, then the stream will be force flushed immediately. |
|
Specifies to trigger generation when the event count reaches this limit. |
|
Specifies to trigger generation at a fixed interval. The duration must have a minute-level granularity. |
|
Specifies to trigger generation if the stream is inactive for the specified duration after the most recent event. The duration must have a minute-level granularity. |
|
Re-include the last N already-processed events in the next window. |
|
The model used to generate memories. Format: projects/{project}/locations/{location}/publishers/google/models/{model}. |
|
Configuration for how to perform similarity search on memories. |
|
The model used to generate embeddings to lookup similar memories. Format: projects/{project}/locations/{location}/publishers/google/models/{model}. |
|
Structured memory configurations for Agent Engine sub-resources. |
|
List of schema configs that this structured memory config applies to. |
|
Unique ID identifying the memory schema. |
|
The memory schema defined as an OpenAPI Schema Object JSON string. |
|
List of scope keys that this structured memory config applies to. |
|
Configuration for automatic TTL (“time-to-live”) of the memories in the Memory Bank. |
|
The default TTL duration of the memories in the Memory Bank. |
|
The granular TTL configuration of the memories in the Memory Bank. |
|
The TTL duration for memories uploaded via CreateMemory. |
|
The TTL duration for memories newly generated via GenerateMemories. |
|
The TTL duration for memories updated via GenerateMemories. |
|
The default TTL duration of the memory revisions in the Memory Bank. |
|
The description of the ReasoningEngine. |
|
The display name of the ReasoningEngine. |
|
Customer-managed encryption key spec for a ReasoningEngine. If set, this ReasoningEngine and all sub-resources of this ReasoningEngine will be secured by this key. This property is immutable, to change it, you must delete and recreate the resource. |
|
The Cloud KMS resource identifier of the customer managed encryption key used to protect a resource. Has the form: projects/my-project/locations/my-region/keyRings/my-kr/cryptoKeys/my-key. The key needs to be in the same region as where the compute resource is created. |
|
Specifies which Ansible environment you’re running this module within. This should not be set unless you know what you’re doing. This only alters the User Agent string for any API requests. |
|
The labels associated with this ReasoningEngine. You can use these to organize and group your ReasoningEngines. **Note**: This field is non-authoritative, and will only manage the labels present in your configuration. |
|
The Google Cloud Platform project to use. |
|
The region of the reasoning engine. eg us-central1. This property is immutable, to change it, you must delete and recreate the resource. |
|
Array of scopes to be used. |
|
The contents of a Service Account JSON file, either in a dictionary or as a JSON string that represents it. |
|
An optional service account email address if machineaccount is selected and the user does not wish to use the default email. |
|
The path of a Service Account JSON file if serviceaccount is selected as type. |
|
Configurations of the ReasoningEngine. |
|
The A2A Agent Card for the agent (if available). |
|
The OSS agent framework used to develop the agent. |
|
Configuration for building container image. |
|
The service account that the Cloud Build builder runs as. |
|
The resource name of the Cloud Build WorkerPool to use for the build. |
|
Declarations for object class methods in OpenAPI specification format. **Note**: When deploying via Terraform, this field must be populated manually. Otherwise, client SDKs (like `agent_engines.get()`) will not be able to discover the methods, and calls to the engine (or A2A integrations) will fail. Depending on the template/framework used (`agent_framework`), the required class methods and their parameters differ: **Warning**: The configuration snippets below are illustrative, may not be exhaustive, and could stop working over time. For the most up-to-date method lists and schemas, please consult the respective SDK source code: * For Google ADK: See [ADK Python SDK cli_deploy.py](https://github.com/google/adk-python/blob/68a780306e3bdd648a882ef34c0abf8e5148353e/src/google/adk/cli/cli_deploy.py#L109). * For Langchain: See [Vertex AI Python SDK langchain.py](https://github.com/googleapis/python-aiplatform/blob/c8a38a085931b01f4d6071f0ab7a64cb42851829/agentplatform/agent_engines/templates/langchain.py#L642-L717). ### 1. Langchain Template * `query` (api_mode = “sync” or empty) * `stream_query` (api_mode = “stream”) Example for Langchain: ```hcl class_methods = jsonencode([ { name = “query” api_mode = “sync” description = “Queries the reasoning engine” parameters = { type = “object” required = [“input”] properties = { input = { type = “string” description = “The input prompt” } } } }, { name = “stream_query” api_mode = “stream” description = “Streams queries from the reasoning engine” parameters = { type = “object” required = [“input”] properties = { input = { type = “string” description = “The input prompt” } } } } ]) ``` ### 2. Google ADK Template (Standard - No A2A) For standard Google ADK (Agent Development Kit) deployments, you must define the following 11 methods: Example for Standard ADK: ```hcl class_methods = jsonencode([ { name = “get_session” api_mode = “” description = “Retrieve session by ID” parameters = { type = “object” required = [“user_id”, “session_id”] properties = { user_id = { type = “string” } session_id = { type = “string” } } } }, { name = “async_get_session” api_mode = “async” description = “Retrieve session asynchronously by ID” parameters = { type = “object” required = [“user_id”, “session_id”] properties = { user_id = { type = “string” } session_id = { type = “string” } } } }, { name = “list_sessions” api_mode = “” description = “List all sessions for a user” parameters = { type = “object” required = [“user_id”] properties = { user_id = { type = “string” } } } }, { name = “async_list_sessions” api_mode = “async” description = “List all sessions for a user asynchronously” parameters = { type = “object” required = [“user_id”] properties = { user_id = { type = “string” } } } }, { name = “create_session” api_mode = “” description = “Create a new session” parameters = { type = “object” required = [“user_id”] properties = { user_id = { type = “string” } session_id = { type = “string” } state = { type = “object” } } } }, { name = “async_create_session” api_mode = “async” description = “Create a new session asynchronously” parameters = { type = “object” required = [“user_id”] properties = { user_id = { type = “string” } session_id = { type = “string” } state = { type = “object” } } } }, { name = “delete_session” api_mode = “” description = “Delete session by ID” parameters = { type = “object” required = [“user_id”, “session_id”] properties = { user_id = { type = “string” } session_id = { type = “string” } } } }, { name = “async_delete_session” api_mode = “async” description = “Delete session asynchronously by ID” parameters = { type = “object” required = [“user_id”, “session_id”] properties = { user_id = { type = “string” } session_id = { type = “string” } } } }, { name = “stream_query” api_mode = “stream” description = “Stream queries from the agent” parameters = { type = “object” required = [“message”, “user_id”] properties = { message = { description = “Message string or object” } user_id = { type = “string” } session_id = { type = “string” } run_config = { type = “object” } } } }, { name = “async_stream_query” api_mode = “async_stream” description = “Stream queries asynchronously from the agent” parameters = { type = “object” required = [“message”, “user_id”] properties = { message = { description = “Message string or object” } user_id = { type = “string” } session_id = { type = “string” } session_events = { type = “array”, items = { type = “object” } } run_config = { type = “object” } } } }, { name = “streaming_agent_run_with_events” api_mode = “async_stream” description = “Stream agent run with events asynchronously” parameters = { type = “object” required = [“request_json”] properties = { request_json = { type = “string” } } } } ]) ``` ### 3. Google ADK Template (A2A-Enabled) If the agent integrates with the Gemini Enterprise Agent Registry (A2A), you must inject the `a2a_agent_card` JSON metadata as a string **specifically inside the `async_create_session` method definition**: Example for A2A-Enabled ADK: ```hcl locals { # Construct the A2A endpoint URL a2a_url = “https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1/reasoningEngines/my-agent/a2a” agent_card = { name = “my-agent” description = “A2A Agent” version = “1.0.0” preferred_transport = “HTTP_JSON” supported_interfaces = [{ url = local.a2a_url, protocol_binding = “HTTP_JSON” }] capabilities = { streaming = true } } } # In class_methods, append “a2a_agent_card” key ONLY to the “async_create_session” method: class_methods = jsonencode([ # .. other 10 standard methods (same as Standard ADK) .. { name = “async_create_session” api_mode = “async” description = “Create a new session asynchronously” parameters = { type = “object” required = [“user_id”] properties = { user_id = { type = “string” } session_id = { type = “string” } state = { type = “object” } } } # Inject the serialized Agent Card here a2a_agent_card = jsonencode(local.agent_card) } ]) ```. |
|
Deploy from a container image with a defined entrypoint and commands. |
|
The Artifact Registry Docker image URI (e.g., `us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag`) of the container image that is to be run on each worker replica. |
|
The port that the container listens on for incoming requests. If not specified, defaults to 8080. |
|
The specification of a Reasoning Engine deployment. |
|
Agent Gateway configuration for a Reasoning Engine deployment. |
|
Configuration for traffic originating from the Reasoning Engine. |
|
The resource name of the Agent Gateway for outbound traffic. |
|
Configuration for traffic targeting the Reasoning Engine. |
|
The resource name of the Agent Gateway to use for inbound traffic. |
|
The agent server mode specifies what features are used when deploy the agent to agent engine. Possible values: * `STABLE`: Stable agent server mode. * `EXPERIMENTAL`: Experimental agent server mode. Choices:
|
|
Concurrency for each container and agent server. Recommended value: 2 * cpu + 1. Defaults to 9. |
|
Whether to enable dedicated ingress endpoint for the deployment. If true, the deployment will be accessible via a dedicated endpoint. This is required to enable GKE V2 runtime. Choices:
|
|
Environment variables to be set with the Reasoning Engine deployment. |
|
The name of the environment variable. Must be a valid C identifier. |
|
Variables that reference a $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. |
|
Specifies the configuration for keep-alive probe. |
|
Specifies the HTTP GET configuration for the probe. |
|
Specifies the path of the HTTP GET request (e.g., `”/is_busy”`). |
|
Specifies the port number on the container to which the request is sent. |
|
Specifies the maximum duration (in seconds) to keep the instance alive via this probe. Can be a maximum of 3600 seconds (1 hour). |
|
The maximum number of application instances that can be launched to handle increased traffic. Defaults to 100. Range: [1, 1000]. If VPC-SC or PSC-I is enabled, the acceptable range is [1, 100]. |
|
The minimum number of application instances that will be kept running at all times. Defaults to 1. Range: [0, 10]. |
|
Configuration for PSC-Interface. |
|
DNS peering configurations. When specified, Vertex AI will attempt to configure DNS peering zones in the tenant project VPC to resolve the specified domains using the target network’s Cloud DNS. The user must grant the dns.peer role to the Vertex AI service Agent on the target project. |
|
The DNS name suffix of the zone being peered to, e.g., “my-internal-domain.corp.”. Must end with a dot. |
|
The VPC network name in the targetProject where the DNS zone specified by ‘domain’ is visible. |
|
The project id hosting the Cloud DNS managed zone that contains the ‘domain’. The Vertex AI service Agent requires the dns.peer role on this project. |
|
The name of the Compute Engine network attachment to attach to the resource within the region and user project. To specify this field, you must have already created a network attachment. This field is only used for resources using PSC-Interface. |
|
Resource limits for each container. Only ‘cpu’ and ‘memory’ keys are supported. Defaults to {“cpu”: “4”, “memory”: “4Gi”}. The only supported values for CPU are ‘1’, ‘2’, ‘4’, ‘6’ and ‘8’. For more information, go to https://cloud.google.com/run/docs/configuring/cpu. The only supported values for memory are ‘1Gi’, ‘2Gi’, .. ‘32 Gi’. For more information, go to https://cloud.google.com/run/docs/configuring/memory-limits. |
|
Environment variables where the value is a secret in Cloud Secret Manager. To use this feature, add ‘Secret Manager Secret Accessor’ role (roles/secretmanager.secretAccessor) to AI Platform Reasoning Engine service Agent. |
|
The name of the environment variable. Must be a valid C identifier. |
|
Reference to a secret stored in the Cloud Secret Manager that will provide the value for this environment variable. |
|
The name of the secret in Cloud Secret Manager. Format: {secret_name}. |
|
The Cloud Secret Manager secret version. Can be ‘latest’ for the latest version, an integer for a specific version, or a version alias. |
|
The identity to use for the Reasoning Engine. |
|
The resource name of the linked ExampleStore. |
|
The identity type to use for the Reasoning Engine. If not specified, the `service_account` field will be used if set, otherwise the default Vertex AI Reasoning Engine Service Agent in the project will be used. Possible values: * `SERVICE_ACCOUNT`: Use a custom service account if the `service_account` field is set, otherwise use the default Vertex AI Reasoning Engine Service Agent in the project. * `AGENT_IDENTITY`: Use Agent Identity. The `service_account` field must not be set. Choices:
|
|
User provided package spec of the ReasoningEngine. Ignored when users directly specify a deployment image through deploymentSpec.first_party_image_override, but keeping the field_behavior to avoid introducing breaking changes. |
|
The Cloud Storage URI of the dependency files in tar.gz format. |
|
The Cloud Storage URI of the pickled python object. |
|
The Python version. Currently support 3.8, 3.9, 3.10, 3.11, 3.12, 3.13. If not specified, default value is 3.10. |
|
The Cloud Storage URI of the requirements.txtfile. |
|
The service account that the Reasoning Engine artifact runs as. It should have “roles/storage.objectViewer” for reading the user project’s Cloud Storage and “roles/aiplatform.user” for using Vertex extensions. If not specified, the Vertex AI Reasoning Engine service Agent in the project will be used. |
|
Specification for deploying from source code. |
|
Specification for the deploying from agent config. |
|
Configuration for the Agent Development Kit (ADK). |
|
The value of the ADK config in JSON format. |
|
Any additional files needed to interpret the config. |
|
Input only. The application source code archive, provided as a compressed tarball (.tar.gz) file. |
|
Specification for source code to be fetched from a Git repository managed through the Developer Connect service. |
|
The Developer Connect configuration that defines the specific repository, revision, and directory to use as the source code root. |
|
Directory, relative to the source root, in which to run the build. |
|
The Developer Connect Git repository link, formatted as projects/*/locations/*/connections/*/gitRepositoryLink/*. |
|
The revision to fetch from the Git repository such as a branch, a tag, a commit SHA, or any Git ref. |
|
Configuration for building an image with custom config file. |
|
Build arguments to be used. They will be passed through --build-arg flags. |
|
Source code is provided directly in the request. |
|
Input only. The application source code archive, provided as a compressed tarball (.tar.gz) file. A base64-encoded string. |
|
Specification for running a Python application from source. |
|
The Python module to load as the entrypoint, specified as a fully qualified module name. For example: path.to.agent. If not specified, defaults to “agent”. The project root will be added to Python sys.path, allowing imports to be specified relative to the root. |
|
The name of the callable object within the entrypointModule to use as the application If not specified, defaults to “root_agent”. |
|
The path to the requirements file, relative to the source root. If not specified, defaults to “requirements.txt”. |
|
The version of Python to use. Support version includes 3.9, 3.10, 3.11, 3.12, 3.13. If not specified, default value is 3.10. |
|
Whether the resource should exist. Choices:
|
|
Traffic distribution configuration for the Reasoning Engine. ~> **Note:** Because revision IDs do not exist before the resource is created, the best practice for initial deployment is to set `traffic_split_always_latest {}`. Once the resource is created, you can update the configuration to a manual split using newly generated revision IDs, short names (e.g. `rev-1`), or keywords such as `LATEST` and `PREVIOUS`. |
|
Traffic distribution configuration, where all traffic is sent to the latest Runtime Revision. |
|
Manual traffic distribution configuration, where the user specifies the Runtime Revision IDs and the percentage of traffic to send to each. |
|
A list of traffic targets for the Runtimes Revisions. The sum of percentages must equal to 100. |
|
Specifies percent of the traffic to this Runtime Revision. |
|
The Runtime Revision name to which to send this portion of traffic. Accepts revision IDs, short names (e.g. `rev-1`), or keywords such as `LATEST` and `PREVIOUS`. Note: Keywords like `LATEST` and `PREVIOUS` resolve at apply time to the concrete underlying revision ID and remain pinned until `traffic_config` is updated in Terraform. |
Notes
Note
API Reference: https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/rest/v1/projects.locations.reasoningEngines
Scale your agents Guide: https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale
For authentication, you can set auth_kind using the
GCP_AUTH_KINDenv variable.For authentication, you can set service_account_file using the
GCP_SERVICE_ACCOUNT_FILEenv variable.For authentication, you can set service_account_contents using the
GCP_SERVICE_ACCOUNT_CONTENTSenv variable.For authentication, you can set service_account_email using the
GCP_SERVICE_ACCOUNT_EMAILenv variable.For authentication, you can set access_token using the
GCP_ACCESS_TOKENenv variable.For authentication, you can set scopes using the
GCP_SCOPESenv variable.Environment variables values will only be used if the playbook values are not set.
The
service_account_email,service_account_file,service_account_fileandaccess_tokenoptions are mutually exclusive.
Examples
- name: Create Basic Reasoning Engine
google.cloud.gcp_vertexai_reasoning_engine:
state: present
display_name: basic-reasoning-engine
description: A Basic Reasoning Engine
region: us-central1
################################################################################
- name: Create Source Based Deployment Reasoning Engine
google.cloud.gcp_vertexai_reasoning_engine:
state: present
display_name: source-based-deployment-reasoning-engine
description: A Source Based Deployment Reasoning Engine
region: us-central1
spec:
source_code_spec:
inline_source:
source_archive: "{{ slurped_tarball.content }}" # slurp already returns b64
# source_archive: "{{ some_other_b64_encoded_string }}"
python_spec:
entrypoint_module: my_agent
entrypoint_object: name_generator
requirements_file: prod-requirements.txt # defaults to requirements.txt
version: "3.11"
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Whether the resource was changed. Returned: always |
|
The timestamp of when the Index was created in RFC3339 UTC “Zulu” format, with nanosecond resolution and up to nine fractional digits. Returned: success |
|
The generated name of the ReasoningEngine, in the format projects/{project}/locations/{location}/reasoningEngines/{reasoningEngine}. Returned: success |
|
The current state of the resource. Returned: always |
|
The timestamp of when the Index was last updated in RFC3339 UTC “Zulu” format, with nanosecond resolution and up to nine fractional digits. Returned: success |
|
Output only. The URL of the reasoning engine. Returned: success |