feat(selfHosted): add self-hosted worker runtime

README.md

@@ -227,4 +227,6 @@ service.shutdownExecutor();
 
 ## License
 
-Apache License 2.0.
+This project is licensed under the Apache License 2.0. See [LICENSE](./LICENSE).
+For third-party open-source software notices, see
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,41 @@
+# Third-Party Notices
+
+This repository contains code that is derived from or structurally adapted
+from third-party open-source projects.
+
+## Anthropic self-hosted worker SDK
+
+Portions of the self-hosted worker lifecycle and local agent tool
+implementations under
+`src/main/java/com/volcengine/ark/runtime/selfhosted`, including the work
+poller, environment worker, session tool runner, skill initializer, local
+tools, and tool-result store, are structurally adapted from Anthropic's
+self-hosted worker SDK implementations:
+
+- https://github.com/anthropics/anthropic-sdk-go
+- https://github.com/anthropics/anthropic-sdk-python
+
+The upstream projects are licensed under the MIT License. The MIT copyright
+and permission notice is preserved below as required by that license.
+
+```text
+Copyright 2023 Anthropic, PBC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

examples/README.md

@@ -28,6 +28,9 @@ pom on purpose — install the SDK first, then build the examples separately.
 | `EnvironmentsLifecycleExample` | Managed-Agents: Environment lifecycle — Create/Get/List/Update/Delete (cloud + unrestricted networking) |
 | `SessionsLoopExample` | Managed-Agents: end-to-end agent loop — Agent + Env + Session, send user.message, stream events until idle |
 | `MemoryStoresLifecycleExample` | Managed-Agents: MemoryStore + nested Memory CRUD |
+| `SelfHostedWorkerExample` | Managed-Agents: self-hosted worker poll / handle loop |
+
+`SelfHostedWorkerExample` uses the client's production default `https://ark.cn-beijing.volces.com/api/v3`.
 
 The Managed-Agents examples additionally accept `ARK_MODEL_ID` for the model id (falls back to a `${YOUR_MODEL_ID}` placeholder that will 400 at runtime).
 

examples/src/main/java/com/volcengine/ark/runtime/examples/SelfHostedWorkerExample.java

@@ -0,0 +1,63 @@
+// Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+// SPDX-License-Identifier: Apache-2.0
+
+// Retrofit 2.9 may report an illegal reflective access warning on JDK 9-16.
+// The warning is not a startup failure. To suppress it when running with Maven:
+//
+//   MAVEN_OPTS="--add-opens=java.base/java.lang.invoke=ALL-UNNAMED" \
+//     mvn -q -f examples/pom.xml exec:java \
+//     -Dexec.mainClass=com.volcengine.ark.runtime.examples.SelfHostedWorkerExample
+
+package com.volcengine.ark.runtime.examples;
+
+import com.volcengine.ark.runtime.selfhosted.EnvironmentWorker;
+import com.volcengine.ark.runtime.selfhosted.SelfHostedClient;
+
+public final class SelfHostedWorkerExample {
+    private SelfHostedWorkerExample() {
+    }
+
+    public static void main(String[] args) {
+        String environmentId = requiredEnv("MA_ENVIRONMENT_ID");
+        String workerId = System.getenv("MA_WORKER_ID");
+        String workdir = envOrDefault("MA_WORKDIR", ".");
+        SelfHostedClient.Builder clientBuilder = new SelfHostedClient.Builder()
+                .apiKey(requiredEnv("ARK_API_KEY"));
+        String baseUrl = System.getenv("ARK_BASE_URL");
+        if (baseUrl != null && !baseUrl.isEmpty()) {
+            clientBuilder.baseUrl(baseUrl);
+        }
+        System.out.printf(
+                "starting self-hosted worker base_url=%s environment_id=%s worker_id=%s workdir=%s%n",
+                baseUrl == null || baseUrl.isEmpty() ? SelfHostedClient.DEFAULT_BASE_URL : baseUrl,
+                environmentId,
+                workerId == null || workerId.isEmpty() ? "auto" : workerId,
+                workdir);
+        SelfHostedClient client = clientBuilder.build();
+        EnvironmentWorker worker = new EnvironmentWorker(
+                client,
+                new EnvironmentWorker.Options()
+                        .environmentId(environmentId)
+                        .workerId(workerId)
+                        .workdir(workdir));
+        Runtime.getRuntime().addShutdownHook(new Thread(worker::close, "ark-self-hosted-worker-shutdown"));
+        try {
+            worker.run();
+        } finally {
+            worker.close();
+        }
+    }
+
+    private static String requiredEnv(String name) {
+        String value = System.getenv(name);
+        if (value == null || value.isEmpty()) {
+            throw new IllegalArgumentException(name + " is required");
+        }
+        return value;
+    }
+
+    private static String envOrDefault(String name, String defaultValue) {
+        String value = System.getenv(name);
+        return value == null || value.isEmpty() ? defaultValue : value;
+    }
+}

