ReasoningEngine.yaml

# Copyright 2025 Google Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

---
name: 'ReasoningEngine'
description: |-
  ReasoningEngine provides a customizable runtime for models to determine which actions to take and in which order.
references:
  guides:
    'Develop and deploy agents on Vertex AI Agent Engine': 'https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/quickstart'
  api: 'https://cloud.google.com/vertex-ai/docs/reference/rest/v1/projects.locations.reasoningEngines/'
docs:
base_url: 'projects/{{project}}/locations/{{region}}/reasoningEngines'
self_link: 'projects/{{project}}/locations/{{region}}/reasoningEngines/{{name}}'
create_url: 'projects/{{project}}/locations/{{region}}/reasoningEngines'
update_verb: 'PATCH'
update_mask: true
timeouts:
  insert_minutes: 20
  update_minutes: 20
  delete_minutes: 60
async:
  actions: ['create', 'delete', 'update']
  type: 'OpAsync'
  operation:
    base_url: '{{op_id}}'
  result:
    resource_inside_response: true
examples:
  - name: 'vertex_ai_reasoning_engine_deletion_policy'
    primary_resource_id: 'reasoning_engine'
    exclude_docs: true
    vars:
      name: 'reasoning-engine'
    ignore_read_extra:
      - 'deletion_policy'
  - name: 'vertex_ai_reasoning_engine_basic'
    primary_resource_id: 'reasoning_engine'
    exclude_docs: true
    vars:
      name: 'reasoning-engine'
    ignore_read_extra:
      - 'deletion_policy'
  - name: 'vertex_ai_reasoning_engine_source_based_deployment'
    primary_resource_id: 'reasoning_engine'
    vars:
      name: 'reasoning-engine'
    ignore_read_extra:
      - 'deletion_policy'
  - name: 'vertex_ai_reasoning_engine_developer_connect_source'
    skip_docs: true  # skip docs until templatized (or decide to skip docs permanently then)
    primary_resource_id: 'reasoning_engine'
    vars:
      name: 'reasoning-engine'
    ignore_read_extra:
      - 'deletion_policy'
  - name: 'vertex_ai_reasoning_engine_psc_interface'
    primary_resource_id: 'reasoning_engine'
    vars:
      name: 'reasoning-engine'
      bucket_name: 'reasoning-engine'
      network_name: 'network'
      network_attachment_name: 'network-attachment'
      subnetwork_name: 'subnetwork'
    external_providers: ["time"]
    bootstrap_iam:
      - member: "serviceAccount:service-{project_number}@gcp-sa-aiplatform.iam.gserviceaccount.com"
        role: "roles/compute.networkAdmin"
      - member: "serviceAccount:service-{project_number}@gcp-sa-aiplatform.iam.gserviceaccount.com"
        role: "roles/dns.peer"
      - member: "serviceAccount:service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
        role: "roles/viewer"
    exclude_test: true
    ignore_read_extra:
      - 'deletion_policy'
  - name: 'vertex_ai_reasoning_engine_full'
    primary_resource_id: 'reasoning_engine'
    vars:
      name: 'reasoning-engine'
      bucket_name: 'reasoning-engine'
      kms_key_name: 'example-key'
      secret_name: 'secret'
      service_account_id: 'sa'
    bootstrap_iam:
      - member: "serviceAccount:service-{project_number}@gcp-sa-aiplatform.iam.gserviceaccount.com"
        role: "roles/cloudkms.cryptoKeyEncrypterDecrypter"
    test_vars_overrides:
      'kms_key_name': 'acctest.BootstrapKMSKeyWithPurposeInLocationAndName(t, "ENCRYPT_DECRYPT", "us-central1", "tf-bootstrap-re-key1").CryptoKey.Name'
    external_providers: ["time"]
    ignore_read_extra:
      - 'deletion_policy'
  - name: 'vertex_ai_reasoning_engine_context_spec'
    primary_resource_id: 'reasoning_engine'
    min_version: beta
    vars:
      name: 're-ctx-spec'
    ignore_read_extra:
      - 'deletion_policy'
  - name: 'vertex_ai_reasoning_engine_granular_ttl'
    primary_resource_id: 'reasoning_engine'
    min_version: beta
    vars:
      name: 're-gran-ttl'
    ignore_read_extra:
      - 'deletion_policy'
custom_code:
  pre_delete: 'templates/terraform/pre_delete/reasoning_engine_deletion_policy.go.tmpl'
virtual_fields:
  - name: 'deletion_policy'
    description: |
      Optional. The deletion policy for the reasoning engine. Setting this to FORCE allows the reasoning engine to be deleted regardless of child undeleted resources.
    type: Enum
    enum_values:
      - 'FORCE'
parameters:
  - name: 'region'
    type: String
    description: The region of the reasoning engine. eg us-central1
    url_param_only: true
    immutable: true
