Agents

SDK reference for agents — Create and manage agent chat sessions, and list the agents in a deployment.

Create and manage agent chat sessions, and list the agents in a deployment.

createSession

Create a platform agent chat session

POST

Usage:

const result = await swirls.client.agents.createSession({
  agentName: '...',
  projectId: '...',
})

Input:

Parameter	Type	Required
`agentName`	`string`	Yes
`projectId`	`string`	Yes
`title`	`string \| null`	No
`metadata`	`object`	No

Output:

Field	Type	Description
`sessionId`	`string`

listSessions

List agent chat sessions for a project

GET

Usage:

const result = await swirls.client.agents.listSessions({
  projectId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`agentName`	`string`	No
`limit`	`number`	No

Output:

Field	Type	Description
`sessions`	`object[]`

getSession

Load an agent chat session by id

GET

Usage:

const result = await swirls.client.agents.getSession({
  sessionId: '...',
})

Input:

Parameter	Type	Required	Description
`sessionId`	`string`	Yes

sendSessionMessage

Send a user message to an existing agent session and start a turn

POST

Usage:

const result = await swirls.client.agents.sendSessionMessage({
  sessionId: '...',
  message: '...',
})

Input:

Parameter	Type	Required	Description
`sessionId`	`string`	Yes
`message`	`string`	Yes

Output:

Field	Type	Description
`runId`	`string`

mintActorSessionGrant

Mint a short-lived WebSocket grant for an agent session turn

POST

Usage:

const result = await swirls.client.agents.mintActorSessionGrant({
  sessionId: '...',
  runId: '...',
})

Input:

Parameter	Type	Required	Description
`sessionId`	`string`	Yes
`runId`	`string`	Yes

Output:

Field	Type	Description
`actor`	`"directory" \| "project" \| "session" \| "execution"`
`grant`	`string`
`websocketUrl`	`string`
`expiresAt`	`string`
`appId`	`string`
`projectId`	`string`
`sessionId`	`string`
`threadId`	`string`
`runId`	`string`
`executionId`	`string`

deleteSession

Delete an agent chat session by id

POST

Usage:

const result = await swirls.client.agents.deleteSession({
  sessionId: '...',
})

Input:

Parameter	Type	Required	Description
`sessionId`	`string`	Yes

Output:

Field	Type	Description
`deleted`	`boolean`

createWebSession

Create a web chat session (channel-keyed: bindingName is the channel name)

POST

Usage:

const result = await swirls.client.agents.createWebSession({
  projectId: '...',
  bindingName: '...',
  agentName: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`bindingName`	`string`	Yes
`agentName`	`string`	Yes
`title`	`string \| null`	No

Output:

Field	Type	Description
`sessionId`	`string`

createAgentChatSession

Create an in-app agent chat session (binding stored as agentName)

POST

Usage:

const result = await swirls.client.agents.createAgentChatSession({
  projectId: '...',
  agentName: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`agentName`	`string`	Yes
`title`	`string \| null`	No

Output:

Field	Type	Description
`sessionId`	`string`

listWebSessions

List web channel chat sessions for the current user (bindingName is the channel name)

GET

Usage:

const result = await swirls.client.agents.listWebSessions({
  projectId: '...',
  bindingName: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`bindingName`	`string`	Yes
`limit`	`number`	No

Output:

Field	Type	Description
`sessions`	`object[]`

listAgentChatSessions

List in-app agent chat sessions for the current user (binding stored as agentName)

GET

Usage:

const result = await swirls.client.agents.listAgentChatSessions({
  projectId: '...',
  agentName: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`agentName`	`string`	Yes
`limit`	`number`	No

Output:

Field	Type	Description
`sessions`	`object[]`

getWebChatMessages

Load persisted web chat UI messages from execution event replay

GET

Usage:

const result = await swirls.client.agents.getWebChatMessages({
  sessionId: '...',
})

Input:

Parameter	Type	Required	Description
`sessionId`	`string`	Yes

Output:

Field	Type	Description
`messages`	`object[]`

getSessionContextStatus

Context utilization for an agent session: budget used, tokens by segment, the last compaction, and whether the next turn would compact

GET

Usage:

const result = await swirls.client.agents.getSessionContextStatus({
  sessionId: '...',
})

Input:

Parameter	Type	Required	Description
`sessionId`	`string`	Yes

Output:

Field	Type	Description
`sessionId`	`string`
`tokensEstimate`	`number`
`budget`	`object`
`usedFraction`	`number`
`remainingTokens`	`number`
`shouldCompact`	`boolean`
`pruningApplied`	`boolean`
`segments`	`object`
`messageCount`	`number`
`compacted`	`boolean`
`anchor`	`object`
`lastCompaction`	`object \| null`
`cacheHitRate`	`number \| null`

compactSessionContext

Compact an agent session now, optionally steering the summary with a focus instruction

POST

Usage:

const result = await swirls.client.agents.compactSessionContext({
  sessionId: '...',
})

Input:

Parameter	Type	Required	Description
`sessionId`	`string`	Yes
`focus`	`string`	No

listAgents

List agents in the active deployment for a project

GET

Usage:

const result = await swirls.client.agents.listAgents({
  projectId: '...',
})

Input:

Parameter	Type	Required	Description
`projectId`	`string`	Yes

Output:

Field	Type	Description
`agents`	`object[]`

getAgentWalletStatus

Per-agent tool wallet status for the current cadence window

GET

Usage:

const result = await swirls.client.agents.getAgentWalletStatus({
  projectId: '...',
  agentName: '...',
})

Input:

Parameter	Type	Required	Description
`projectId`	`string`	Yes
`agentName`	`string`	Yes

Output:

Field	Type	Description
`configured`	`boolean`
`wallet`	`object \| null`
`windowKey`	`string \| null`
`budgetCents`	`number \| null`
`spentCents`	`number \| null`
`reservedCents`	`number \| null`
`remainingCents`	`number \| null`

getWorkspaceDisk

Resolve the platform-managed dedicated Archil workspace disk for a deployed agent

GET

Usage:

const result = await swirls.client.agents.getWorkspaceDisk({
  projectId: '...',
  deploymentId: '...',
  agentId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`deploymentId`	`string`	Yes
`agentId`	`string`	Yes

Output:

Field	Type	Description
`agentId`	`string`
`agentName`	`string`
`mountPath`	`string`
`externalDiskId`	`string`

listWorkspaceDirectory

List files and directories on an agent workspace disk

GET

Usage:

const result = await swirls.client.agents.listWorkspaceDirectory({
  projectId: '...',
  deploymentId: '...',
  agentId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`deploymentId`	`string`	Yes
`agentId`	`string`	Yes
`path`	`string`	No

Output:

Field	Type	Description
`path`	`string`
`entries`	`object[]`

readWorkspaceFile

Read a single file from an agent workspace disk (size-capped)

GET

Usage:

const result = await swirls.client.agents.readWorkspaceFile({
  projectId: '...',
  deploymentId: '...',
  agentId: '...',
  path: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`deploymentId`	`string`	Yes
`agentId`	`string`	Yes
`path`	`string`	Yes

Output:

Field	Type	Description
`path`	`string`
`size`	`number`
`content`	`string`
`truncated`	`boolean`

On this page