diff --git a/agentplatform/_genai/types/common.py b/agentplatform/_genai/types/common.py index 88d34fa7be..49ea457388 100644 --- a/agentplatform/_genai/types/common.py +++ b/agentplatform/_genai/types/common.py @@ -210,14 +210,14 @@ class ManagedTopicEnum(_common.CaseInSensitiveEnum): class IdentityType(_common.CaseInSensitiveEnum): - """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.""" + """The identity type to use for the Reasoning Engine.""" IDENTITY_TYPE_UNSPECIFIED = "IDENTITY_TYPE_UNSPECIFIED" - """Default value. 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. Same behavior as SERVICE_ACCOUNT.""" + """Default value. 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. Same behavior as `SERVICE_ACCOUNT`. WARNING: The default service agent is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account; see `identity_type` for security guidance.""" SERVICE_ACCOUNT = "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.""" + """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. WARNING: The default service agent is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account; see `identity_type` for security guidance.""" AGENT_IDENTITY = "AGENT_IDENTITY" - """Use Agent Identity. The `service_account` field must not be set.""" + """Use Agent Identity. The `service_account` field must not be set. Restrict `aiplatform.reasoningEngines.update` permissions on the engine because any principal permitted to update it can run code as its identity.""" class AgentServerMode(_common.CaseInSensitiveEnum): @@ -8836,7 +8836,7 @@ class ReasoningEngineSpecDeploymentSpec(_common.BaseModel): ) secret_env: Optional[list[SecretEnvVar]] = Field( default=None, - 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.""", + description="""Optional. Environment variables where the value is a secret in Secret Manager. Secrets must be global secrets in the same project as the Reasoning Engine. At startup (and during deployment validation for service-account-based deployments), the Reasoning Engine accesses the referenced secrets using its configured runtime identity. Grant the Secret Manager Secret Accessor role (`roles/secretmanager.secretAccessor`) on the specific secret to an isolated per-agent identity (`identity_type = AGENT_IDENTITY`) or a dedicated custom `service_account`. When using `AGENT_IDENTITY`, create the Reasoning Engine first without `secret_env`, grant access to its provisioned agent identity (prepend `principal://` to `effective_identity`), and then update the Reasoning Engine to add `secret_env`. WARNING: Avoid granting secret access to the default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`), which is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account; any principal with permission to deploy or update agents in the project can access secrets granted to it. Also restrict `aiplatform.reasoningEngines.update` permissions on `AGENT_IDENTITY` engines.""", ) agent_gateway_config: Optional[ ReasoningEngineSpecDeploymentSpecAgentGatewayConfig @@ -8875,7 +8875,7 @@ class ReasoningEngineSpecDeploymentSpecDict(TypedDict, total=False): """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 required cpu on different memory values, go to https://cloud.google.com/run/docs/configuring/memory-limits""" secret_env: Optional[list[SecretEnvVarDict]] - """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.""" + """Optional. Environment variables where the value is a secret in Secret Manager. Secrets must be global secrets in the same project as the Reasoning Engine. At startup (and during deployment validation for service-account-based deployments), the Reasoning Engine accesses the referenced secrets using its configured runtime identity. Grant the Secret Manager Secret Accessor role (`roles/secretmanager.secretAccessor`) on the specific secret to an isolated per-agent identity (`identity_type = AGENT_IDENTITY`) or a dedicated custom `service_account`. When using `AGENT_IDENTITY`, create the Reasoning Engine first without `secret_env`, grant access to its provisioned agent identity (prepend `principal://` to `effective_identity`), and then update the Reasoning Engine to add `secret_env`. WARNING: Avoid granting secret access to the default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`), which is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account; any principal with permission to deploy or update agents in the project can access secrets granted to it. Also restrict `aiplatform.reasoningEngines.update` permissions on `AGENT_IDENTITY` engines.""" agent_gateway_config: Optional[ ReasoningEngineSpecDeploymentSpecAgentGatewayConfigDict @@ -9315,11 +9315,11 @@ class ReasoningEngineSpec(_common.BaseModel): ) effective_identity: Optional[str] = Field( default=None, - description="""Output only. The identity to use for the Reasoning Engine. It can contain one of the following values: * service-{project}@gcp-sa-aiplatform-re.googleapis.com (for SERVICE_AGENT identity type) * {name}@{project}.gserviceaccount.com (for SERVICE_ACCOUNT identity type) * agents.global.{org}.system.id.goog/resources/aiplatform/projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine} (for AGENT_IDENTITY identity type)""", + description="""Output only. The identity to use for the Reasoning Engine. It can contain one of the following values: * `service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com` (for the default service agent when `identity_type` is `IDENTITY_TYPE_UNSPECIFIED` or `SERVICE_ACCOUNT` and `service_account` is not set) * `{name}@{project}.iam.gserviceaccount.com` (for a custom `service_account` when `identity_type` is `IDENTITY_TYPE_UNSPECIFIED` or `SERVICE_ACCOUNT`) * `agents.global.org-{org}.system.id.goog/resources/aiplatform/projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}` (or `agents.global.proj-{project_number}.system.id.goog/...` for org-less projects; for `AGENT_IDENTITY` identity type -- prepend `principal://` when used in IAM policy bindings)""", ) identity_type: Optional[IdentityType] = Field( default=None, - 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.""", + 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. WARNING: The default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account. Any permissions or secrets granted to it can be accessed by any principal permitted to deploy or update agents in the project (even without using `secret_env`, by calling APIs directly from agent code). Prefer `AGENT_IDENTITY` (and restrict `aiplatform.reasoningEngines.update` permissions on the engine) or a dedicated custom `service_account` when granting access to sensitive resources such as Secret Manager secrets.""", ) package_spec: Optional[ReasoningEngineSpecPackageSpec] = Field( default=None, @@ -9327,7 +9327,7 @@ class ReasoningEngineSpec(_common.BaseModel): ) service_account: Optional[str] = Field( default=None, - 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.""", + 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 and `identity_type` is not `AGENT_IDENTITY`, the default Vertex AI Reasoning Engine Service Agent in the project will be used. WARNING: The default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account. Any permissions or secrets granted to it can be accessed by any principal permitted to deploy or update agents in the project (even without using `secret_env`, by calling APIs directly from agent code). For sensitive resources such as Secret Manager secrets, use `identity_type = AGENT_IDENTITY` (restricting `aiplatform.reasoningEngines.update` access to that engine) or a dedicated custom `service_account`.""", ) source_code_spec: Optional[ReasoningEngineSpecSourceCodeSpec] = Field( default=None, @@ -9359,16 +9359,16 @@ class ReasoningEngineSpecDict(TypedDict, total=False): """Optional. The specification of a Reasoning Engine deployment.""" effective_identity: Optional[str] - """Output only. The identity to use for the Reasoning Engine. It can contain one of the following values: * service-{project}@gcp-sa-aiplatform-re.googleapis.com (for SERVICE_AGENT identity type) * {name}@{project}.gserviceaccount.com (for SERVICE_ACCOUNT identity type) * agents.global.{org}.system.id.goog/resources/aiplatform/projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine} (for AGENT_IDENTITY identity type)""" + """Output only. The identity to use for the Reasoning Engine. It can contain one of the following values: * `service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com` (for the default service agent when `identity_type` is `IDENTITY_TYPE_UNSPECIFIED` or `SERVICE_ACCOUNT` and `service_account` is not set) * `{name}@{project}.iam.gserviceaccount.com` (for a custom `service_account` when `identity_type` is `IDENTITY_TYPE_UNSPECIFIED` or `SERVICE_ACCOUNT`) * `agents.global.org-{org}.system.id.goog/resources/aiplatform/projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}` (or `agents.global.proj-{project_number}.system.id.goog/...` for org-less projects; for `AGENT_IDENTITY` identity type -- prepend `principal://` when used in IAM policy bindings)""" identity_type: Optional[IdentityType] - """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.""" + """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. WARNING: The default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account. Any permissions or secrets granted to it can be accessed by any principal permitted to deploy or update agents in the project (even without using `secret_env`, by calling APIs directly from agent code). Prefer `AGENT_IDENTITY` (and restrict `aiplatform.reasoningEngines.update` permissions on the engine) or a dedicated custom `service_account` when granting access to sensitive resources such as Secret Manager secrets.""" package_spec: Optional[ReasoningEngineSpecPackageSpecDict] """Optional. User provided package spec of the ReasoningEngine. Ignored when users directly specify a deployment image through `deployment_spec.first_party_image_override`, but keeping the field_behavior to avoid introducing breaking changes. The `deployment_source` field should not be set if `package_spec` is specified.""" service_account: Optional[str] - """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.""" + """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 and `identity_type` is not `AGENT_IDENTITY`, the default Vertex AI Reasoning Engine Service Agent in the project will be used. WARNING: The default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account. Any permissions or secrets granted to it can be accessed by any principal permitted to deploy or update agents in the project (even without using `secret_env`, by calling APIs directly from agent code). For sensitive resources such as Secret Manager secrets, use `identity_type = AGENT_IDENTITY` (restricting `aiplatform.reasoningEngines.update` access to that engine) or a dedicated custom `service_account`.""" source_code_spec: Optional[ReasoningEngineSpecSourceCodeSpecDict] """Deploy from source code files with a defined entrypoint.""" @@ -33269,16 +33269,50 @@ class AgentRuntimeConfig(_common.BaseModel): description="""The environment variables to be set when running the Agent Runtime. If it is a dictionary, the keys are the environment variable names, and - the values are the corresponding values.""", + the values are the corresponding values (strings or Secret Manager + references of the form `{'secret': '', 'version': ''}`). + + When referencing Secret Manager secrets, grant + `roles/secretmanager.secretAccessor` on the specific secret to an isolated + `AGENT_IDENTITY` (create the Agent Runtime first without secrets, grant + access to `principal://{effective_identity}`, then update) or a dedicated + custom `service_account`. Avoid granting secret access to the shared + default Vertex AI Reasoning Engine Service Agent.""", ) service_account: Optional[str] = Field( default=None, description="""The service account to be used for the Agent Runtime. - If not specified, the default Reasoning Engine P6SA service agent will be used.""", + When creating an Agent Runtime, if not specified and `identity_type` is + not `AGENT_IDENTITY`, the default Vertex AI Reasoning Engine Service + Agent + (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) + will be used; when updating, omitting it preserves the existing service + account. + + WARNING: The default service agent is shared across all Agent Runtimes in + the project that do not specify an isolated identity or custom service + account, so any principal with permission to deploy or update agents in + the project can access permissions or secrets granted to it. Prefer + `identity_type='AGENT_IDENTITY'` (restricting + `aiplatform.reasoningEngines.update` permissions on the runtime) or a + dedicated custom `service_account` for sensitive resources such as Secret + Manager secrets.""", ) identity_type: Optional[IdentityType] = Field( - default=None, description="""The identity type to use for the Agent Runtime.""" + default=None, + description="""The identity type to use for the Agent Runtime. + + Set to `AGENT_IDENTITY` to run the Agent Runtime under a resource-scoped + per-agent identity (`service_account` must not be set), or + `SERVICE_ACCOUNT` to use `service_account` (if set) or the shared default + Vertex AI Reasoning Engine Service Agent. + + WARNING: Avoid granting sensitive permissions or Secret Manager secrets to + the shared default service agent. Prefer `AGENT_IDENTITY` (restricting + `aiplatform.reasoningEngines.update` permissions on the runtime, since + any principal permitted to update it can run code as its identity) or a + dedicated custom `service_account`.""", ) context_spec: Optional[ReasoningEngineContextSpec] = Field( default=None, @@ -33498,15 +33532,48 @@ class AgentRuntimeConfigDict(TypedDict, total=False): """The environment variables to be set when running the Agent Runtime. If it is a dictionary, the keys are the environment variable names, and - the values are the corresponding values.""" + the values are the corresponding values (strings or Secret Manager + references of the form `{'secret': '', 'version': ''}`). + + When referencing Secret Manager secrets, grant + `roles/secretmanager.secretAccessor` on the specific secret to an isolated + `AGENT_IDENTITY` (create the Agent Runtime first without secrets, grant + access to `principal://{effective_identity}`, then update) or a dedicated + custom `service_account`. Avoid granting secret access to the shared + default Vertex AI Reasoning Engine Service Agent.""" service_account: Optional[str] """The service account to be used for the Agent Runtime. - If not specified, the default Reasoning Engine P6SA service agent will be used.""" + When creating an Agent Runtime, if not specified and `identity_type` is + not `AGENT_IDENTITY`, the default Vertex AI Reasoning Engine Service + Agent + (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) + will be used; when updating, omitting it preserves the existing service + account. + + WARNING: The default service agent is shared across all Agent Runtimes in + the project that do not specify an isolated identity or custom service + account, so any principal with permission to deploy or update agents in + the project can access permissions or secrets granted to it. Prefer + `identity_type='AGENT_IDENTITY'` (restricting + `aiplatform.reasoningEngines.update` permissions on the runtime) or a + dedicated custom `service_account` for sensitive resources such as Secret + Manager secrets.""" identity_type: Optional[IdentityType] - """The identity type to use for the Agent Runtime.""" + """The identity type to use for the Agent Runtime. + + Set to `AGENT_IDENTITY` to run the Agent Runtime under a resource-scoped + per-agent identity (`service_account` must not be set), or + `SERVICE_ACCOUNT` to use `service_account` (if set) or the shared default + Vertex AI Reasoning Engine Service Agent. + + WARNING: Avoid granting sensitive permissions or Secret Manager secrets to + the shared default service agent. Prefer `AGENT_IDENTITY` (restricting + `aiplatform.reasoningEngines.update` permissions on the runtime, since + any principal permitted to update it can run code as its identity) or a + dedicated custom `service_account`.""" context_spec: Optional[ReasoningEngineContextSpecDict] """The context spec to be used for the Agent Runtime.""" diff --git a/vertexai/_genai/types/common.py b/vertexai/_genai/types/common.py index daf95fe28b..64f804d7cb 100644 --- a/vertexai/_genai/types/common.py +++ b/vertexai/_genai/types/common.py @@ -260,14 +260,41 @@ class ManagedTopicEnum(_common.CaseInSensitiveEnum): class IdentityType(_common.CaseInSensitiveEnum): - """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.""" + """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. WARNING: Avoid granting sensitive permissions or + Secret Manager secrets to the shared default service agent; prefer + `AGENT_IDENTITY` (restricting `aiplatform.reasoningEngines.update` + permissions on the engine) or a dedicated custom `service_account`. + """ IDENTITY_TYPE_UNSPECIFIED = "IDENTITY_TYPE_UNSPECIFIED" - """Default value. 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. Same behavior as SERVICE_ACCOUNT.""" + """Default value. + + 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. Same behavior as `SERVICE_ACCOUNT`. WARNING: The default service + agent is shared across all Reasoning Engines in the project that do not + specify an isolated identity or custom service account. + """ SERVICE_ACCOUNT = "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.""" + """Use a custom service account or the default service agent. + + Uses the custom service account if the `service_account` field is set, + otherwise uses the default Vertex AI Reasoning Engine Service Agent in the + project. WARNING: The default service agent is shared across all Reasoning + Engines in the project that do not specify an isolated identity or custom + service account. + """ AGENT_IDENTITY = "AGENT_IDENTITY" - """Use Agent Identity. The `service_account` field must not be set.""" + """Use Agent Identity. + + The `service_account` field must not be set. Restrict + `aiplatform.reasoningEngines.update` permissions on the engine because any + principal permitted to update it can run code as its identity. + """ class AgentServerMode(_common.CaseInSensitiveEnum): @@ -8133,7 +8160,7 @@ class ReasoningEngineSpecDeploymentSpec(_common.BaseModel): ) secret_env: Optional[list[SecretEnvVar]] = Field( default=None, - 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.""", + description="""Optional. Environment variables where the value is a secret in Secret Manager. Secrets must be global secrets in the same project as the Reasoning Engine. At startup (and during deployment validation for service-account-based deployments), the Reasoning Engine accesses the referenced secrets using its configured runtime identity. Grant the Secret Manager Secret Accessor role (`roles/secretmanager.secretAccessor`) on the specific secret to an isolated per-agent identity (`identity_type = AGENT_IDENTITY`) or a dedicated custom `service_account`. When using `AGENT_IDENTITY`, create the Reasoning Engine first without `secret_env`, grant access to its provisioned agent identity (prepend `principal://` to `effective_identity`), and then update the Reasoning Engine to add `secret_env`. WARNING: Avoid granting secret access to the default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`), which is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account; any principal with permission to deploy or update agents in the project can access secrets granted to it. Also restrict `aiplatform.reasoningEngines.update` permissions on `AGENT_IDENTITY` engines.""", ) agent_gateway_config: Optional[ ReasoningEngineSpecDeploymentSpecAgentGatewayConfig @@ -8172,7 +8199,7 @@ class ReasoningEngineSpecDeploymentSpecDict(TypedDict, total=False): """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 required cpu on different memory values, go to https://cloud.google.com/run/docs/configuring/memory-limits""" secret_env: Optional[list[SecretEnvVarDict]] - """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.""" + """Optional. Environment variables where the value is a secret in Secret Manager. Secrets must be global secrets in the same project as the Reasoning Engine. At startup (and during deployment validation for service-account-based deployments), the Reasoning Engine accesses the referenced secrets using its configured runtime identity. Grant the Secret Manager Secret Accessor role (`roles/secretmanager.secretAccessor`) on the specific secret to an isolated per-agent identity (`identity_type = AGENT_IDENTITY`) or a dedicated custom `service_account`. When using `AGENT_IDENTITY`, create the Reasoning Engine first without `secret_env`, grant access to its provisioned agent identity (prepend `principal://` to `effective_identity`), and then update the Reasoning Engine to add `secret_env`. WARNING: Avoid granting secret access to the default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`), which is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account; any principal with permission to deploy or update agents in the project can access secrets granted to it. Also restrict `aiplatform.reasoningEngines.update` permissions on `AGENT_IDENTITY` engines.""" agent_gateway_config: Optional[ ReasoningEngineSpecDeploymentSpecAgentGatewayConfigDict @@ -8563,11 +8590,11 @@ class ReasoningEngineSpec(_common.BaseModel): ) effective_identity: Optional[str] = Field( default=None, - description="""Output only. The identity to use for the Reasoning Engine. It can contain one of the following values: * service-{project}@gcp-sa-aiplatform-re.googleapis.com (for SERVICE_AGENT identity type) * {name}@{project}.gserviceaccount.com (for SERVICE_ACCOUNT identity type) * agents.global.{org}.system.id.goog/resources/aiplatform/projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine} (for AGENT_IDENTITY identity type)""", + description="""Output only. The identity to use for the Reasoning Engine. It can contain one of the following values: * `service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com` (for the default service agent when `identity_type` is `IDENTITY_TYPE_UNSPECIFIED` or `SERVICE_ACCOUNT` and `service_account` is not set) * `{name}@{project}.iam.gserviceaccount.com` (for a custom `service_account` when `identity_type` is `IDENTITY_TYPE_UNSPECIFIED` or `SERVICE_ACCOUNT`) * `agents.global.org-{org}.system.id.goog/resources/aiplatform/projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}` (or `agents.global.proj-{project_number}.system.id.goog/...` for org-less projects; for `AGENT_IDENTITY` identity type -- prepend `principal://` when used in IAM policy bindings)""", ) identity_type: Optional[IdentityType] = Field( default=None, - 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.""", + 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. WARNING: The default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account. Any permissions or secrets granted to it can be accessed by any principal permitted to deploy or update agents in the project (even without using `secret_env`, by calling APIs directly from agent code). Prefer `AGENT_IDENTITY` (and restrict `aiplatform.reasoningEngines.update` permissions on the engine) or a dedicated custom `service_account` when granting access to sensitive resources such as Secret Manager secrets.""", ) package_spec: Optional[ReasoningEngineSpecPackageSpec] = Field( default=None, @@ -8575,7 +8602,7 @@ class ReasoningEngineSpec(_common.BaseModel): ) service_account: Optional[str] = Field( default=None, - 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.""", + 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 and `identity_type` is not `AGENT_IDENTITY`, the default Vertex AI Reasoning Engine Service Agent in the project will be used. WARNING: The default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account. Any permissions or secrets granted to it can be accessed by any principal permitted to deploy or update agents in the project (even without using `secret_env`, by calling APIs directly from agent code). For sensitive resources such as Secret Manager secrets, use `identity_type = AGENT_IDENTITY` (restricting `aiplatform.reasoningEngines.update` access to that engine) or a dedicated custom `service_account`.""", ) source_code_spec: Optional[ReasoningEngineSpecSourceCodeSpec] = Field( default=None, @@ -8607,16 +8634,16 @@ class ReasoningEngineSpecDict(TypedDict, total=False): """Optional. The specification of a Reasoning Engine deployment.""" effective_identity: Optional[str] - """Output only. The identity to use for the Reasoning Engine. It can contain one of the following values: * service-{project}@gcp-sa-aiplatform-re.googleapis.com (for SERVICE_AGENT identity type) * {name}@{project}.gserviceaccount.com (for SERVICE_ACCOUNT identity type) * agents.global.{org}.system.id.goog/resources/aiplatform/projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine} (for AGENT_IDENTITY identity type)""" + """Output only. The identity to use for the Reasoning Engine. It can contain one of the following values: * `service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com` (for the default service agent when `identity_type` is `IDENTITY_TYPE_UNSPECIFIED` or `SERVICE_ACCOUNT` and `service_account` is not set) * `{name}@{project}.iam.gserviceaccount.com` (for a custom `service_account` when `identity_type` is `IDENTITY_TYPE_UNSPECIFIED` or `SERVICE_ACCOUNT`) * `agents.global.org-{org}.system.id.goog/resources/aiplatform/projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}` (or `agents.global.proj-{project_number}.system.id.goog/...` for org-less projects; for `AGENT_IDENTITY` identity type -- prepend `principal://` when used in IAM policy bindings)""" identity_type: Optional[IdentityType] - """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.""" + """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. WARNING: The default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account. Any permissions or secrets granted to it can be accessed by any principal permitted to deploy or update agents in the project (even without using `secret_env`, by calling APIs directly from agent code). Prefer `AGENT_IDENTITY` (and restrict `aiplatform.reasoningEngines.update` permissions on the engine) or a dedicated custom `service_account` when granting access to sensitive resources such as Secret Manager secrets.""" package_spec: Optional[ReasoningEngineSpecPackageSpecDict] """Optional. User provided package spec of the ReasoningEngine. Ignored when users directly specify a deployment image through `deployment_spec.first_party_image_override`, but keeping the field_behavior to avoid introducing breaking changes. The `deployment_source` field should not be set if `package_spec` is specified.""" service_account: Optional[str] - """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.""" + """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 and `identity_type` is not `AGENT_IDENTITY`, the default Vertex AI Reasoning Engine Service Agent in the project will be used. WARNING: The default Vertex AI Reasoning Engine Service Agent (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) is shared across all Reasoning Engines in the project that do not specify an isolated identity or custom service account. Any permissions or secrets granted to it can be accessed by any principal permitted to deploy or update agents in the project (even without using `secret_env`, by calling APIs directly from agent code). For sensitive resources such as Secret Manager secrets, use `identity_type = AGENT_IDENTITY` (restricting `aiplatform.reasoningEngines.update` access to that engine) or a dedicated custom `service_account`.""" source_code_spec: Optional[ReasoningEngineSpecSourceCodeSpecDict] """Deploy from source code files with a defined entrypoint.""" @@ -20363,16 +20390,50 @@ class AgentEngineConfig(_common.BaseModel): description="""The environment variables to be set when running the Agent Engine. If it is a dictionary, the keys are the environment variable names, and - the values are the corresponding values.""", + the values are the corresponding values (strings or Secret Manager + references of the form `{'secret': '', 'version': ''}`). + + When referencing Secret Manager secrets, grant + `roles/secretmanager.secretAccessor` on the specific secret to an isolated + `AGENT_IDENTITY` (create the Agent Engine first without secrets, grant + access to `principal://{effective_identity}`, then update) or a dedicated + custom `service_account`. Avoid granting secret access to the shared + default Vertex AI Reasoning Engine Service Agent.""", ) service_account: Optional[str] = Field( default=None, description="""The service account to be used for the Agent Engine. - If not specified, the default Reasoning Engine P6SA service agent will be used.""", + When creating an Agent Engine, if not specified and `identity_type` is + not `AGENT_IDENTITY`, the default Vertex AI Reasoning Engine Service + Agent + (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) + will be used; when updating, omitting it preserves the existing service + account. + + WARNING: The default service agent is shared across all Agent Engines in + the project that do not specify an isolated identity or custom service + account, so any principal with permission to deploy or update agents in + the project can access permissions or secrets granted to it. Prefer + `identity_type='AGENT_IDENTITY'` (restricting + `aiplatform.reasoningEngines.update` permissions on the engine) or a + dedicated custom `service_account` for sensitive resources such as Secret + Manager secrets.""", ) identity_type: Optional[IdentityType] = Field( - default=None, description="""The identity type to use for the Agent Engine.""" + default=None, + description="""The identity type to use for the Agent Engine. + + Set to `AGENT_IDENTITY` to run the Agent Engine under a resource-scoped + per-agent identity (`service_account` must not be set), or + `SERVICE_ACCOUNT` to use `service_account` (if set) or the shared default + Vertex AI Reasoning Engine Service Agent. + + WARNING: Avoid granting sensitive permissions or Secret Manager secrets to + the shared default service agent. Prefer `AGENT_IDENTITY` (restricting + `aiplatform.reasoningEngines.update` permissions on the engine, since any + principal permitted to update it can run code as its identity) or a + dedicated custom `service_account`.""", ) context_spec: Optional[ReasoningEngineContextSpec] = Field( default=None, @@ -20578,15 +20639,48 @@ class AgentEngineConfigDict(TypedDict, total=False): """The environment variables to be set when running the Agent Engine. If it is a dictionary, the keys are the environment variable names, and - the values are the corresponding values.""" + the values are the corresponding values (strings or Secret Manager + references of the form `{'secret': '', 'version': ''}`). + + When referencing Secret Manager secrets, grant + `roles/secretmanager.secretAccessor` on the specific secret to an isolated + `AGENT_IDENTITY` (create the Agent Engine first without secrets, grant + access to `principal://{effective_identity}`, then update) or a dedicated + custom `service_account`. Avoid granting secret access to the shared + default Vertex AI Reasoning Engine Service Agent.""" service_account: Optional[str] """The service account to be used for the Agent Engine. - If not specified, the default Reasoning Engine P6SA service agent will be used.""" + When creating an Agent Engine, if not specified and `identity_type` is + not `AGENT_IDENTITY`, the default Vertex AI Reasoning Engine Service + Agent + (`service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) + will be used; when updating, omitting it preserves the existing service + account. + + WARNING: The default service agent is shared across all Agent Engines in + the project that do not specify an isolated identity or custom service + account, so any principal with permission to deploy or update agents in + the project can access permissions or secrets granted to it. Prefer + `identity_type='AGENT_IDENTITY'` (restricting + `aiplatform.reasoningEngines.update` permissions on the engine) or a + dedicated custom `service_account` for sensitive resources such as Secret + Manager secrets.""" identity_type: Optional[IdentityType] - """The identity type to use for the Agent Engine.""" + """The identity type to use for the Agent Engine. + + Set to `AGENT_IDENTITY` to run the Agent Engine under a resource-scoped + per-agent identity (`service_account` must not be set), or + `SERVICE_ACCOUNT` to use `service_account` (if set) or the shared default + Vertex AI Reasoning Engine Service Agent. + + WARNING: Avoid granting sensitive permissions or Secret Manager secrets to + the shared default service agent. Prefer `AGENT_IDENTITY` (restricting + `aiplatform.reasoningEngines.update` permissions on the engine, since any + principal permitted to update it can run code as its identity) or a + dedicated custom `service_account`.""" context_spec: Optional[ReasoningEngineContextSpecDict] """The context spec to be used for the Agent Engine.""" diff --git a/vertexai/agent_engines/__init__.py b/vertexai/agent_engines/__init__.py index d64133522c..2292beadf2 100644 --- a/vertexai/agent_engines/__init__.py +++ b/vertexai/agent_engines/__init__.py @@ -47,7 +47,6 @@ LanggraphAgent, ) - _LOGGER = base.Logger(__name__) @@ -155,22 +154,42 @@ def create( Agent Engine. If it is a list of strings, each string should be a valid key to `os.environ`. If it is a dictionary, the keys are the environment variable names, and the values are the - corresponding values. + corresponding values (strings or `SecretRef` entries for Secret + Manager secrets). When referencing Secret Manager secrets, grant + `roles/secretmanager.secretAccessor` on the specific secret to + an isolated `AGENT_IDENTITY` (create the Agent Engine first + without secrets, grant access to + `principal://{effective_identity}`, then update) or a dedicated + custom `service_account`; avoid granting secret access to the + shared default Reasoning Engine Service Agent. build_options (Dict[str, Sequence[str]]): Optional. The build options for the Agent Engine. This includes options such as installation scripts. service_account (str): - Optional. The service account to be used for the Agent Engine. If - not specified, the default reasoning engine service agent service - account will be used. + Optional. The service account to be used for the Agent Engine. + If not specified and `identity_type` is not `AGENT_IDENTITY`, + the default Vertex AI Reasoning Engine Service Agent, + `service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`, + will be used. WARNING: That default service agent is shared + across all Agent Engines in the project that do not specify an + isolated identity or custom service account, so any principal + with permission to deploy or update agents in the project can + access permissions or secrets granted to it. Use + `identity_type="AGENT_IDENTITY"` (restricting + `aiplatform.reasoningEngines.update` access on the engine) or a + dedicated custom `service_account` for sensitive resources such + as Secret Manager secrets. identity_type (Union[str, ReasoningEngineSpec.IdentityType]): Optional. The identity type to be used by the Agent Engine at runtime. Set it to `AGENT_IDENTITY` to run the Agent Engine under a resource-scoped workload identity with no default project permissions, instead of the shared Reasoning Engine Service Agent. - `service_account` must not be specified when `AGENT_IDENTITY` is - used. If not specified, `service_account` is used if set, otherwise - the default Reasoning Engine Service Agent is used. + Restrict `aiplatform.reasoningEngines.update` permissions on + `AGENT_IDENTITY` engines because any principal permitted to update + the engine can run code as its identity. `service_account` must not + be specified when `AGENT_IDENTITY` is used. If not specified, + `service_account` is used if set, otherwise the default Reasoning + Engine Service Agent is used. psc_interface_config (PscInterfaceConfig): Optional. The PSC interface config for the Agent Engine. If not specified, the default PSC interface config will be used. @@ -359,21 +378,33 @@ def update( Agent Engine. If it is a list of strings, each string should be a valid key to `os.environ`. If it is a dictionary, the keys are the environment variable names, and the values are the - corresponding values. + corresponding values (strings or `SecretRef` entries for Secret + Manager secrets). When referencing Secret Manager secrets, grant + `roles/secretmanager.secretAccessor` on the specific secret to + an isolated `AGENT_IDENTITY` or a dedicated custom + `service_account`; avoid granting secret access to the shared + default Reasoning Engine Service Agent. build_options (Dict[str, Sequence[str]]): Optional. The build options for the Agent Engine. This includes options such as installation scripts. service_account (str): - Optional. The service account to be used for the Agent Engine. If - not specified, the default reasoning engine service agent service - account will be used. + Optional. The service account to be used for the Agent Engine. + If not specified, the existing service account is used. + Avoid granting sensitive permissions or Secret Manager secrets + to the shared default Reasoning Engine Service Agent; prefer + `identity_type="AGENT_IDENTITY"` (restricting + `aiplatform.reasoningEngines.update` access) or a dedicated + custom `service_account`. identity_type (Union[str, ReasoningEngineSpec.IdentityType]): Optional. The identity type to be used by the Agent Engine at runtime. Set it to `AGENT_IDENTITY` to run the Agent Engine under a resource-scoped workload identity with no default project permissions, instead of the shared Reasoning Engine Service Agent. - `service_account` must not be specified when `AGENT_IDENTITY` is - used. If not specified, the existing identity type will be used. + Restrict `aiplatform.reasoningEngines.update` permissions on + `AGENT_IDENTITY` engines because any principal permitted to update + the engine can run code as its identity. `service_account` must not + be specified when `AGENT_IDENTITY` is used. If not specified, the + existing identity type will be used. min_instances (int): Optional. The minimum number of instances to run the Agent Engine. If not specified, the default value will be used. diff --git a/vertexai/agent_engines/_agent_engines.py b/vertexai/agent_engines/_agent_engines.py index fbba646e62..cd3828a980 100644 --- a/vertexai/agent_engines/_agent_engines.py +++ b/vertexai/agent_engines/_agent_engines.py @@ -470,7 +470,14 @@ def create( Agent Engine. If it is a list of strings, each string should be a valid key to `os.environ`. If it is a dictionary, the keys are the environment variable names, and the values are the - corresponding values. + corresponding values (strings or `SecretRef` entries for Secret + Manager secrets). When referencing Secret Manager secrets, grant + `roles/secretmanager.secretAccessor` on the specific secret to + an isolated `AGENT_IDENTITY` (create the Agent Engine first + without secrets, grant access to + `principal://{effective_identity}`, then update) or a dedicated + custom `service_account`; avoid granting secret access to the + shared default Reasoning Engine Service Agent. build_options (Dict[str, Sequence[str]]): Optional. The build options for the Agent Engine. The following keys are supported: @@ -483,17 +490,29 @@ def create( working directory and included in `extra_packages`. service_account (str): Optional. The service account to be used for the Agent Engine. - If not specified, the default reasoning engine service agent - service account will be used. + If not specified and `identity_type` is not `AGENT_IDENTITY`, + the default Vertex AI Reasoning Engine Service Agent, + `service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`, + will be used. WARNING: That default service agent is shared + across all Agent Engines in the project that do not specify an + isolated identity or custom service account, so any principal + with permission to deploy or update agents in the project can + access permissions or secrets granted to it. Use + `identity_type="AGENT_IDENTITY"` (restricting + `aiplatform.reasoningEngines.update` access on the engine) or a + dedicated custom `service_account` for sensitive resources such + as Secret Manager secrets. identity_type (Union[str, aip_types.ReasoningEngineSpec.IdentityType]): Optional. The identity type to be used by the Agent Engine at runtime. Set it to `AGENT_IDENTITY` to run the Agent Engine under a resource-scoped workload identity with no default project permissions, instead of the shared Reasoning Engine - Service Agent. `service_account` must not be specified when - `AGENT_IDENTITY` is used. If not specified, `service_account` - is used if set, otherwise the default Reasoning Engine Service - Agent is used. + Service Agent. Restrict `aiplatform.reasoningEngines.update` + permissions on `AGENT_IDENTITY` engines because any principal + permitted to update the engine can run code as its identity. + `service_account` must not be specified when `AGENT_IDENTITY` is + used. If not specified, `service_account` is used if set, + otherwise the default Reasoning Engine Service Agent is used. psc_interface_config (aip_types.PscInterfaceConfig): Optional. The Private Service Connect interface config for the Agent Engine. @@ -742,7 +761,12 @@ def update( Agent Engine. If it is a list of strings, each string should be a valid key to `os.environ`. If it is a dictionary, the keys are the environment variable names, and the values are the - corresponding values. + corresponding values (strings or `SecretRef` entries for Secret + Manager secrets). When referencing Secret Manager secrets, grant + `roles/secretmanager.secretAccessor` on the specific secret to + an isolated `AGENT_IDENTITY` or a dedicated custom + `service_account`; avoid granting secret access to the shared + default Reasoning Engine Service Agent. build_options (Dict[str, Sequence[str]]): Optional. The build options for the Agent Engine. The following keys are supported: @@ -755,16 +779,22 @@ def update( working directory and included in `extra_packages`. service_account (str): Optional. The service account to be used for the Agent Engine. - If not specified, the default reasoning engine service agent - service account will be used. + If not specified, the existing service account is used. + Avoid granting sensitive permissions or Secret Manager secrets + to the shared default Reasoning Engine Service Agent; prefer + `identity_type="AGENT_IDENTITY"` (restricting + `aiplatform.reasoningEngines.update` access) or a dedicated + custom `service_account`. identity_type (Union[str, aip_types.ReasoningEngineSpec.IdentityType]): Optional. The identity type to be used by the Agent Engine at runtime. Set it to `AGENT_IDENTITY` to run the Agent Engine under a resource-scoped workload identity with no default project permissions, instead of the shared Reasoning Engine - Service Agent. `service_account` must not be specified when - `AGENT_IDENTITY` is used. If not specified, the existing - identity type will be used. + Service Agent. Restrict `aiplatform.reasoningEngines.update` + permissions on `AGENT_IDENTITY` engines because any principal + permitted to update the engine can run code as its identity. + `service_account` must not be specified when `AGENT_IDENTITY` is + used. If not specified, the existing identity type will be used. psc_interface_config (aip_types.PscInterfaceConfig): Optional. The Private Service Connect interface config for the Agent Engine. diff --git a/vertexai/reasoning_engines/_reasoning_engines.py b/vertexai/reasoning_engines/_reasoning_engines.py index 8cf3002279..539cbdb0dc 100644 --- a/vertexai/reasoning_engines/_reasoning_engines.py +++ b/vertexai/reasoning_engines/_reasoning_engines.py @@ -234,17 +234,31 @@ def create( Optional. The set of extra user-provided packages (if any). service_account (str): Optional. The service account that the Reasoning Engine runs - as. If not specified, the default Reasoning Engine Service - Agent in the project will be used. + as. If not specified and `identity_type` is not + `AGENT_IDENTITY`, the default Vertex AI Reasoning Engine + Service Agent, + `service-{project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com`, + will be used. WARNING: That default service agent is shared + across all Reasoning Engines in the project that do not specify + an isolated identity or custom service account, so any + principal with permission to deploy or update engines in the + project can access permissions or secrets granted to it. Use + `identity_type="AGENT_IDENTITY"` (restricting + `aiplatform.reasoningEngines.update` access on the engine) or a + dedicated custom `service_account` for sensitive resources such + as Secret Manager secrets. identity_type (Union[str, aip_types.ReasoningEngineSpec.IdentityType]): Optional. The identity type to be used by the Reasoning Engine at runtime. Set it to `AGENT_IDENTITY` to run the Reasoning Engine under a resource-scoped workload identity with no default project permissions, instead of the shared Reasoning - Engine Service Agent. `service_account` must not be specified - when `AGENT_IDENTITY` is used. If not specified, - `service_account` is used if set, otherwise the default - Reasoning Engine Service Agent is used. + Engine Service Agent. Restrict + `aiplatform.reasoningEngines.update` permissions on + `AGENT_IDENTITY` engines because any principal permitted to + update the engine can run code as its identity. + `service_account` must not be specified when `AGENT_IDENTITY` + is used. If not specified, `service_account` is used if set, + otherwise the default Reasoning Engine Service Agent is used. Returns: ReasoningEngine: The Reasoning Engine that was created. @@ -423,15 +437,23 @@ def update( service_account (str): Optional. The service account that the Reasoning Engine runs as. If not specified, the existing service account will be - used. + used. Avoid granting sensitive permissions or Secret Manager + secrets to the shared default Reasoning Engine Service Agent; + prefer `identity_type="AGENT_IDENTITY"` (restricting + `aiplatform.reasoningEngines.update` access) or a dedicated + custom `service_account`. identity_type (Union[str, aip_types.ReasoningEngineSpec.IdentityType]): Optional. The identity type to be used by the Reasoning Engine at runtime. Set it to `AGENT_IDENTITY` to run the Reasoning Engine under a resource-scoped workload identity with no default project permissions, instead of the shared Reasoning - Engine Service Agent. `service_account` must not be specified - when `AGENT_IDENTITY` is used. If not specified, the existing - identity type will be used. + Engine Service Agent. Restrict + `aiplatform.reasoningEngines.update` permissions on + `AGENT_IDENTITY` engines because any principal permitted to + update the engine can run code as its identity. + `service_account` must not be specified when `AGENT_IDENTITY` + is used. If not specified, the existing identity type will be + used. Returns: ReasoningEngine: The Reasoning Engine that was updated.