examples/src/main/java/com/volcengine/ark/runtime/examples/SessionsLoopExample.java

@@ -13,15 +13,15 @@
 import com.volcengine.ark.runtime.models.environment.NetworkingConfig;
 import com.volcengine.ark.runtime.models.environment.NetworkingType;
 import com.volcengine.ark.runtime.models.session.AgentIdentifier;
+import com.volcengine.ark.runtime.models.session.ContentBlockType;
 import com.volcengine.ark.runtime.models.session.CreateSessionRequest;
-import com.volcengine.ark.runtime.models.session.IncomingEventParams;
-import com.volcengine.ark.runtime.models.session.IncomingEventParamsType;
+import com.volcengine.ark.runtime.models.session.ManagedAgentsEventParams;
+import com.volcengine.ark.runtime.models.session.ManagedAgentsEventParamsType;
+import com.volcengine.ark.runtime.models.session.ManagedAgentsMessageContentBlock;
+import com.volcengine.ark.runtime.models.session.ManagedAgentsTextBlock;
+import com.volcengine.ark.runtime.models.session.ManagedAgentsUserMessageEventParams;
 import com.volcengine.ark.runtime.models.session.SendSessionEventsRequest;
 import com.volcengine.ark.runtime.models.session.Session;
-import com.volcengine.ark.runtime.models.session.TurnInputContent;
-import com.volcengine.ark.runtime.models.session.TurnInputContentType;
-import com.volcengine.ark.runtime.models.session.TurnInputTextContent;
-import com.volcengine.ark.runtime.models.session.UserMessageEventParams;
 import com.volcengine.ark.runtime.service.ArkService;
 import java.io.BufferedReader;
 import java.io.InputStreamReader;
