REST Resource: projects.locations.reasoningEngines

Resource: ReasoningEngine

ReasoningEngine provides a customizable runtime for models to determine which actions to take and in which order.

Fields
name string

Identifier. The resource name of the ReasoningEngine. Format: projects/{project}/locations/{location}/reasoningEngines/{reasoningEngine}

displayName string

Required. The display name of the ReasoningEngine.

description string

Optional. The description of the ReasoningEngine.

spec object (ReasoningEngineSpec)

Optional. Configurations of the ReasoningEngine

createTime string (Timestamp format)

Output only. timestamp when this ReasoningEngine was created.

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. timestamp when this ReasoningEngine was most recently 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".

etag string

Optional. Used to perform consistent read-modify-write updates. If not set, a blind "overwrite" update happens.

contextSpec object (ReasoningEngineContextSpec)

Optional. Configuration for how Agent Engine sub-resources should manage context.

encryptionSpec object (EncryptionSpec)

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.

labels map (key: string, value: string)

Labels for the ReasoningEngine.

JSON representation
{
  "name": string,
  "displayName": string,
  "description": string,
  "spec": {
    object (ReasoningEngineSpec)
  },
  "createTime": string,
  "updateTime": string,
  "etag": string,
  "contextSpec": {
    object (ReasoningEngineContextSpec)
  },
  "encryptionSpec": {
    object (EncryptionSpec)
  },
  "labels": {
    string: string,
    ...
  }
}

ReasoningEngineSpec

ReasoningEngine configurations

Fields
packageSpec object (PackageSpec)

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. The deployment_source field should not be set if packageSpec is specified.

deploymentSpec object (DeploymentSpec)

Optional. The specification of a Reasoning Engine deployment.

classMethods[] object (Struct format)

Optional. Declarations for object class methods in OpenAPI specification format.

agentFramework string

Optional. The OSS agent framework used to develop the agent. Currently supported values: "google-adk", "langchain", "langgraph", "ag2", "llama-index", "custom".

deployment_source Union type
Defines the source for the deployment. The package_spec field should not be set if deployment_source is specified. deployment_source can be only one of the following:
sourceCodeSpec object (SourceCodeSpec)

Deploy from source code files with a defined entrypoint.

serviceAccount string

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.

JSON representation
{
  "packageSpec": {
    object (PackageSpec)
  },
  "deploymentSpec": {
    object (DeploymentSpec)
  },
  "classMethods": [
    {
      object
    }
  ],
  "agentFramework": string,

  // deployment_source
  "sourceCodeSpec": {
    object (SourceCodeSpec)
  }
  // Union type
  "serviceAccount": string
}

SourceCodeSpec

Specification for deploying from source code.

Fields
source Union type
Specifies where the source code is located. source can be only one of the following:
inlineSource object (InlineSource)

Source code is provided directly in the request.

language_spec Union type
Specifies the language-specific configuration for building and running the code. language_spec can be only one of the following:
pythonSpec object (PythonSpec)

Configuration for a Python application.

JSON representation
{

  // source
  "inlineSource": {
    object (InlineSource)
  }
  // Union type

  // language_spec
  "pythonSpec": {
    object (PythonSpec)
  }
  // Union type
}

InlineSource

Specifies source code provided as a byte stream.

Fields
sourceArchive string (bytes format)

Required. Input only. The application source code archive, provided as a compressed tarball (.tar.gz) file.

A base64-encoded string.

JSON representation
{
  "sourceArchive": string
}

PythonSpec

Specification for running a Python application from source.

Fields
version string

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.

entrypointModule string

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.

entrypointObject string

Optional. The name of the callable object within the entrypointModule to use as the application If not specified, defaults to "root_agent".

requirementsFile string

Optional. The path to the requirements file, relative to the source root. If not specified, defaults to "requirements.txt".

JSON representation
{
  "version": string,
  "entrypointModule": string,
  "entrypointObject": string,
  "requirementsFile": string
}

PackageSpec