properties:
  - name: 'name'
    type: String
    description: |-
      The generated name of the ReasoningEngine, in the format
      projects/{project}/locations/{location}/reasoningEngines/{reasoningEngine}
    output: true
    custom_flatten: 'templates/terraform/custom_flatten/name_from_self_link.tmpl'
  - name: 'displayName'
    type: String
    description: The display name of the ReasoningEngine.
    required: true
  - name: 'description'
    type: String
    description: The description of the ReasoningEngine.

  - name: 'createTime'
    type: String
    description: |-
      The timestamp of when the Index was created in RFC3339 UTC "Zulu" format,
      with nanosecond resolution and up to nine fractional digits.
    output: true
  - name: 'updateTime'
    type: String
    description: |-
      The timestamp of when the Index was last updated in RFC3339 UTC "Zulu"
      format, with nanosecond resolution and up to nine fractional digits.
    output: true
  - name: 'encryptionSpec'
    type: NestedObject
    description: |-
      Optional. 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.
    immutable: true
    properties:
      - name: 'kmsKeyName'
        type: String
        description: |-
          Required. 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.
        required: true
  - name: 'spec'
    type: NestedObject
    default_from_api: true
    description: |-
      Optional. Configurations of the ReasoningEngine.
    properties:
      - name: 'agentFramework'
        type: String
        description: |
          Optional. The OSS agent framework used to develop the agent.
      - name: 'classMethods'
        type: String
        description: |
          Optional. Declarations for object class methods in OpenAPI
          specification format.
        state_func: 'func(v interface{}) string { s, _ := structure.NormalizeJsonString(v); return s }'
        custom_flatten: 'templates/terraform/custom_flatten/json_schema.tmpl'
        custom_expand: 'templates/terraform/custom_expand/json_value.tmpl'
        validation:
          function: 'validation.StringIsJSON'
      - name: 'deploymentSpec'
        type: NestedObject
        description: |-
          Optional. The specification of a Reasoning Engine deployment.
        properties:
          - name: 'env'
            type: Array
            description: |-
              Optional. Environment variables to be set with the Reasoning
              Engine deployment.
            is_set: true
            item_type:
              type: NestedObject
              properties:
                - name: 'name'
                  type: String
                  description: |-
                    The name of the environment variable. Must be a valid
                    C identifier.
                  required: true
                - name: 'value'
                  type: String
                  description: |-
                    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.
                  required: true
          - name: 'secretEnv'
            type: Array
            description: |-
              Optional. 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.
            is_set: true
            item_type:
              type: NestedObject
              properties:
                - name: 'name'
                  type: String
                  description: |-
                    The name of the environment variable. Must be a valid C
                    identifier.
                  required: true
                - name: 'secretRef'
                  type: NestedObject
                  description: |-
                    Reference to a secret stored in the Cloud Secret Manager
                    that will provide the value for this environment variable.
                  required: true
                  properties:
                    - name: 'secret'
                      type: String
                      description: |-
                        The name of the secret in Cloud Secret Manager.
                        Format: {secret_name}.
                      required: true
                    - name: 'version'
                      type: String
                      description: |-
                        The Cloud Secret Manager secret version. Can be 'latest'
                        for the latest version, an integer for a specific
                        version, or a version alias.
          - name: 'pscInterfaceConfig'
            type: NestedObject
            description: |-
              Optional. Configuration for PSC-Interface.
            properties:
              - name: 'networkAttachment'
                type: String
                description: |-
                  Optional. 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.
              - name: 'dnsPeeringConfigs'
                type: 'Array'
                description: |
                  Optional. 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.
                item_type:
                  type: NestedObject
                  properties:
                    - name: 'domain'
                      type: String
                      description: |
                        Required. The DNS name suffix of the zone being peered
                        to, e.g., "my-internal-domain.corp.".
                        Must end with a dot.
                      required: true
                    - name: 'targetProject'
                      type: String
                      description: |
                        Required. 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.
                      required: true
                    - name: 'targetNetwork'
                      type: String
                      description: |
                        Required. The VPC network name in the targetProject
                        where the DNS zone specified by 'domain' is visible.
                      required: true
          - name: 'resourceLimits'
            type: KeyValuePairs
            default_from_api: true
            description: |-
              Optional. 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.
          - name: 'minInstances'
            type: 'Integer'
            description: |
              Optional. The minimum number of application instances that will be
              kept running at all times. Defaults to 1. Range: [0, 10].
            default_from_api: true
          - name: 'maxInstances'
            type: 'Integer'
            description: |
              Optional. 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].
            default_from_api: true
          - name: 'containerConcurrency'
            type: 'Integer'
            description: |
              Optional. Concurrency for each container and agent server.
              Recommended value: 2 * cpu + 1. Defaults to 9.
            default_from_api: true
      - name: 'packageSpec'
        type: NestedObject
        description: |-
          Optional. 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.
        properties:
          - name: 'dependencyFilesGcsUri'
            type: String
            description: |
              Optional. The Cloud Storage URI of the dependency files in tar.gz
              format.
          - name: 'pickleObjectGcsUri'
            type: String
            description: |
              Optional. The Cloud Storage URI of the pickled python object.
          - name: 'pythonVersion'
            type: String
            description: |
              Optional. 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.
          - name: 'requirementsGcsUri'
            type: String
            description: |
              Optional. The Cloud Storage URI of the requirements.txtfile
      - name: 'sourceCodeSpec'
        type: NestedObject
        description: |-
          Specification for deploying from source code.
        properties:
          - name: 'inlineSource'
            type: NestedObject
            description: Source code is provided directly in the request.
            ignore_read: true
            properties:
              - name: 'sourceArchive'
                type: String
                description: |
                  Required. Input only.
                  The application source code archive, provided as a compressed
                  tarball (.tar.gz) file. A base64-encoded string.
                ignore_read: true
          - name: 'pythonSpec'
            type: NestedObject
            description: |-
              Specification for running a Python application from source.
            properties:
              - name: 'entrypointModule'
                type: String
                description: |
                  Optional. 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.
              - name: 'entrypointObject'
                type: String
                description: |
                  Optional. The name of the callable object within the
                  entrypointModule to use as the application If not specified,
                  defaults to "root_agent".
              - name: 'requirementsFile'
                type: String
                description: |
                  Optional. The path to the requirements file, relative to the
                  source root. If not specified, defaults to "requirements.txt".
              - name: 'version'
                type: String
                description: |
                  Optional. 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.
          - name: 'developerConnectSource'
            type: NestedObject
            description: |-
              Specification for source code to be fetched from a Git repository managed through the Developer Connect service.
            properties:
              - name: 'config'
                type: NestedObject
                required: true
                description: |-
                  The Developer Connect configuration that defines the specific repository, revision, and directory to use as the source code root.
                properties:
                  - name: 'gitRepositoryLink'
                    type: String
                    required: true
                    description: |
                      The Developer Connect Git repository link, formatted as projects/*/locations/*/connections/*/gitRepositoryLink/*.
                  - name: 'dir'
                    type: String
                    required: true
                    description: |
                      Directory, relative to the source root, in which to run the build.
                  - name: 'revision'
                    type: String
                    required: true
                    description: |
                      The revision to fetch from the Git repository such as a branch, a tag, a commit SHA, or any Git ref.
      - name: 'serviceAccount'
        type: String
        description: |-
          Optional. 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.
      - name: 'identityType'
        type: Enum
        description: |-
          Optional. 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.
        enum_values:
          - 'SERVICE_ACCOUNT'
          - 'AGENT_IDENTITY'
      - name: 'effectiveIdentity'
        type: String
        description: |-
          The identity to use for the Reasoning Engine.
        output: true
  - name: 'contextSpec'
    min_version: 'beta'
    type: NestedObject
    description: |-
      Optional. Configuration for how Agent Engine sub-resources should manage context.
    properties:
      - name: 'memoryBankConfig'
        type: NestedObject
        description: |-
          Specification for a Memory Bank, which manages memories for the Agent Engine.
        properties:
          - name: 'generationConfig'
            type: NestedObject
            description: |-
              Configuration for how to generate memories for the Memory Bank.
            properties:
              - name: 'model'
                type: String
                description: |-
                  The model used to generate memories. Format: projects/{project}/locations/{location}/publishers/google/models/{model}.
                required: true
          - name: 'similaritySearchConfig'
            type: NestedObject
            description: |-
              Configuration for how to perform similarity search on memories.
            properties:
              - name: 'embeddingModel'
                type: String
                description: |-
                  The model used to generate embeddings to lookup similar memories. Format: projects/{project}/locations/{location}/publishers/google/models/{model}.
                required: true
          - name: 'ttlConfig'
            type: NestedObject
            description: |-
              Configuration for automatic TTL ("time-to-live") of the memories in the Memory Bank.
            properties:
              - name: 'defaultTtl'
                type: String
                exactly_one_of:
                  - defaultTtl
                  - granularTtlConfig
                description: |-
                  The default TTL duration of the memories in the Memory Bank.
              - name: 'granularTtlConfig'
                type: NestedObject
                description: |-
                  The granular TTL configuration of the memories in the Memory Bank.
                properties:
                  - name: 'createTtl'
                    type: String
                    description: |-
                      The TTL duration for memories uploaded via CreateMemory.
                  - name: 'generateCreatedTtl'
                    type: String
                    description: |-
                      The TTL duration for memories newly generated via GenerateMemories.
                  - name: 'generateUpdatedTtl'
                    type: String
                    description: |-
                      The TTL duration for memories updated via GenerateMemories.
              - name: 'memoryRevisionDefaultTtl'
                type: String
                description: |-
                  The default TTL duration of the memory revisions in the Memory Bank.
          - name: 'disableMemoryRevisions'
            type: Boolean
            description: |-
              If true, no memory revisions will be created for any requests to the Memory Bank.