AgentKit Studio
Guides

Run and Debug a Session

Issue instructions in a session, inspect tool calls, approve sensitive operations, rewind the conversation branch, and diagnose failed runs.

A session is a conversation and transcript owned by DSH; a run is one turn inside it. This page covers everything after the agent already works: how to see what it did, when it needs your approval, and how to back out of a failure.

Prerequisites

You finished Quickstart and at least one agent revision is saved. A cloud session additionally needs that agent deployed to the cloud with state READY; see Deploy to the Cloud.

Steps

Choose the agent bound to the session

Pick a target in the agent selector at the top of the conversation area. Every row carries its execution location:

LabelMeaning
LocalRuns inside your Host process and can read and write the local workspace
CloudRuns in a managed cloud instance and keeps running after you close the app

The agent locks once the session starts

After the first message the selector title becomes "Session started, agent locked". Start a new session to switch agents: the transcript does not migrate, and a cloud session refuses to continue because its frozen version differs.

Send an instruction

Type one sentence in the composer and press Enter. Stating the goal and the allowed action scope beats writing steps:

List every .mjs file in the current workspace, read-only, do not modify;
describe each file in one sentence.

Then watch three things in order:

  • Tool call cards: each call expands as in progress and turns into completed or failed once a result arrives.
  • Usage footer: input tokens, output tokens, and total duration for this turn.
  • File change cards: when the agent edited files, the right side lists a diff per file that you can accept or discard individually.

Approve operations that need a human

When the execution policy requires approval, a tool call stops on a pending approval card titled "<tool name> requests one-time authorization".

  1. Read the reason on the card.
  2. Choose Allow once — a risk confirmation appears; tick "I have reviewed this operation and its impact" and choose Confirm allow once.
  3. Or choose Reject — that call fails and the agent receives the rejection and continues.

The approval panel authorizes this one call only; it is not reused for later calls of the same tool. See Approvals and Permission Policy for the full policy.

Stop a running turn

You can stop at any time. After stopping:

  • Results of finished tool calls remain and can be inspected one by one.
  • Tool calls that had not returned are marked as interrupted.
  • The session keeps accepting the next message; no new session is required.

Stopping is not rewinding

Stopping only ends the current turn; file changes already written to the workspace are not reverted. To drop a conversation branch, use the next step.

Rewind the conversation branch

Open the Conversation rewind disclosure in the conversation area. It lists every rewindable user input in this session, each with two buttons:

ButtonScope
Rewind to before this inputConversation only: this input and everything after it leaves the current branch, workspace files stay
Preview rewinding files tooConversation and files: a file preview appears first, and you commit after reviewing it

After choosing "Preview rewinding files too", the preview lists one action per file:

restore: src/host/routes/agents.mjs
delete:  src/host/routes/agents.mjs.bak

Choose Confirm rewind conversation and files when it looks right. A file judged unsafe (outside the workspace, or changed externally in the meantime) never appears in the applicable list; it is reported on its own warning line with a reason.

Never reissue a rewind whose request is unconfirmed

If the panel shows "The rewind request is not confirmed yet", choose Retry the original rewind request: it replays with the same commandId and does not produce a second rewind. Issuing a new rewind can push the branch further back than intended.

Export the session log

Open the matching trace under Operations → Observability and choose Export session. The export needs a SessionId on that trace; otherwise it reports "This trace has no Session ID, so the session log cannot be exported".

The export is the complete event record of that run — useful in a ticket or when aligning with a colleague.

What success looks like

A healthy session satisfies all of these:

  • The final answer appears in full, not as an error summary.
  • Every tool call has a result; none is stuck "in progress".
  • Every call needing approval has an allow or deny decision, with no pending approval card left over.
  • The transcript survives a page refresh.
  • A cloud session shows a corresponding dsh.turn span under Observability → Trace detail.

Common errors

CodeCauseFix
DEPLOYMENT_SESSION_VERSION_CHANGEDThe cloud agent was upgraded or rolled back, so the session's frozen version no longer matches the current oneStart a new session; the old transcript stays readable
DEPLOYMENT_MODEL_FROZENThe selected model is not bound to this frozen versionPick a model already bound in the "Cloud deployment" group; changing models requires editing the agent, rebuilding, and updating the instance
DEPLOYMENT_MODEL_SWITCH_UNAVAILABLEThe current cloud image cannot switch bound modelsUpdate the instance image under Build and deploy
DEPLOYMENT_SESSION_REQUIREDA cloud conversation is missing its native session or message identityEnter through the "Start conversation" action instead of hand-crafting requests
DEPLOYMENT_ACCESS_REJECTEDThe cloud returned 401; the access token does not matchCheck access configuration and logs in Operations, then use "Repair access configuration" if needed
RUNTIME_RUN_FAILEDThe runtime failed to executeOpen the turn's error detail; rerun once under a read-only policy to localize it
native_conversation_rewind_requires_idleA rewind was attempted while tasks were still runningStop the current turn, then preview the rewind again
native_conversation_rewind_head_conflictThe rewind target is no longer the head of the branchRefresh, then pick the input to rewind to again
native_conversation_rewind_stop_unsettledTasks stopped but execution results are still being verifiedRetry the original rewind request once verification settles
checkpoint_control_compensatedAn unfinished file rewind was compensatedThe conversation was not rewound; preview again before operating
STUDIO_NATIVE_AGENT_POLICY_INVALIDThe agent's permission rules are malformedFix the JSON per Approvals and Permission Policy

On this page