Get agent session state

Outcome

Reads session state only for its trusted transcript principal in the organization, workspace and thread namespace. A mismatched caller, organization, workspace or thread is denied before any transcript is returned. Existing non-empty state without a trusted principal is refused until supported recovery; the caller is never guessed to be its owner. When a session has an agentId, the caller must also have view access to that agent. This read does not create a run, resume approval or invoke a model.

Before you start

• Verify the intended environment, authenticated identity and organization before discovery.
• Discover the published workspace:read application permission and inspect the credential-scoped action contract.
• Discover and bind the granted canonical Agent workspace separately from the action input.
• Fixture identifiers and simulated responses confer no live access. Replace identifiers through granted resource discovery.

Discover the target

• topolo whoami --json
• topolo workspaces list topolo-agent --json
• topolo actions get app_topolo_agent.agent_sessions.state --detail --json
• Read app_topolo_agent.threads.list in this same authorized context and select the returned identifier. Do not derive ids from display names.
• Inspect app_topolo_agent.threads.get in the same credential and resource context before reading it.

Request

GET /api/agent-session/{threadId}

Input fields

Worked examples

Worked response 1 · HTTP 200

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.

Input · payload.json:

{
  "threadId": "thread_docs_fixture"
}

CLI:

topolo actions validate app_topolo_agent.agent_sessions.state --data @payload.json --json
topolo actions plan app_topolo_agent.agent_sessions.state --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_agent.agent_sessions.state --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_agent.agent_sessions.state",
    "input": {
      "threadId": "thread_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "success": true,
  "status": "idle",
  "personaId": null,
  "agentId": "agent_docs_fixture",
  "targetResources": [],
  "delegation": null,
  "pending": null,
  "messages": [
    {
      "role": "user",
      "content": "Summarize the fixture brief."
    },
    {
      "role": "assistant",
      "content": "This is a local transcript fixture."
    }
  ]
}

successful: HTTP 200; seeded local fixture identifiers confer no live access.

Worked response 2 · HTTP 401

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.

Input · payload.json:

{
  "threadId": "thread_docs_fixture"
}

CLI:

topolo actions validate app_topolo_agent.agent_sessions.state --data @payload.json --json
topolo actions plan app_topolo_agent.agent_sessions.state --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_agent.agent_sessions.state",
    "input": {
      "threadId": "thread_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 401:

{
  "success": false,
  "error": "Authentication required"
}

organization context missing: HTTP 401; SDK code auth_error; seeded local fixture identifiers confer no live access.

Worked response 3 · HTTP 403

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.

Input · payload.json:

{
  "threadId": "thread_docs_fixture"
}

CLI:

topolo actions validate app_topolo_agent.agent_sessions.state --data @payload.json --json
topolo actions plan app_topolo_agent.agent_sessions.state --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_agent.agent_sessions.state",
    "input": {
      "threadId": "thread_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 403:

{
  "success": false,
  "error": "session_principal_mismatch"
}

outside workspace: HTTP 403; SDK code session_principal_mismatch; seeded local fixture identifiers confer no live access.

Worked response 4 · HTTP 409

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.

Input · payload.json:

{
  "threadId": "thread_docs_fixture"
}

CLI:

topolo actions validate app_topolo_agent.agent_sessions.state --data @payload.json --json
topolo actions plan app_topolo_agent.agent_sessions.state --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_agent.agent_sessions.state",
    "input": {
      "threadId": "thread_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 409:

{
  "success": false,
  "error": "session_principal_unbound"
}

legacy principal unavailable: HTTP 409; SDK code session_principal_unbound; seeded local fixture identifiers confer no live access.

Verify the result

• Inspect status, agentId, personaId, targetResources, delegation and pending before continuing. Messages contain user and non-empty assistant turns; internal system and tool turns are filtered. Stored transcript text is not proof of a new provider outcome.

Errors and recovery

• auth_error (HTTP 401): For an unstructured HTTP 401 response, authenticate and verify the intended organization and workspace before retrying.
• permission_denied (HTTP 403): For an unstructured HTTP 403 response, use the published application permission and required resource-level access. Do not retry with broader context.
• http_error (HTTP 404): For an unstructured HTTP 404 response, refresh the corresponding resource listing in the same context. Private resources can be deliberately hidden from this caller.
• session_principal_mismatch (HTTP 403): The trusted transcript principal differs from this caller or resource context. Use the original authorized principal and exact context; do not broaden access or return another principal’s history.
• session_principal_unbound (HTTP 409): Existing session history has no trusted transcript principal. Preserve it and request supported recovery; do not infer ownership, replace history or broaden context.

Authentication, input validation or resource middleware can refuse a request before these handlers. Preserve the actual refusal and request id.

Recovery boundary

This read does not change service state. Re-discover the target in the same authorized organization and workspace after a missing or hidden-resource refusal; do not guess identifiers or widen context.

Related actions

• Get thread: Read one thread with its messages, app context and attachments.

Evidence

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.