user-provided package specification, containing pickled object and package requirements.

Fields
pickleObjectGcsUri string

Optional. The Cloud Storage URI of the pickled python object.

dependencyFilesGcsUri string

Optional. The Cloud Storage URI of the dependency files in tar.gz format.

requirementsGcsUri string

Optional. The Cloud Storage URI of the requirements.txt file

pythonVersion string

Optional. The Python version. Currently support 3.8, 3.9, 3.10, 3.11. If not specified, default value is 3.10.

JSON representation
{
  "pickleObjectGcsUri": string,
  "dependencyFilesGcsUri": string,
  "requirementsGcsUri": string,
  "pythonVersion": string
}

DeploymentSpec

The specification of a Reasoning Engine deployment.

Fields
env[] object (EnvVar)

Optional. Environment variables to be set with the Reasoning Engine deployment. The environment variables can be updated through the reasoningEngines.patch API.

secretEnv[] object (SecretEnvVar)

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.

agentServerMode enum (AgentServerMode)

The agent server mode.

pscInterfaceConfig object (PscInterfaceConfig)

Optional. Configuration for PSC-I.

resourceLimits map (key: string, value: string)

Optional. Resource limits for each container. Only 'cpu' and 'memory' keys are supported. Defaults to {"cpu": "4", "memory": "4Gi"}.

minInstances integer

Optional. The minimum number of application instances that will be kept running at all times. Defaults to 1. Range: [0, 10].

maxInstances integer

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

containerConcurrency integer

Optional. Concurrency for each container and agent server. Recommended value: 2 * cpu + 1. Defaults to 9.

JSON representation
{
  "env": [
    {
      object (EnvVar)
    }
  ],
  "secretEnv": [
    {
      object (SecretEnvVar)
    }
  ],
  "agentServerMode": enum (AgentServerMode),
  "pscInterfaceConfig": {
    object (PscInterfaceConfig)
  },
  "resourceLimits": {
    string: string,
    ...
  },
  "minInstances": integer,
  "maxInstances": integer,
  "containerConcurrency": integer
}

EnvVar

Represents an environment variable present in a Container or Python Module.

Fields
name string

Required. name of the environment variable. Must be a valid C identifier.

value string

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

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

SecretEnvVar

Represents an environment variable where the value is a secret in Cloud Secret Manager.

Fields
name string

Required. name of the secret environment variable.

secretRef object (SecretRef)

Required. Reference to a secret stored in the Cloud Secret Manager that will provide the value for this environment variable.

JSON representation
{
  "name": string,
  "secretRef": {
    object (SecretRef)
  }
}

SecretRef

Reference to a secret stored in the Cloud Secret Manager that will provide the value for this environment variable.

Fields
secret string

Required. The name of the secret in Cloud Secret Manager. Format: {secret_name}.

version string

The Cloud Secret Manager secret version. Can be 'latest' for the latest version, an integer for a specific version, or a version alias.

JSON representation
{
  "secret": string,
  "version": string
}

AgentServerMode

The agent server mode specifies what features are used when deploy the agent to agent engine.

Enums
AGENT_SERVER_MODE_UNSPECIFIED Unspecified agent server mode. Do not use.
STABLE Stable agent server mode. This mode has everything stable and well-tested features agent engine offers.
EXPERIMENTAL Experimental agent server mode. This mode contains experimental features.

PscInterfaceConfig

Configuration for PSC-I.

Fields
networkAttachment string

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

dnsPeeringConfigs[] object (DnsPeeringConfig)

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.

JSON representation
{
  "networkAttachment": string,
  "dnsPeeringConfigs": [
    {
      object (DnsPeeringConfig)
    }
  ]
}

DnsPeeringConfig

DNS peering configuration. These configurations are used to create DNS peering zones in the Vertex tenant project VPC, enabling resolution of records within the specified domain hosted in the target network's Cloud DNS.

Fields
domain string

Required. The DNS name suffix of the zone being peered to, e.g., "my-internal-domain.corp.". Must end with a dot.

