1use 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
61pub const AGENT_ENGINE_OPERATION_TIMEOUT: Duration = Duration::from_secs(45 * 60);
63
64pub const SHORT: &str = "Deploys the application to Agent Engine.";
66pub 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#[derive(Debug, Clone, Default, PartialEq, Eq)]
71pub struct GCloudFlags {
72 pub region: String,
73 pub project_name: String,
74}
75
76#[derive(Debug, Clone, Default, PartialEq, Eq)]
78pub struct MemoryBankFlags {
79 pub deploy: bool,
80 pub model: String,
81 pub ttl: GoDuration,
82}
83
84#[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 pub env: Vec<OsString>,
95 pub default_env: bool,
97 pub env_vars: Vec<EnvVar>,
99 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 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#[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#[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#[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 pub bin: String,
161 pub target: Option<CargoTarget>,
163}
164
165pub 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 .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 .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 .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
230pub 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
241pub 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
281fn 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
292fn 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
304async 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
314fn 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 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 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 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 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 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 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 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 match fs::remove_dir_all(&self.build.temp_dir) {
431 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 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 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 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 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 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 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 fn source_code_spec_and_methods(&self, p: &Printer) -> Result<(Value, Value), String> {
553 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 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 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 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 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}