Use Agent Sandbox workloads in Knative

Create a sandbox service

1. Apply the following configuration to your cluster to enable the sandbox workload type and session affinity.

   Replace registry-cn-wulanchabu-vpc in the image address with the endpoint for your region, such as registry-cn-hangzhou-vpc.

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: ai-agent-delete
   spec:
     template:
       metadata:
         annotations:
           # Enable the Sandbox workload type.
           serving.knative.dev/workload-type: "sandbox"
           # Enable session affinity to ensure requests from a user are routed to the same instance.
           serving.knative.dev/session-affinity: "true"
           # Release the instance after 30 minutes of inactivity.
           serving.knative.dev/session-timeout: "30m"
           # The cookie name used to identify the user session.
           serving.knative.dev/session-affinity-cookie: "app"
           # Scale based on the number of active sessions.
           autoscaling.knative.dev/metric: "session"
           # Strictly bind one session to each instance.
           autoscaling.knative.dev/target: "1"
       spec:
         containers:
         - image: registry-cn-wulanchabu-vpc.ack.aliyuncs.com/acs/knative-samples-helloworld-go-session:v1.0-bfdce98

2. Wait for the ai-agent-delete service to be deployed. On the Services page, get the Gateway address and the service's Default Domain.

3. Verify the result.

   1. The first request carries Cookie: app=11. Subsequent requests with the same cookie should be routed to the same Pod.

      curl -i -H "Host: ai-agent-delete.default.example.com" http://<GATEWAY_IP> \
        -H "Cookie: app=11"

      Expected output:

      HTTP/1.1 200 OK
      Date: Fri, 05 Jun 2026 08:00:53 GMT
      Content-Type: text/plain; charset=utf-8
      Content-Length: 75
      Connection: keep-alive
      
      Hello World!
      
      Cookies:
        Name:  app
        Value: 11
      
      Raw Cookie Header: app=11

   2. A subsequent request with Cookie: app=22 will access another Pod.

      curl -i -H "Host: ai-agent-delete.default.example.com" http://<GATEWAY_IP> \
        -H "Cookie: app=22"

      Expected output:

      HTTP/1.1 200 OK
      Date: Fri, 05 Jun 2026 08:02:49 GMT
      Content-Type: text/plain; charset=utf-8
      Content-Length: 75
      Connection: keep-alive
      
      Hello World!
      
      Cookies:
        Name:  app
        Value: 22
      
      Raw Cookie Header: app=22

Request routing logic

After the configuration is applied, user requests are processed as follows:

1. The first user request arrives. No instances are available, so Sandbox-1 is created and the session is bound to it.

2. The second user request arrives. Sandbox-1 is exclusively occupied by session-1 (target=1), so the request waits. APA automatically scales out Sandbox-2, and the session is bound to Sandbox-2.

3. If a user is inactive for 30 minutes, the session times out, the instance is deleted, and the resources are released.

4. No active users: Scales down to 0, consuming zero resources.

Create a sandbox service in Pause mode

1. Compared to Delete mode, you must add the serving.knative.dev/sandbox-idle-policy: "pause" annotation.

   Replace registry-cn-wulanchabu-vpc in the image address with the actual region, such as registry-cn-hangzhou-vpc.

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: ai-agent-pause
   spec:
     template:
       metadata:
         annotations:
           serving.knative.dev/workload-type: "sandbox"
           serving.knative.dev/sandbox-idle-policy: "pause"
           serving.knative.dev/session-affinity: "true"
           # Specify the size of the warm pool (number of pre-warmed Sandbox instances).
           serving.knative.dev/warm-pool: "3"
           serving.knative.dev/session-timeout: "30m"
           serving.knative.dev/session-expiry: "2h"
           serving.knative.dev/session-affinity-cookie: "test"
           autoscaling.knative.dev/metric: "session"
           autoscaling.knative.dev/target: "1"
       spec:
         containers:
         - image: registry-cn-wulanchabu-vpc.ack.aliyuncs.com/acs/knative-samples-helloworld-go-session:v1.0-bfdce98

2. Wait for the ai-agent-pause service to be deployed. On the Services page, get the Gateway address and the service's Default Domain.

3. Verify the result.

   curl -i -H "Host: ai-agent-pause.default.example.com" http://<GATEWAY_IP> \
     -H "Cookie: app=11"

   Expected output:

   HTTP/1.1 200 OK
   Date: Fri, 05 Jun 2026 08:33:06 GMT
   Content-Type: text/plain; charset=utf-8
   Content-Length: 75
   Connection: keep-alive
   
   Hello World!
   
   Cookies:
     Name:  app
     Value: 11
   
   Raw Cookie Header: app=11

Scope of state retention

When an instance is paused, the following state is fully retained, eliminating the need for re-initialization upon resume.

Configure warm pool

A warm pool is an advanced feature of Pause mode. It pre-creates and pauses a specified number of Sandbox instances. This allows a new user to immediately resume a pre-warmed instance, eliminating the wait for a cold start.

Use the following annotation to specify the size of the warm pool.

annotations:
  # Specify the size of the warm pool (number of pre-warmed Sandbox instances).
  serving.knative.dev/warm-pool: "3"

Choosing between Pause and Delete mode

The choice depends on whether you need to retain the runtime state:

• Use Pause mode if you need to preserve the container's state, such as its files and processes.

• Use Delete mode if you do not require state retention and want to achieve zero resource usage when idle.

Request routing for multiple users

This is not the case when target=1 is set. Each Sandbox instance is strictly bound to a single session. When a new user arrives, they wait for a new instance to become ready or for a frozen instance from the warm pool to be resumed.

Session persistence on Activator restart

It depends on the session storage mode:

• Memory mode: Limited session data can be recovered for a single instance.

• Redis mode: Session data is fully recovered from Redis, with zero data loss.

For production environments, use Redis mode to ensure complete session recovery if the Activator restarts.