Skip to main content

gadk_cli/deploy/
agentengine.rs

1// Copyright 2026 Chris Olson
2// Portions derived from ADK-Go (https://github.com/google/adk-go), Copyright 2026 Google LLC.
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8//     http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16//! `gadk deploy agentengine`.
17//!
18//! The flag structs keep ADK's shape (the nested flag groups, field for field in ADK's order);
19//! gadk's additions (`bin`, `target`) sit after those fields. The flags are not printed:
20//! `--env` values may be secrets.
21//!
22//! `compute_flags` resolves the Cargo target where ADK splits an entry-point path, and fixes
23//! the archive root (`-d`, else the Cargo workspace root); the derived fields are set as
24//! ADK sets them (`exec_file` = the binary, `src_base_path` = the package directory,
25//! `source_dir` = the absolute archive root). Vertex AI is reached through
26//! `gadk_vertexai::reasoning_engine` with [`Env::vertex`].
27
28use std::ffi::OsString;
29use std::fs::{self, OpenOptions};
30use std::io::{ErrorKind, Write};
31use std::os::unix::fs::OpenOptionsExt;
32use std::path::{Path, PathBuf};
33use std::time::Duration;
34
35use base64::Engine;
36use base64::engine::general_purpose::STANDARD;
37use chrono::{Local, SecondsFormat};
38use clap::{ArgMatches, Command};
39use gadk_platform::{GoDuration, go_path_clean, go_path_join, go_quote};
40use gadk_vertexai::reasoning_engine::{ReasoningEngineClient, ReasoningEngineOptions};
41use serde_json::{Value, json};
42
43use crate::Env;
44use crate::flags::{
45    STRAY_ARGS, bool_flag, bool_value, duration_flag, duration_value, int_flag, int_value, passed,
46    pflag_command, stray_args, string_flag, string_value,
47};
48use crate::stage::{BuilderStage, SourceTree, dockerfile, make_temp};
49use crate::target::{
50    COMPILED_RUSTC_VERSION, CargoTarget, builder_image, builder_rust_version,
51    check_path_dependencies, resolve,
52};
53use crate::util::{Printer, log_start_stop, validate_shell_arg_safe};
54
55pub mod environment;
56#[cfg(test)]
57pub(crate) mod tests;
58
59use environment::{EnvVar, deployment_spec, register_environment_flags};
60
61/// The bound on waiting for a create/update operation.
62pub const AGENT_ENGINE_OPERATION_TIMEOUT: Duration = Duration::from_secs(45 * 60);
63
64/// The command's short description.
65pub const SHORT: &str = "Deploys the application to Agent Engine.";
66/// The command's long description.
67pub const LONG: &str = "Deploys the application to Agent Engine. It creates a source archive, uploads it to create a Reasoning Engine, and cleans up temporary files.";
68
69/// The gcloud flags.
70#[derive(Debug, Clone, Default, PartialEq, Eq)]
71pub struct GCloudFlags {
72    pub region: String,
73    pub project_name: String,
74}
75
76/// The memory bank flags.
77#[derive(Debug, Clone, Default, PartialEq, Eq)]
78pub struct MemoryBankFlags {
79    pub deploy: bool,
80    pub model: String,
81    pub ttl: GoDuration,
82}
83
84/// The Agent Engine service flags. `Debug` shows the `--env` names only: values may be secrets.
85#[derive(Clone, Default, PartialEq, Eq)]
86pub struct AgentEngineServiceFlags {
87    pub name: String,
88    pub display_name: String,
89    pub server_port: i64,
90    pub agent_engine_id: String,
91    pub memory_bank: MemoryBankFlags,
92    /// `--env` entries, verbatim (unvalidated until
93    /// [`AgentEngineFlags::environment_variables`]).
94    pub env: Vec<OsString>,
95    /// `--default_env`.
96    pub default_env: bool,
97    /// The environment [`AgentEngineFlags::compute_flags`] computed.
98    pub env_vars: Vec<EnvVar>,
99    /// `--env` or `--default_env` was on the command line: an update
100    /// replaces the environment.
101    pub update_env: bool,
102}
103
104impl std::fmt::Debug for AgentEngineServiceFlags {
105    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
106        // Each `--env` entry as its name (the text before the first `=`), value redacted; an
107        // entry without `=` is malformed and could be a bare value, so it is redacted whole.
108        let env: Vec<String> = self
109            .env
110            .iter()
111            .map(|e| {
112                let e = e.to_string_lossy();
113                match e.split_once('=') {
114                    Some((name, _)) => format!("{name}=<redacted>"),
115                    None => "<redacted>".to_owned(),
116                }
117            })
118            .collect();
119        f.debug_struct("AgentEngineServiceFlags")
120            .field("name", &self.name)
121            .field("display_name", &self.display_name)
122            .field("server_port", &self.server_port)
123            .field("agent_engine_id", &self.agent_engine_id)
124            .field("memory_bank", &self.memory_bank)
125            .field("env", &env)
126            .field("default_env", &self.default_env)
127            .field("env_vars", &self.env_vars)
128            .field("update_env", &self.update_env)
129            .finish()
130    }
131}
132
133/// The build flags: the temp dir and the paths derived from it by `compute_flags`.
134#[derive(Debug, Clone, Default, PartialEq, Eq)]
135pub struct BuildFlags {
136    pub temp_dir: String,
137    pub exec_path: String,
138    pub exec_file: String,
139    pub dockerfile_build_path: String,
140    pub archive_path: String,
141}
142
143/// The source flags: the entry point, its original form and the derived source paths.
144#[derive(Debug, Clone, Default, PartialEq, Eq)]
145pub struct SourceFlags {
146    pub src_base_path: String,
147    pub entry_point_path: String,
148    pub orig_entry_point_path: String,
149    pub source_dir: String,
150}
151
152/// The flags of `gadk deploy agentengine`, plus gadk's `--bin` and the resolved Cargo target.
153#[derive(Debug, Clone, Default, PartialEq, Eq)]
154pub struct AgentEngineFlags {
155    pub gcloud: GCloudFlags,
156    pub agent_engine: AgentEngineServiceFlags,
157    pub build: BuildFlags,
158    pub source: SourceFlags,
159    /// gadk's `--bin` (not printed).
160    pub bin: String,
161    /// The Cargo target `compute_flags` resolved (not printed).
162    pub target: Option<CargoTarget>,
163}
164
165/// The `agentengine` command with its flags, in ADK's order, plus gadk's `--bin`.
166/// Positional arguments are collected (not a clap error) so [`validate_args`] can reject them
167/// with ADK's text.
168pub fn command() -> Command {
169    let cmd = pflag_command("agentengine")
170        .about(SHORT)
171        .long_about(LONG)
172        .arg(string_flag("region", Some('r'), "", "GCP Region"))
173        .arg(string_flag("project_name", Some('p'), "", "GCP Project Name"))
174        .arg(string_flag("name", Some('s'), "", "Agent Engine name"))
175        .arg(string_flag(
176            "temp_dir",
177            Some('t'),
178            "",
179            "Temp dir for build, defaults to os.TempDir() if not specified",
180        ))
181        .arg(int_flag("server_port", None, "8080", "agentEngine server port"))
182        // `-e` names a Cargo package.
183        .arg(string_flag(
184            "entry_point_path",
185            Some('e'),
186            "",
187            "Path to the Cargo package of the entry point (its directory or Cargo.toml), defaults to the current directory",
188        ))
189        // The archive root defaults to the Cargo workspace root.
190        .arg(string_flag(
191            "source_dir",
192            Some('d'),
193            "",
194            "Directory to archive (the Cargo workspace root or an ancestor of it), defaults to the Cargo workspace root",
195        ))
196        .arg(string_flag(
197            "agent_engine_id",
198            None,
199            "",
200            "ID of the Agent Engine instance to update if it exists (default: \"\", which means a new instance will be created).",
201        ))
202        .arg(bool_flag(
203            "mem_deploy",
204            false,
205            "If set to true then memory bank will be deployed too",
206        ))
207        .arg(string_flag(
208            "mem_model",
209            None,
210            "",
211            "Name of the model to be used for memory generation, as publishers/google/models/<model_id>. If empty, Memory Bank uses its own default model. A non-empty value is prefixed with projects/<project_name>/locations/<region>, so the model must be available in that region. To list models, GET https://${LOCATION_ID}-aiplatform.googleapis.com/v1beta1/publishers/google/models",
212        ))
213        .arg(duration_flag(
214            "mem_ttl",
215            None,
216            "8760h0m0s",
217            "Time-To-Live for memories",
218        ));
219    register_environment_flags(cmd)
220        // A gadk-only flag selecting the Cargo binary target.
221        .arg(string_flag(
222            "bin",
223            None,
224            "",
225            "Binary target of the package to deploy, required when the package has more than one",
226        ))
227        .arg(stray_args())
228}
229
230/// Accepts no positional arguments: any positional argument fails with
231/// `accepts 0 arg(s), received N`, which does not echo the arguments; runs before
232/// anything else.
233pub fn validate_args(m: &ArgMatches) -> Result<(), String> {
234    let n = m.get_raw(STRAY_ARGS).map_or(0, |v| v.len());
235    if n != 0 {
236        return Err(format!("accepts 0 arg(s), received {n}"));
237    }
238    Ok(())
239}
240
241/// The flags of a parsed `agentengine` command;
242/// the derived fields are empty until [`AgentEngineFlags::compute_flags`].
243pub fn from_matches(m: &ArgMatches) -> AgentEngineFlags {
244    AgentEngineFlags {
245        gcloud: GCloudFlags {
246            region: string_value(m, "region"),
247            project_name: string_value(m, "project_name"),
248        },
249        agent_engine: AgentEngineServiceFlags {
250            name: string_value(m, "name"),
251            display_name: String::new(),
252            server_port: int_value(m, "server_port"),
253            agent_engine_id: string_value(m, "agent_engine_id"),
254            memory_bank: MemoryBankFlags {
255                deploy: bool_value(m, "mem_deploy"),
256                model: string_value(m, "mem_model"),
257                ttl: duration_value(m, "mem_ttl"),
258            },
259            env: m
260                .get_many::<OsString>("env")
261                .map(|v| v.cloned().collect())
262                .unwrap_or_default(),
263            default_env: bool_value(m, "default_env"),
264            env_vars: Vec::new(),
265            update_env: passed(m, "env") || passed(m, "default_env"),
266        },
267        build: BuildFlags {
268            temp_dir: string_value(m, "temp_dir"),
269            ..BuildFlags::default()
270        },
271        source: SourceFlags {
272            entry_point_path: string_value(m, "entry_point_path"),
273            source_dir: string_value(m, "source_dir"),
274            ..SourceFlags::default()
275        },
276        bin: string_value(m, "bin"),
277        target: None,
278    }
279}
280
281/// `path` relative to `root` when `path` is `root` or lies under it: compared lexically (both
282/// cleaned), else once both resolve (a symlinked temp or source dir).
283fn relative_to(path: &Path, root: &Path) -> Option<PathBuf> {
284    let clean = |p: &Path| PathBuf::from(go_path_clean(&p.to_string_lossy()));
285    if let Ok(rel) = clean(path).strip_prefix(clean(root)) {
286        return Some(rel.to_path_buf());
287    }
288    let (path, root) = (fs::canonicalize(path).ok()?, fs::canonicalize(root).ok()?);
289    path.strip_prefix(root).ok().map(Path::to_path_buf)
290}
291
292/// A `google.protobuf.Duration` in its JSON form: seconds with 0, 3, 6 or 9 fractional digits and
293/// an `s` suffix (`86400s`, `1.500s`, `-0.000000001s`).
294fn protojson_duration(d: GoDuration) -> String {
295    let (secs, nanos) = (d.0 / 1_000_000_000, d.0 % 1_000_000_000);
296    let sign = if secs == 0 && nanos < 0 { "-" } else { "" };
297    let x = format!("{sign}{secs}.{:09}", nanos.unsigned_abs());
298    let x = x.strip_suffix("000").unwrap_or(&x);
299    let x = x.strip_suffix("000").unwrap_or(x);
300    let x = x.strip_suffix(".000").unwrap_or(x);
301    format!("{x}s")
302}
303
304/// Waits for the operation, bounded by [`AGENT_ENGINE_OPERATION_TIMEOUT`],
305/// wrapped as `operation failed: <error>`.
306async fn wait_for_operation(client: &ReasoningEngineClient, op: Value) -> Result<Value, String> {
307    match tokio::time::timeout(AGENT_ENGINE_OPERATION_TIMEOUT, client.wait(op)).await {
308        Ok(Ok(engine)) => Ok(engine),
309        Ok(Err(e)) => Err(format!("operation failed: {e}")),
310        Err(_) => Err("operation failed: context deadline exceeded".to_string()),
311    }
312}
313
314/// A string field of a JSON message (`""` when absent).
315fn str_field<'a>(v: &'a Value, name: &str) -> &'a str {
316    v.get(name).and_then(Value::as_str).unwrap_or_default()
317}
318
319impl AgentEngineFlags {
320    /// Computes the derived flags: the environment (validated first, before any other step),
321    /// target resolution, the shell-safe checks, the archive root,
322    /// the `agentEngine_<local time>__*` temp dir, the derived paths, the display name and the
323    /// `--mem_model` prefix. Every check runs before the temp dir is created.
324    pub async fn compute_flags(&mut self, env: &Env) -> Result<(), String> {
325        log_start_stop(
326            &env.out,
327            "Computing flags & preparing temp",
328            async |p: Printer| {
329                self.agent_engine.env_vars = self.environment_variables()?;
330                self.source.orig_entry_point_path = self.source.entry_point_path.clone();
331                let orig = self.source.orig_entry_point_path.clone();
332                self.source.entry_point_path = env.abs(&orig).to_string_lossy().into_owned();
333
334                // Resolves the Cargo package and binary, the binary standing in for `exec_file`
335                // and the package directory for `src_base_path`.
336                let target = resolve(env, &orig, &self.bin).await?;
337                self.source.src_base_path = target.manifest_dir.to_string_lossy().into_owned();
338                if self.build.exec_path.is_empty() {
339                    self.build.exec_file = target.bin.clone();
340                }
341
342                validate_shell_arg_safe(
343                    &self.build.exec_file,
344                    &format!(
345                        "executable name derived from --entry_point_path {}:",
346                        go_quote(&orig)
347                    ),
348                )?;
349                // The package name reaches the RUN line's `-p`.
350                validate_shell_arg_safe(
351                    &target.package,
352                    &format!(
353                        "package name derived from --entry_point_path {}:",
354                        go_quote(&orig)
355                    ),
356                )?;
357                validate_shell_arg_safe(&orig, "--entry_point_path")?;
358
359                // The archive root is `-d` or else the Cargo workspace
360                // root, and must contain the workspace root,
361                // whose path below it becomes the builder's WORKDIR.
362                let archive_root = if self.source.source_dir.is_empty() {
363                    target.workspace_root.clone()
364                } else {
365                    env.abs(&self.source.source_dir)
366                };
367                let Some(workdir) = relative_to(&target.workspace_root, &archive_root) else {
368                    return Err(format!(
369                        "--source_dir {} is neither the Cargo workspace root {} nor an ancestor of it",
370                        go_quote(&self.source.source_dir),
371                        go_quote(&target.workspace_root.to_string_lossy())
372                    ));
373                };
374                validate_shell_arg_safe(workdir.as_os_str().as_encoded_bytes(), "--source_dir")?;
375                check_path_dependencies(&target, &archive_root)?;
376                self.source.source_dir = archive_root.to_string_lossy().into_owned();
377                self.target = Some(target);
378
379                if self.build.temp_dir.is_empty() {
380                    self.build.temp_dir = env.temp_dir().to_string_lossy().into_owned();
381                }
382                let absp = env.abs(&self.build.temp_dir);
383                // The wrapped error is Rust's `io::Error` text.
384                let dir = make_temp(&absp, "agentEngine_", env.time.now()).map_err(|e| {
385                    format!(
386                        "cannot create a temporary sub directory in '{}': {e}",
387                        absp.display()
388                    )
389                })?;
390                self.build.temp_dir = dir.to_string_lossy().into_owned();
391                p.print(&[&"Using temp dir:", &self.build.temp_dir]);
392
393                if self.build.exec_path.is_empty() {
394                    self.build.exec_path = go_path_join(&[&self.build.temp_dir, &self.build.exec_file]);
395                }
396                self.build.dockerfile_build_path =
397                    go_path_join(&[self.build.temp_dir.as_str(), "Dockerfile"]);
398                self.build.archive_path = go_path_join(&[self.build.temp_dir.as_str(), "archive.tgz"]);
399
400                let date_time = env
401                    .time
402                    .now()
403                    .with_timezone(&Local)
404                    .to_rfc3339_opts(SecondsFormat::Secs, true);
405                self.agent_engine.display_name = self.agent_engine.name.clone();
406                if self.agent_engine.display_name.is_empty() {
407                    self.agent_engine.display_name = format!("ADK Agent: {date_time}");
408                }
409
410                // prefix an explicit model with the project and region
411                if !self.agent_engine.memory_bank.model.is_empty() {
412                    self.agent_engine.memory_bank.model = format!(
413                        "projects/{}/locations/{}/{}",
414                        self.gcloud.project_name,
415                        self.gcloud.region,
416                        self.agent_engine.memory_bank.model
417                    );
418                }
419                Ok(())
420            },
421        )
422        .await
423    }
424
425    /// Removes the temp dir.
426    pub async fn clean_temp(&self, env: &Env) -> Result<(), String> {
427        log_start_stop(&env.out, "Cleaning temp", async |p: Printer| {
428            p.print(&[&"Clean temp starting with", &self.build.temp_dir]);
429            // The wrapped error is Rust's `io::Error` text.
430            match fs::remove_dir_all(&self.build.temp_dir) {
431                // A missing path is not an error.
432                Err(e) if e.kind() != ErrorKind::NotFound => Err(format!(
433                    "failed to clean temp directory {}: {e}",
434                    self.build.temp_dir
435                )),
436                _ => Ok(()),
437            }
438        })
439        .await
440    }
441
442    /// The directory archived: `source_dir` (absolute
443    /// after [`compute_flags`](Self::compute_flags)), else the target's workspace root.
444    fn archive_root(&self) -> PathBuf {
445        if self.source.source_dir.is_empty() {
446            self.target
447                .as_ref()
448                .map(|t| t.workspace_root.clone())
449                .unwrap_or_default()
450        } else {
451            PathBuf::from(&self.source.source_dir)
452        }
453    }
454
455    /// Prepares the Dockerfile: reads only the receiver (the builder version from the
456    /// target's workspace, `WORKDIR /app/<workspace root below the archive root>`, `-p
457    /// <package> --bin <exec_file>`, `EXPOSE`/`CMD` from `server_port`), written with mode 0600.
458    pub async fn prepare_dockerfile(&self, env: &Env) -> Result<(), String> {
459        log_start_stop(&env.out, "Preparing Dockerfile", async |p: Printer| {
460            p.print(&[&"Writing:", &self.build.dockerfile_build_path]);
461            let target = self.target.clone().unwrap_or_default();
462            let workdir = relative_to(&target.workspace_root, &self.archive_root())
463                .map(|w| w.to_string_lossy().into_owned())
464                .unwrap_or_default();
465            let builder = BuilderStage {
466                image: builder_image(&builder_rust_version(&target, COMPILED_RUSTC_VERSION)),
467                workdir,
468                package: target.package,
469                bin: self.build.exec_file.clone(),
470            };
471            let text = dockerfile(
472                &builder,
473                self.agent_engine.server_port,
474                r#", "agentengine""#,
475            );
476            // The error is Rust's `io::Error` text.
477            OpenOptions::new()
478                .write(true)
479                .create(true)
480                .truncate(true)
481                .mode(0o600)
482                .open(&self.build.dockerfile_build_path)
483                .and_then(|mut f| f.write_all(text.as_bytes()))
484                .map_err(|e| e.to_string())
485        })
486        .await
487    }
488
489    /// Creates the archive: the sorted tar.gz of the archive root (without `.git`,
490    /// `target`, a nested temp dir and the root `Dockerfile`) with the generated `Dockerfile`
491    /// last.
492    // The archive is written in-process (no `Running :` line, gadk's error texts) and leaves
493    // out a root `Dockerfile` of the source, so only the generated one is archived.
494    pub async fn create_archive(&self, env: &Env) -> Result<(), String> {
495        log_start_stop(&env.out, "Creating source archive", async |p: Printer| {
496            let root = self.archive_root();
497            p.print(&[&"Creating:", &self.build.archive_path]);
498            let mut exclude = vec![root.join("Dockerfile")];
499            if let Some(rel) = relative_to(Path::new(&self.build.temp_dir), &root)
500                && !rel.as_os_str().is_empty()
501            {
502                exclude.push(root.join(rel));
503            }
504            let tree = SourceTree::walk(&root, &exclude).map_err(|e| {
505                format!(
506                    "cannot read the source directory {}: {e}",
507                    go_quote(&root.to_string_lossy())
508                )
509            })?;
510            let generated = fs::read(&self.build.dockerfile_build_path)
511                .map_err(|e| format!("cannot read the generated Dockerfile: {e}"))?;
512            tree.write_tar_gz(
513                Path::new(&self.build.archive_path),
514                &[("Dockerfile", generated.as_slice())],
515            )
516            .map_err(|e| {
517                format!(
518                    "cannot write the source archive {}: {e}",
519                    go_quote(&self.build.archive_path)
520                )
521            })
522        })
523        .await
524    }
525
526    /// The memory bank context spec as a `ReasoningEngineContextSpec` in JSON form:
527    /// `memoryBankConfig.ttlConfig.defaultTtl` = `--mem_ttl`, and
528    /// `memoryBankConfig.generationConfig.model` only for a non-empty `--mem_model`.
529    pub fn memory_bank_context_spec(&self) -> Value {
530        let mb = &self.agent_engine.memory_bank;
531        let mut cfg = json!({"ttlConfig": {"defaultTtl": protojson_duration(mb.ttl)}});
532        if !mb.model.is_empty() {
533            cfg["generationConfig"] = json!({"model": mb.model});
534        }
535        json!({"memoryBankConfig": cfg})
536    }
537
538    /// Builds the Reasoning Engine client for the region's Vertex AI endpoint
539    /// with [`Env::vertex`]; ADC reads [`Env::env`] unless the options name an environment.
540    fn client(&self, env: &Env) -> Result<ReasoningEngineClient, String> {
541        let mut opts: ReasoningEngineOptions = env.vertex.clone();
542        if opts.env.is_none() {
543            opts.env = Some(env.env.clone());
544        }
545        ReasoningEngineClient::new(&self.gcloud.region, opts)
546            .map_err(|e| format!("cannot create ReasoningEngineClient: {e}"))
547    }
548
549    /// The parts of the create and update requests read from disk and the server package:
550    /// the `sourceCodeSpec` (inline archive, empty `imageSpec`) and the class methods,
551    /// printing `Methods: <json>`.
552    fn source_code_spec_and_methods(&self, p: &Printer) -> Result<(Value, Value), String> {
553        // The wrapped error is Rust's `io::Error` text.
554        let archive = fs::read(&self.build.archive_path)
555            .map_err(|e| format!("cannot read archive file: {e}"))?;
556        let methods = gadk_server::agentengine::list_class_methods();
557        let methods_json =
558            gadk_model::to_go_json(&methods).map_err(|e| format!("cannot marshal methods: {e}"))?;
559        p.print(&[&"Methods:", &String::from_utf8_lossy(&methods_json)]);
560        let source_code_spec = json!({
561            "inlineSource": {"sourceArchive": STANDARD.encode(&archive)},
562            "imageSpec": {},
563        });
564        Ok((source_code_spec, Value::from(methods)))
565    }
566
567    /// Creates the Reasoning Engine: `CreateReasoningEngine` under
568    /// `projects/<p>/locations/<r>`, then the operation awaited for at most 45 minutes.
569    pub async fn deploy_to_agent_engine(&self, env: &Env) -> Result<(), String> {
570        log_start_stop(&env.out, "Deploying to Agent Engine", async |p: Printer| {
571            let parent = format!(
572                "projects/{}/locations/{}",
573                self.gcloud.project_name, self.gcloud.region
574            );
575            let client = self.client(env)?;
576            let (source_code_spec, methods) = self.source_code_spec_and_methods(&p)?;
577            let mut engine = json!({
578                "displayName": self.agent_engine.display_name,
579                "spec": {
580                    "sourceCodeSpec": source_code_spec,
581                    "agentFramework": "google-adk",
582                    "deploymentSpec": deployment_spec(&self.agent_engine.env_vars),
583                    "classMethods": methods,
584                },
585            });
586            if self.agent_engine.memory_bank.deploy {
587                engine["contextSpec"] = self.memory_bank_context_spec();
588            }
589
590            p.print(&[&"Sending CreateReasoningEngine request..."]);
591            let op = client
592                .create(&parent, engine)
593                .await
594                .map_err(|e| format!("CreateReasoningEngine failed: {e}"))?;
595
596            p.print(&[&"Waiting for operation to complete..."]);
597            let re = wait_for_operation(&client, op).await?;
598
599            p.print(&[&"Deployed Reasoning Engine:", &str_field(&re, "name")]);
600            p.print(&[&"Display Name:", &str_field(&re, "displayName")]);
601            Ok(())
602        })
603        .await
604    }
605
606    /// Updates the Reasoning Engine: `UpdateReasoningEngine` of
607    /// `projects/<p>/locations/<r>/reasoningEngines/<id>` with the update mask in JSON
608    /// form (the environment only when [`AgentEngineServiceFlags::update_env`], before the
609    /// memory bank's `spec.contextSpec`), then the operation awaited for at most 45 minutes.
610    pub async fn update_agent_engine(&self, env: &Env) -> Result<(), String> {
611        log_start_stop(&env.out, "Updating Agent Engine", async |p: Printer| {
612            let name = format!(
613                "projects/{}/locations/{}/reasoningEngines/{}",
614                self.gcloud.project_name, self.gcloud.region, self.agent_engine.agent_engine_id
615            );
616            let client = self.client(env)?;
617            let (source_code_spec, methods) = self.source_code_spec_and_methods(&p)?;
618            let mut engine = json!({
619                "name": name,
620                "spec": {
621                    "sourceCodeSpec": source_code_spec,
622                    "classMethods": methods,
623                },
624            });
625            let mut mask = vec!["spec.sourceCodeSpec", "spec.classMethods"];
626            if self.agent_engine.update_env {
627                engine["spec"]["deploymentSpec"] = deployment_spec(&self.agent_engine.env_vars);
628                mask.push("spec.deploymentSpec.env");
629            }
630            if self.agent_engine.memory_bank.deploy {
631                engine["contextSpec"] = self.memory_bank_context_spec();
632                // The mask path `spec.context_spec` is kept (in JSON form) although `contextSpec`
633                // is a top-level ReasoningEngine field.
634                mask.push("spec.contextSpec");
635            }
636
637            p.print(&[&"Sending UpdateReasoningEngine request..."]);
638            let op = client
639                .update(engine, &mask)
640                .await
641                .map_err(|e| format!("UpdateReasoningEngine failed: {e}"))?;
642
643            p.print(&[&"Waiting for operation to complete..."]);
644            let re = wait_for_operation(&client, op).await?;
645
646            p.print(&[&"Updated Reasoning Engine:", &str_field(&re, "name")]);
647            p.print(&[&"Display Name:", &str_field(&re, "displayName")]);
648            Ok(())
649        })
650        .await
651    }
652
653    /// Deploys: compute → Dockerfile → archive → update|deploy → clean,
654    /// stopping at the first error (the temp dir is kept).
655    pub async fn deploy_on_agent_engine(&mut self, env: &Env) -> Result<(), String> {
656        self.compute_flags(env).await?;
657        self.prepare_dockerfile(env).await?;
658        self.create_archive(env).await?;
659        if !self.agent_engine.agent_engine_id.is_empty() {
660            self.update_agent_engine(env).await?;
661        } else {
662            self.deploy_to_agent_engine(env).await?;
663        }
664        self.clean_temp(env).await
665    }
666}