Runtime Sessions And Files

The local KsADK runtime provides more than request forwarding. It also manages session IDs, run events, feedback records, uploads, and workspace file previews for the local Web UI.

Runtime Surfaces

Public clients should prefer the OpenAI-compatible API unless they are integrating directly with the KsADK local UI.

Request Lifecycle

For local Responses calls, the runtime follows a stable sequence:

1. normalize the input into messages, content blocks, and attachments.
2. create or load the session.
3. append the user message and run_status=in_progress.
4. build PlatformInvocationContext.
5. call the framework runner.
6. append assistant, tool, reasoning, approval, or error events.
7. append a terminal run_status.

The same conversation runtime is shared by /v1/responses, /v1/chat/completions, and the local Web UI run action. Protocol endpoints mainly decide input and output shape; they do not define separate business execution models.

Sessions

Responses calls can use conversation:

{
  "model": "my-agent",
  "conversation": {"id": "local-session-1"},
  "input": "Continue this conversation",
  "stream": false
}

Older local clients may use session_id:

{
  "model": "my-agent",
  "session_id": "local-session-1",
  "input": "Continue this conversation",
  "stream": false
}

Use one style consistently. If both are present and disagree, the local runtime rejects the request.

When PostgreSQL is configured, it is a durable session replica rather than an availability prerequisite for agent execution. If a connection or write fails, the runtime continues with its in-process live session and emits a structured error when it enters session_backend_state=degraded. The runtime periodically probes PostgreSQL; after recovery, new sessions and subsequent events are written to PostgreSQL again and session_backend_state=recovered is logged. Older events missed during the outage are not backfilled automatically and are not guaranteed to survive a pod restart or relocation. While PostgreSQL is unavailable, only history already loaded by the current process is available. A request routed to another pod may have reduced context, but the current agent request still runs.

Readable PostgreSQL View

KsADK creates ksadk_session_events_readable alongside the raw PostgreSQL tables. The raw content_json and metadata_json values remain available, while the view exposes flattened message_role, message_text, tool_name, lifecycle_status, and created_at columns for operators:

SELECT
  session_id,
  seq_id,
  message_role,
  event_type,
  message_text,
  tool_name,
  lifecycle_status,
  created_at
FROM ksadk_session_events_readable
WHERE namespace = 'default' AND session_id = '<session-id>'
ORDER BY seq_id;

Reasoning deltas are still streamed to clients in real time, but they are persisted as one aggregated reasoning event per turn. Lifecycle events remain separate and can be inspected through lifecycle_status.

Account Boundary

Hosted deployments pass account_id through the request chain. It is injected by the gateway, not manufactured by the business agent. Sessions, attachments, and workspace files are isolated per account_id; the local runtime isolates per owner and never shares session, attachment, or workspace state across account_id boundaries.

Web UI Sessions

agentengine web sets local UI state under the project directory unless another session backend is configured:

.agentengine/ui/sessions.sqlite

That file is local runtime state, not source. Delete it to reset local browser sessions.

Run Events

The session store records run facts as events. Typical event types include:

Clients should treat terminal run_status events as the end of a turn. Text output alone does not prove the run is complete.

Session And Event Pagination

ListSessions

Request fields:

Response Data fields:

curl -sS -X POST https://<public-endpoint>/agentengine/api/v1/ListSessions \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"AgentId":"my-agent","UserId":"user","Page":1,"PageSize":20}'

ListSessionEvents

Request fields:

Response Data fields:

curl -sS -X POST https://<public-endpoint>/agentengine/api/v1/ListSessionEvents \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"SessionId":"<sid>","Offset":0,"Limit":50}'