targetProject string

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.

targetNetwork string

Required. The VPC network name in the targetProject where the DNS zone specified by 'domain' is visible.

JSON representation
{
  "domain": string,
  "targetProject": string,
  "targetNetwork": string
}

ReasoningEngineContextSpec

Configuration for how Agent Engine sub-resources should manage context.

Fields
memoryBankConfig object (MemoryBankConfig)

Optional. Specification for a Memory Bank, which manages memories for the Agent Engine.

JSON representation
{
  "memoryBankConfig": {
    object (MemoryBankConfig)
  }
}

MemoryBankConfig

Specification for a Memory Bank.

Fields
generationConfig object (GenerationConfig)

Optional. Configuration for how to generate memories for the Memory Bank.

similaritySearchConfig object (SimilaritySearchConfig)

Optional. Configuration for how to perform similarity search on memories. If not set, the Memory Bank will use the default embedding model text-embedding-005.

customizationConfigs[] object (MemoryBankCustomizationConfig)

Optional. Configuration for how to customize Memory Bank behavior for a particular scope.

ttlConfig object (TtlConfig)

Optional. Configuration for automatic TTL ("time-to-live") of the memories in the Memory Bank. If not set, TTL will not be applied automatically. The TTL can be explicitly set by modifying the expireTime of each Memory resource.

disableMemoryRevisions boolean

If true, no memory revisions will be created for any requests to the Memory Bank.

JSON representation
{
  "generationConfig": {
    object (GenerationConfig)
  },
  "similaritySearchConfig": {
    object (SimilaritySearchConfig)
  },
  "customizationConfigs": [
    {
      object (MemoryBankCustomizationConfig)
    }
  ],
  "ttlConfig": {
    object (TtlConfig)
  },
  "disableMemoryRevisions": boolean
}

GenerationConfig

Configuration for how to generate memories.

Fields
model string

Required. The model used to generate memories. Format: projects/{project}/locations/{location}/publishers/google/models/{model}.

JSON representation
{
  "model": string
}

SimilaritySearchConfig

Configuration for how to perform similarity search on memories.

Fields
embeddingModel string

Required. The model used to generate embeddings to lookup similar memories. Format: projects/{project}/locations/{location}/publishers/google/models/{model}.

JSON representation
{
  "embeddingModel": string
}

MemoryBankCustomizationConfig

Configuration for organizing memories for a particular scope.

Fields
scopeKeys[] string

Optional. The scope keys (i.e. 'userId') for which to use this config. A request's scope must include all of the provided keys for the config to be used (order does not matter). If empty, then the config will be used for all requests that do not have a more specific config. Only one default config is allowed per Memory Bank.

memoryTopics[] object (MemoryTopic)

Optional. Topics of information that should be extracted from conversations and stored as memories. If not set, then Memory Bank's default topics will be used.

generateMemoriesExamples[] object (GenerateMemoriesExample)

Optional. Examples of how to generate memories for a particular scope.

JSON representation
{
  "scopeKeys": [
    string
  ],
  "memoryTopics": [
    {
      object (MemoryTopic)
    }
  ],
  "generateMemoriesExamples": [
    {
      object (GenerateMemoriesExample)
    }
  ]
}

MemoryTopic

A topic of information that should be extracted from conversations and stored as memories.

Fields
topic_type Union type
The type of the topic. topic_type can be only one of the following:
customMemoryTopic object (CustomMemoryTopic)

A custom memory topic defined by the developer.

managedMemoryTopic object (ManagedMemoryTopic)

A managed memory topic defined by Memory Bank.

JSON representation
{

  // topic_type
  "customMemoryTopic": {
    object (CustomMemoryTopic)
  },
  "managedMemoryTopic": {
    object (ManagedMemoryTopic)
  }
  // Union type
}

CustomMemoryTopic

A custom memory topic defined by the developer.

Fields
label string

Required. The label of the topic.

description string