@@ -103,14 +103,14 @@ public static void main(String[] args) throws Exception {
             Thread sender = new Thread(() -> {
                 try {
                     Thread.sleep(500);
-                    TurnInputTextContent textBlock = new TurnInputTextContent();
-                    textBlock.setType(TurnInputContentType.TEXT);
+                    ManagedAgentsTextBlock textBlock = new ManagedAgentsTextBlock();
+                    textBlock.setType(ContentBlockType.TEXT);
                     textBlock.setText("What's the tallest mountain? One sentence.");
-                    UserMessageEventParams msg = new UserMessageEventParams();
-                    msg.setType(IncomingEventParamsType.USER_MESSAGE);
-                    msg.setContent(Arrays.<TurnInputContent>asList(textBlock));
+                    ManagedAgentsUserMessageEventParams msg = new ManagedAgentsUserMessageEventParams();
+                    msg.setType(ManagedAgentsEventParamsType.USER_MESSAGE);
+                    msg.setContent(Arrays.<ManagedAgentsMessageContentBlock>asList(textBlock));
                     SendSessionEventsRequest req = new SendSessionEventsRequest();
-                    req.setEvents(Arrays.<IncomingEventParams>asList(msg));
+                    req.setEvents(Arrays.<ManagedAgentsEventParams>asList(msg));
                     service.sendSessionEvents(sess.getId(), req);
                 } catch (InterruptedException e) {
                     Thread.currentThread().interrupt();

pom.xml

@@ -48,6 +48,7 @@
         <rxjava2.version>2.0.0</rxjava2.version>
         <okhttp3-version>4.12.0</okhttp3-version>
         <bouncycastle-version>1.84</bouncycastle-version>
+        <junit-version>4.13.2</junit-version>
     </properties>
 
     <dependencies>
@@ -117,12 +118,23 @@
         <dependency>
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>
-            <version>4.13.2</version>
+            <version>${junit-version}</version>
             <scope>test</scope>
         </dependency>
     </dependencies>
 
     <build>
+        <resources>
+            <resource>
+                <directory>${project.basedir}</directory>
+                <targetPath>META-INF</targetPath>
+                <filtering>false</filtering>
+                <includes>
+                    <include>LICENSE</include>
+                    <include>THIRD_PARTY_NOTICES.md</include>
+                </includes>
+            </resource>
+        </resources>
         <plugins>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>

src/main/java/com/volcengine/ark/runtime/models/agent/Agent.java

@@ -44,6 +44,7 @@
   Agent.JSON_PROPERTY_MULTIAGENT,
   Agent.JSON_PROPERTY_METADATA,
   Agent.JSON_PROPERTY_TAGS,
+  Agent.JSON_PROPERTY_DISPLAY_NAME,
   Agent.JSON_PROPERTY_CREATED_AT,
   Agent.JSON_PROPERTY_UPDATED_AT
 })
@@ -134,6 +135,10 @@ public static TypeEnum fromValue(String value) {
   @javax.annotation.Nullable
   private List<Tag> tags;
 
+  public static final String JSON_PROPERTY_DISPLAY_NAME = "display_name";
+  @javax.annotation.Nullable
+  private String displayName;
+
   public static final String JSON_PROPERTY_CREATED_AT = "created_at";
   @javax.annotation.Nonnull
   private String createdAt;
@@ -510,6 +515,31 @@ public void setTags(@javax.annotation.Nullable List<Tag> tags) {
     this.tags = tags;
   }
 
+  public Agent displayName(@javax.annotation.Nullable String displayName) {
+
+    this.displayName = displayName;
+    return this;
+  }
+
+  /**
+   * 展示名。
+   * @return displayName
+   */
+  @javax.annotation.Nullable
+  @JsonProperty(value = JSON_PROPERTY_DISPLAY_NAME, required = false)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+
+  public String getDisplayName() {
+    return displayName;
+  }
+
+
+  @JsonProperty(value = JSON_PROPERTY_DISPLAY_NAME, required = false)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public void setDisplayName(@javax.annotation.Nullable String displayName) {
+    this.displayName = displayName;
+  }
+
   public Agent createdAt(@javax.annotation.Nonnull String createdAt) {
 
     this.createdAt = createdAt;
@@ -583,13 +613,14 @@ public boolean equals(Object o) {
         Objects.equals(this.multiagent, agent.multiagent) &&
         Objects.equals(this.metadata, agent.metadata) &&
         Objects.equals(this.tags, agent.tags) &&
+        Objects.equals(this.displayName, agent.displayName) &&
         Objects.equals(this.createdAt, agent.createdAt) &&
         Objects.equals(this.updatedAt, agent.updatedAt);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(id, type, name, description, version, model, system, tools, mcpServers, skills, multiagent, metadata, tags, createdAt, updatedAt);
+    return Objects.hash(id, type, name, description, version, model, system, tools, mcpServers, skills, multiagent, metadata, tags, displayName, createdAt, updatedAt);
   }
 
   @Override
@@ -609,6 +640,7 @@ public String toString() {
     sb.append("    multiagent: ").append(toIndentedString(multiagent)).append("\n");
     sb.append("    metadata: ").append(toIndentedString(metadata)).append("\n");
     sb.append("    tags: ").append(toIndentedString(tags)).append("\n");
+    sb.append("    displayName: ").append(toIndentedString(displayName)).append("\n");
     sb.append("    createdAt: ").append(toIndentedString(createdAt)).append("\n");
     sb.append("    updatedAt: ").append(toIndentedString(updatedAt)).append("\n");
     sb.append("}");
@@ -687,6 +719,10 @@ public Agent.Builder tags(List<Tag> tags) {
       this.instance.tags = tags;
       return this;
     }
+    public Agent.Builder displayName(String displayName) {
+      this.instance.displayName = displayName;
+      return this;
+    }
     public Agent.Builder createdAt(String createdAt) {
       this.instance.createdAt = createdAt;
       return this;
@@ -742,6 +778,7 @@ public Agent.Builder toBuilder() {
       .multiagent(getMultiagent())
       .metadata(getMetadata())
       .tags(getTags())
+      .displayName(getDisplayName())
       .createdAt(getCreatedAt())
       .updatedAt(getUpdatedAt());
   }