Public API clients should still prefer the OpenAI-compatible /v1/* routes unless they integrate the hosted UI list surface directly.

Event Projection

The runtime does not send every stored event back to the model verbatim. It uses the event log as the source of truth, then projects a model-facing history from transcript events:

This split is deliberate. The event log remains auditable and replayable, while the runner sees a compact model history that excludes control events such as run_status.

Context Compaction

Long conversations can be compacted without overwriting the event log. The runtime appends a compaction boundary and a context checkpoint that records the summary and the event sequence range it covers. Later history projection keeps the checkpoint summary and the uncompressed tail events.

This means deleting local UI state is the right way to reset a development session, but compaction itself should not be treated as data deletion.

Session Backends

The session backend is configurable. The public local defaults are designed for development, while shared hosted deployments should use an explicitly reviewed shared backend.

Useful environment variables:

Do not commit local session databases. They can contain prompts, extracted attachment text, local paths, tool events, and user feedback.

File And Image Inputs

The Web UI can upload files and images into the local runtime. Public protocol examples should prefer Responses-style item names:

{
  "type": "input_image",
  "image_url": "data:image/png;base64,..."
}

{
  "type": "input_file",
  "filename": "notes.txt",
  "file_data": "data:text/plain;base64,..."
}

Framework adapters receive normalized runner input. Applications should still validate file type, size, and trust boundaries before processing content.

Workspace Files

The local UI can expose workspace file operations for preview and debugging. Treat workspace content as local developer data:

• do not include customer data in public docs.
• do not publish uploaded files from local runs.
• avoid screenshots that reveal private paths, tokens, or code.
• keep generated archives out of Git unless explicitly reviewed.

Streaming, Disconnects, And Reconnects

The local Web UI run action has a reconnect-oriented design. In Responses stream mode, the server can continue consuming the runner stream after the browser disconnects, then persist the final run events to the session store. A client that reconnects should use the session id, invocation id, and last consumed sequence id to subscribe to later run events.

Public API clients using /v1/responses should still implement normal SSE error handling and retry behavior. The Web UI reconnect path is a KsADK local UI capability, not a promise that every HTTP client can resume an original TCP connection.

Checkpoint, Resume, Cancel

The runtime exposes five hosted UI actions for run-level checkpoint, resume, cancel, and tool receipts. Every action is POST /agentengine/api/v1/<Action> with a JSON body, and the response is a uniform { Code, Message, RequestId, Action, Data } envelope.

Checkpoint State Machine

Each checkpoint returned by ListSessionCheckpoints or GetCheckpointResumePreview carries a CheckpointStatus, derived at read time from is_terminal, is_resumable, resume_count, expires_at, and replay_allowed. The runtime does not persist this field; it is computed on read:

Checkpoint Descriptor Fields

Each checkpoint is a projection of a run_checkpoint event. Beyond the common event fields, it carries the following resume descriptor fields (all added/aligned in 0.6.7):

ListSessionCheckpoints

List checkpoints under a session, optionally filtered by RunId or Framework, with pagination.

curl -sS -X POST "https://<public-endpoint>/agentengine/api/v1/ListSessionCheckpoints" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "AgentId": "my-agent",
    "SessionId": "<sid>",
    "OnlyResumable": true,
    "Limit": 50
  }'

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "req-abc123",
  "Action": "ListSessionCheckpoints",
  "Data": {
    "Checkpoints": [
      {
        "EventId": "evt_001",
        "SessionId": "<sid>",
        "InvocationId": "inv_xyz",
        "RunId": "run_001",
        "CheckpointId": "ckpt_002",
        "Framework": "langgraph",
        "IsResumable": true,
        "ResumeStatus": "resumable",
        "IsTerminal": false,
        "ResumeDisabledReason": "",
        "NextNode": "research_summarize",
        "Backend": "langgraph_store",
        "Scope": "session",
        "Durable": true,
        "LastResumedAt": null,
        "ResumeCount": 0,
        "ReplayAllowed": true,
        "ExpiresAt": "2026-07-04T12:00:00Z",
        "CheckpointStatus": "active"
      }
    ],
    "Total": 1,
    "Offset": 0,
    "Limit": 50
  }
}

GetCheckpointResumePreview

Preview the impact of resuming from a checkpoint: tool receipts, side-effect risk level, and whether a preview is required before resume.

curl -sS -X POST "https://<public-endpoint>/agentengine/api/v1/GetCheckpointResumePreview" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "AgentId": "my-agent",
    "SessionId": "<sid>",
    "RunId": "run_001",
    "CheckpointId": "ckpt_002"
  }'

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "req_def456",
  "Action": "GetCheckpointResumePreview",
  "Data": {
    "Preview": {
      "Checkpoint": { "CheckpointId": "ckpt_002", "IsResumable": true },
      "Capabilities": {
        "Checkpoints": true,
        "CheckpointResume": true,
        "ToolReceipts": true,
        "IdempotentToolReplay": true
      },
      "CanResume": true,
      "Reason": "",
      "NextNode": "research_summarize",
      "ExpectedAction": "resume_from_checkpoint",
      "ToolReceipts": [
        {
          "ReceiptId": "rcpt_001",
          "ToolName": "write_workspace_file",
          "ToolCallId": "call_01",
          "RunId": "run_001",
          "CheckpointId": "ckpt_001",
          "Status": "succeeded",
          "Replayed": false
        }
      ],
      "Risk": {
        "Level": "medium",
        "DuplicateSideEffectRisk": true,
        "SideEffectReceiptCount": 1,
        "FailedReceiptCount": 0
      },
      "Summary": {
        "RunId": "run_001",
        "CheckpointId": "ckpt_002",
        "Phase": "after_research",
        "ToolReceiptCount": 1
      }
    }
  }
}

ResumeRun

Resume run execution from a checkpoint. In 0.6.7 the ResumeInstructionEnabled / ResumeInstruction fields were added so an extra instruction can be injected on resume, and 409 error codes distinguish non-resumable checkpoints from duplicate resumes.

curl -sS -X POST "https://<public-endpoint>/agentengine/api/v1/ResumeRun" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "AgentId": "my-agent",
    "SessionId": "<sid>",
    "RunId": "run_001",
    "CheckpointId": "ckpt_002",
    "ResumeInstructionEnabled": true,
    "ResumeInstruction": "redo the summary in a more concise tone",
    "Stream": false
  }'

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "req_ghi789",
  "Action": "ResumeRun",
  "Data": {
    "id": "resp_<hex>",
    "object": "response",
    "model": "my-agent",
    "output": [
      { "type": "message", "role": "assistant", "content": [{ "type": "output_text", "text": "..." }] }
    ]
  }
}

{
  "Code": 0,
  "Action": "ResumeRun",
  "Data": {
    "status": "noop",
    "Reason": "该 checkpoint 已是终态;可选择更早恢复点重跑",
    "CheckpointId": "ckpt_002",
    "RunId": "run_001",
    "ResumeAttemptId": "resume_<hex>"
  }
}

curl -sS -N -X POST "https://<public-endpoint>/agentengine/api/v1/ResumeRun" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "AgentId": "my-agent",
    "SessionId": "<sid>",
    "RunId": "run_001",
    "CheckpointId": "ckpt_002",
    "Stream": true
  }'

{
  "detail": {
    "code": "checkpoint_not_resumable",
    "reason": "该 checkpoint 已恢复过,当前策略不允许重复恢复",
    "checkpoint_id": "ckpt_002",
    "run_id": "run_001",
    "resume_status": "disabled",
    "is_terminal": false
  }
}

{
  "detail": {
    "code": "resume_already_running",
    "message": "A checkpoint resume is already running for this session and run.",
    "InvocationId": "inv_existing",
    "SessionId": "<sid>",
    "RunId": "run_001"
  }
}

CancelRun

Cancel an in-progress run. As of 0.6.7, InvocationId is the primary key and AgentId is optional (it is only used as runner cancel context and no longer performs session ownership validation).

curl -sS -X POST "https://<public-endpoint>/agentengine/api/v1/CancelRun" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "InvocationId": "inv_xyz"
  }'

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "req_jkl012",
  "Action": "CancelRun",
  "Data": {
    "Cancelled": true,
    "Found": true,
    "Status": "cancelling",
    "RunnerCancelStatus": "accepted"
  }
}

ListToolReceipts

List tool-call receipts under a run / checkpoint, useful for assessing side-effects before resume or for after-the-fact auditing.

curl -sS -X POST "https://<public-endpoint>/agentengine/api/v1/ListToolReceipts" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "AgentId": "my-agent",
    "SessionId": "<sid>",
    "RunId": "run_001"
  }'

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "req_mno345",
  "Action": "ListToolReceipts",
  "Data": {
    "ToolReceipts": [
      {
        "EventId": "evt_010",
        "SessionId": "<sid>",
        "InvocationId": "inv_xyz",
        "SeqId": 10,
        "Timestamp": "2026-07-03T10:00:00Z",
        "ReceiptId": "rcpt_001",
        "IdempotencyKey": "idem_abc",
        "ToolName": "write_workspace_file",
        "ToolCallId": "call_01",
        "RunId": "run_001",
        "CheckpointId": "ckpt_001",
        "Status": "succeeded",
        "Replayed": false,
        "Metadata": { "tool_name": "write_workspace_file" }
      }
    ]
  }
}

ResumeMode

GetAgentUiBootstrap returns RuntimeCapabilities.ResumeRun.ResumeMode, which describes the framework-level resume capability:

RunLifecycle Gating

The frontend resume entry point must not look at ResumeMode alone. It must also check the two RunLifecycle flags returned by bootstrap:

• RunLifecycle.Checkpoints = true: the session has usable checkpoints.
• RunLifecycle.CheckpointResume = true: the runtime supports resuming from a checkpoint.

If either is false, treat resume as unsupported and do not surface the ResumeRun entry point. RunLifecycle.CheckpointResumePreview indicates whether GetCheckpointResumePreview is available.

SubscribeRunEvents

The local UI reconnect flow is based on persisted events, not on resuming the same HTTP stream:

curl -sS -N "https://<public-endpoint>/agentengine/api/v1/SubscribeRunEvents?SessionId=<sid>&InvocationId=<iid>&AfterSeqId=42" \
  -H "Authorization: Bearer <api_key>" \
  -H "Accept: text/event-stream"

Once a terminal run_status (completed, failed, cancelled, interrupted) appears, the server sends data: [DONE] and ends the stream; otherwise the client must re-subscribe with the latest seq_id after the 5-minute timeout.

Upload References

When the local UI uploads a file, the server returns a ksadk-upload://... reference. That reference is accepted only by the local runtime that created it. Do not store those URIs in source files or public examples as durable external URLs.

Upload URI Scheme

Both schemes are read through the same route:

curl -sS "https://<public-endpoint>/agentengine/api/v1/AttachmentContent?FileUri=ae-upload://<file_id>" \
  -H "Authorization: Bearer <api_key>"

When resolving an ae-upload:// URI, the server locates the hosted upload content by the {file_id} and returns its byte stream, while also writing the content back to a local cache (local_path) so that subsequent reads hit the cache. Paths without the ae-upload:// prefix are treated as workspace-relative paths.

AttachmentContent returns an attachment represented internally as AttachmentBytes:

Feedback

The local runtime includes feedback endpoints for UI interactions. Feedback records are useful for debugging and evaluation flows, but public examples should use fake response IDs and comments.

Cancellation And Reconnects

Streaming runs may continue after a browser refresh or SSE disconnect. Clients that implement streaming should support:

• cancellation.
• reconnecting to known invocation/session state.
• displaying partial output safely.
• handling final error events.

Security Boundary

The local runtime is for development. Do not expose it directly to the public internet without authentication, request limits, file validation, and review of the hosted runtime boundary.