feat(agentstudio): add managed agent deployment APIs (#253)

* feat(agentstudio): add deployment APIs

* fix(agentstudio): serialize empty deployment metadata

* fix(http): parse nested error envelopes

* feat: restrict deployment metadata to string values

---------

Co-authored-by: 一里 <liangshuang.ls@alibaba-inc.com>

Author: coolsky99

samples/AgentStudioDeployments.java

@@ -0,0 +1,52 @@
+import com.alibaba.dashscope.agentstudio.AgentStudioClient;
+import com.alibaba.dashscope.agentstudio.message.ClientEvents;
+import com.alibaba.dashscope.agentstudio.model.Deployment;
+import com.alibaba.dashscope.agentstudio.model.DeploymentRun;
+import com.alibaba.dashscope.agentstudio.param.DeploymentAgentParam;
+import com.alibaba.dashscope.agentstudio.param.DeploymentCreateParam;
+import com.alibaba.dashscope.agentstudio.param.DeploymentRunListParam;
+import com.alibaba.dashscope.agentstudio.param.DeploymentScheduleParam;
+import java.util.Collections;
+
+/**
+ * Managed Agent deployment example.
+ *
+ * <p>Set DASHSCOPE_API_KEY and DASHSCOPE_WORKSPACE before running.
+ */
+public class AgentStudioDeployments {
+
+  public static void main(String[] args) {
+    try (AgentStudioClient client = new AgentStudioClient()) {
+      Deployment deployment =
+          client
+              .deployments()
+              .create(
+                  DeploymentCreateParam.builder()
+                      .name("daily-summary")
+                      .description("Generate a daily summary")
+                      .agent(DeploymentAgentParam.builder().id("agent_xxx").build())
+                      .schedule(
+                          DeploymentScheduleParam.builder()
+                              .type(DeploymentScheduleParam.TYPE_CRON)
+                              .expression("0 9 * * 1-5")
+                              .timezone("Asia/Shanghai")
+                              .build())
+                      .initialEvents(
+                          Collections.singletonList(
+                              ClientEvents.userMessage("Summarize yesterday's orders")))
+                      .metadata(Collections.singletonMap("biz", "summary"))
+                      .build());
+      System.out.printf("deployment: %s %s%n", deployment.getId(), deployment.getStatus());
+
+      DeploymentRun run = client.deployments().run(deployment.getId());
+      System.out.printf("run: %s %s%n", run.getId(), run.getStatus());
+
+      for (DeploymentRun item :
+          client
+              .deployments()
+              .listRuns(deployment.getId(), DeploymentRunListParam.builder().limit(20).build())) {
+        System.out.printf("%s %s %s%n", item.getId(), item.getTriggerSource(), item.getStatus());
+      }
+    }
+  }
+}

src/main/java/com/alibaba/dashscope/agentstudio/AgentStudioClient.java

@@ -2,6 +2,8 @@
 package com.alibaba.dashscope.agentstudio;
 
 import com.alibaba.dashscope.agentstudio.resource.Agents;
+import com.alibaba.dashscope.agentstudio.resource.DeploymentRuns;
+import com.alibaba.dashscope.agentstudio.resource.Deployments;
 import com.alibaba.dashscope.agentstudio.resource.Environments;
 import com.alibaba.dashscope.agentstudio.resource.Files;
 import com.alibaba.dashscope.agentstudio.resource.Sessions;
@@ -14,6 +16,8 @@
 
 public class AgentStudioClient implements Closeable {
   private final Agents agents;
+  private final Deployments deployments;
+  private final DeploymentRuns deploymentRuns;
   private final Sessions sessions;
   private final Environments environments;
   private final Skills skills;
@@ -41,6 +45,8 @@ public AgentStudioClient(
       ConnectionOptions connectionOptions) {
     this.baseUrl = resolveBaseUrl(baseUrl, workspace, region);
     this.agents = new Agents(this.baseUrl, connectionOptions, apiKey);
+    this.deployments = new Deployments(this.baseUrl, connectionOptions, apiKey);
+    this.deploymentRuns = new DeploymentRuns(this.baseUrl, connectionOptions, apiKey);
     this.sessions = new Sessions(this.baseUrl, connectionOptions, apiKey);
     this.environments = new Environments(this.baseUrl, connectionOptions, apiKey);
     this.files = new Files(this.baseUrl, connectionOptions, apiKey);
@@ -93,6 +99,14 @@ public Agents agents() {
     return agents;
   }
 
+  public Deployments deployments() {
+    return deployments;
+  }
+
+  public DeploymentRuns deploymentRuns() {
+    return deploymentRuns;
+  }
+
   public Sessions sessions() {
     return sessions;
   }

src/main/java/com/alibaba/dashscope/agentstudio/model/Deployment.java

@@ -0,0 +1,62 @@
+// Copyright (c) Alibaba, Inc. and its affiliates.
+package com.alibaba.dashscope.agentstudio.model;
+
+import com.alibaba.dashscope.agentstudio.message.Message;
+import com.alibaba.dashscope.common.FlattenResultBase;
+import com.google.gson.annotations.SerializedName;
+import java.util.List;
+import java.util.Map;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class Deployment extends FlattenResultBase {
+  @SerializedName("id")
+  private String id;
+
+  @SerializedName("type")
+  private String type;
+
+  @SerializedName("name")
+  private String name;
+
+  @SerializedName("description")
+  private String description;
+
+  @SerializedName("agent")
+  private Agent agent;
+
+  @SerializedName("environment_id")
+  private String environmentId;
+
+  @SerializedName("schedule")
+  private DeploymentSchedule schedule;
+
+  @SerializedName("initial_events")
+  private List<Message> initialEvents;
+
+  @SerializedName("resources")
+  private List<DeploymentResource> resources;
+
+  @SerializedName("vault_ids")
+  private List<String> vaultIds;
+
+  @SerializedName("metadata")
+  private Map<String, String> metadata;
+
+  @SerializedName("status")
+  private String status;
+
+  @SerializedName("paused_reason")
+  private DeploymentPausedReason pausedReason;
+
+  @SerializedName("archived_at")
+  private String archivedAt;
+
+  @SerializedName("created_at")
+  private String createdAt;
+
+  @SerializedName("updated_at")
+  private String updatedAt;
+}

src/main/java/com/alibaba/dashscope/agentstudio/model/DeploymentAgentReference.java

@@ -0,0 +1,14 @@
+// Copyright (c) Alibaba, Inc. and its affiliates.
+package com.alibaba.dashscope.agentstudio.model;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+
+@Data
+public class DeploymentAgentReference {
+  @SerializedName("id")
+  private String id;
+
+  @SerializedName("version")
+  private Integer version;
+}

src/main/java/com/alibaba/dashscope/agentstudio/model/DeploymentError.java

@@ -0,0 +1,14 @@
+// Copyright (c) Alibaba, Inc. and its affiliates.
+package com.alibaba.dashscope.agentstudio.model;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+
+@Data
+public class DeploymentError {
+  @SerializedName("code")
+  private String code;
+
+  @SerializedName("message")
+  private String message;
+}

src/main/java/com/alibaba/dashscope/agentstudio/model/DeploymentPausedReason.java

@@ -0,0 +1,14 @@
+// Copyright (c) Alibaba, Inc. and its affiliates.
+package com.alibaba.dashscope.agentstudio.model;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+
+@Data
+public class DeploymentPausedReason {
+  @SerializedName("type")
+  private String type;
+
+  @SerializedName("error")
+  private DeploymentError error;
+}

src/main/java/com/alibaba/dashscope/agentstudio/model/DeploymentResource.java

@@ -0,0 +1,17 @@
+// Copyright (c) Alibaba, Inc. and its affiliates.
+package com.alibaba.dashscope.agentstudio.model;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+
+@Data
+public class DeploymentResource {
+  @SerializedName("type")
+  private String type;
+
+  @SerializedName("file_id")
+  private String fileId;
+
+  @SerializedName("mount_path")
+  private String mountPath;
+}

src/main/java/com/alibaba/dashscope/agentstudio/model/DeploymentRun.java

@@ -0,0 +1,41 @@
+// Copyright (c) Alibaba, Inc. and its affiliates.
+package com.alibaba.dashscope.agentstudio.model;
+
+import com.alibaba.dashscope.common.FlattenResultBase;
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class DeploymentRun extends FlattenResultBase {
+  @SerializedName("id")
+  private String id;
+
+  @SerializedName("type")
+  private String type;
+
+  @SerializedName("deployment_id")
+  private String deploymentId;
+
+  @SerializedName("agent")
+  private DeploymentAgentReference agent;
+
+  @SerializedName("session_id")
+  private String sessionId;
+
+  @SerializedName("trigger_source")
+  private String triggerSource;
+
+  @SerializedName("status")
+  private String status;
+
+  @SerializedName("error")
+  private DeploymentError error;
+
+  @SerializedName("started_at")
+  private String startedAt;
+
+  @SerializedName("finished_at")
+  private String finishedAt;
+}

src/main/java/com/alibaba/dashscope/agentstudio/model/DeploymentSchedule.java

@@ -0,0 +1,23 @@
+// Copyright (c) Alibaba, Inc. and its affiliates.
+package com.alibaba.dashscope.agentstudio.model;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+
+@Data
+public class DeploymentSchedule {
+  @SerializedName("type")
+  private String type;
+
+  @SerializedName("expression")
+  private String expression;
+
+  @SerializedName("timezone")
+  private String timezone;
+
+  @SerializedName("last_run_at")
+  private String lastRunAt;
+
+  @SerializedName("next_run_at")
+  private String nextRunAt;
+}

src/main/java/com/alibaba/dashscope/agentstudio/param/DeploymentAgentParam.java

@@ -0,0 +1,18 @@
+// Copyright (c) Alibaba, Inc. and its affiliates.
+package com.alibaba.dashscope.agentstudio.param;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NonNull;
+
+@Data
+@Builder
+public class DeploymentAgentParam {
+  @NonNull
+  @SerializedName("id")
+  private String id;
+
+  @SerializedName("version")
+  private Integer version;
+}