Required. description of the memory topic. This should explain what information should be extracted for this topic.

JSON representation
{
  "label": string,
  "description": string
}

ManagedMemoryTopic

A managed memory topic defined by the system.

Fields
managedTopicEnum enum (ManagedTopicEnum)

Required. The managed topic.

JSON representation
{
  "managedTopicEnum": enum (ManagedTopicEnum)
}

GenerateMemoriesExample

An example of how to generate memories for a particular scope.

Fields
generatedMemories[] object (GeneratedMemory)

Optional. The memories that are expected to be generated from the input conversation. An empty list indicates that no memories are expected to be generated for the input conversation.

source Union type
The input source for the example. source can be only one of the following:
conversationSource object (ConversationSource)

A conversation source for the example.

JSON representation
{
  "generatedMemories": [
    {
      object (GeneratedMemory)
    }
  ],

  // source
  "conversationSource": {
    object (ConversationSource)
  }
  // Union type
}

ConversationSource

A conversation source for the example. This is similar to DirectContentsSource.

Fields
events[] object (Event)

Optional. The input conversation events for the example.

JSON representation
{
  "events": [
    {
      object (Event)
    }
  ]
}

Event

A single conversation event.

Fields
content object (Content)

Required. The content of the event.

JSON representation
{
  "content": {
    object (Content)
  }
}

GeneratedMemory

A memory generated by the operation.

Fields
fact string

Required. The fact to generate a memory from.

topics[] object (MemoryTopicId)

Optional. The list of topics that the memory should be associated with. For example, use customMemoryTopicLabel = "jargon" if the extracted memory is an example of memory extraction for the custom topic jargon.

JSON representation
{
  "fact": string,
  "topics": [
    {
      object (MemoryTopicId)
    }
  ]
}

TtlConfig

Configuration for automatically setting the TTL ("time-to-live") of the memories in the Memory Bank.

Fields
ttl Union type
Configuration for automatically setting the TTL of the memories in the Memory Bank. ttl can be only one of the following:
defaultTtl string (Duration format)

Optional. The default TTL duration of the memories in the Memory Bank. This applies to all operations that create or update a memory.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

granularTtlConfig object (GranularTtlConfig)

Optional. The granular TTL configuration of the memories in the Memory Bank.

memory_revision_ttl Union type
Configuration for automatically setting the TTL of the memory revisions in the Memory Bank. memory_revision_ttl can be only one of the following:
memoryRevisionDefaultTtl string (Duration format)

Optional. The default TTL duration of the memory revisions in the Memory Bank. This applies to all operations that create a memory revision. If not set, a default TTL of 365 days will be used.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

JSON representation
{

  // ttl
  "defaultTtl": string,
  "granularTtlConfig": {
    object (GranularTtlConfig)
  }
  // Union type

  // memory_revision_ttl
  "memoryRevisionDefaultTtl": string
  // Union type
}

GranularTtlConfig

Configuration for TTL of the memories in the Memory Bank based on the action that created or updated the memory.

Fields
createTtl string (Duration format)

Optional. The TTL duration for memories uploaded via CreateMemory.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

generateCreatedTtl string (Duration format)

Optional. The TTL duration for memories newly generated via GenerateMemories (GenerateMemoriesResponse.GeneratedMemory.Action.CREATED).

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

generateUpdatedTtl string (Duration format)

Optional. The TTL duration for memories updated via GenerateMemories (GenerateMemoriesResponse.GeneratedMemory.Action.UPDATED). In the case of an UPDATE action, the expireTime of the existing memory will be updated to the new value (now + TTL).

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

JSON representation
{
  "createTtl": string,
  "generateCreatedTtl": string,
  "generateUpdatedTtl": string
}

Methods

create

Creates a reasoning engine.

delete

Deletes a reasoning engine.

get

Gets a reasoning engine.

list

Lists reasoning engines in a location.

patch

Updates a reasoning engine.

query

Queries using a reasoning engine.

streamQuery

Streams queries using a reasoning engine.