> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revoengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# agent reference

> Durable Agent, inbox, run, plugin, and Assistant-thread methods.

<Note>
  Generated from the same public contract that feeds the Monaco editor. Declaration-marked deprecated compatibility methods are intentionally excluded. Do not edit this page manually.
</Note>

This page contains **51 methods**. Search the docs for an exact method name, or use this index:

* [`agent.list()`](#agent-list)
* [`agent.get()`](#agent-get)
* [`agent.create()`](#agent-create)
* [`agent.update()`](#agent-update)
* [`agent.listInbox()`](#agent-listInbox)
* [`agent.getInboxItem()`](#agent-getInboxItem)
* [`agent.pushInbox()`](#agent-pushInbox)
* [`agent.updateInboxItem()`](#agent-updateInboxItem)
* [`agent.removeInboxItem()`](#agent-removeInboxItem)
* [`agent.listPlugins()`](#agent-listPlugins)
* [`agent.getPlugin()`](#agent-getPlugin)
* [`agent.listRuns()`](#agent-listRuns)
* [`agent.getRun()`](#agent-getRun)
* [`agent.listRunEvents()`](#agent-listRunEvents)
* [`agent.listRunThreads()`](#agent-listRunThreads)
* [`agent.startRun()`](#agent-startRun)
* [`agent.resumeRun()`](#agent-resumeRun)
* [`agent.retryRun()`](#agent-retryRun)
* [`agent.tickRun()`](#agent-tickRun)
* [`agent.cancelRun()`](#agent-cancelRun)
* [`agent.reconcileRuns()`](#agent-reconcileRuns)
* [`agent.listThreads()`](#agent-listThreads)
* [`agent.getThread()`](#agent-getThread)
* [`agent.getThreadState()`](#agent-getThreadState)
* [`agent.getThreadGoal()`](#agent-getThreadGoal)
* [`agent.setThreadGoal()`](#agent-setThreadGoal)
* [`agent.pauseThreadGoal()`](#agent-pauseThreadGoal)
* [`agent.resumeThreadGoal()`](#agent-resumeThreadGoal)
* [`agent.clearThreadGoal()`](#agent-clearThreadGoal)
* [`agent.getThreadShare()`](#agent-getThreadShare)
* [`agent.enableThreadShare()`](#agent-enableThreadShare)
* [`agent.disableThreadShare()`](#agent-disableThreadShare)
* [`agent.getSharedThread()`](#agent-getSharedThread)
* [`agent.listSharedThreadMessages()`](#agent-listSharedThreadMessages)
* [`agent.getSharedThreadMessageExecutionDetails()`](#agent-getSharedThreadMessageExecutionDetails)
* [`agent.getSharedThreadMessageArtifact()`](#agent-getSharedThreadMessageArtifact)
* [`agent.forkSharedThreadMessage()`](#agent-forkSharedThreadMessage)
* [`agent.createThread()`](#agent-createThread)
* [`agent.deleteThread()`](#agent-deleteThread)
* [`agent.restoreThread()`](#agent-restoreThread)
* [`agent.listThreadMessages()`](#agent-listThreadMessages)
* [`agent.sendMessage()`](#agent-sendMessage)
* [`agent.retryMessage()`](#agent-retryMessage)
* [`agent.cancelThread()`](#agent-cancelThread)
* [`agent.forkMessage()`](#agent-forkMessage)
* [`agent.renameThread()`](#agent-renameThread)
* [`agent.resolveAction()`](#agent-resolveAction)
* [`agent.approveAction()`](#agent-approveAction)
* [`agent.rejectAction()`](#agent-rejectAction)
* [`agent.submitAction()`](#agent-submitAction)
* [`agent.compactThread()`](#agent-compactThread)

<span id="agent-list" aria-hidden="true" />

## `agent.list()`

Lists agents visible to the current execution context.

### Signature

```ts theme={null}
static list(): Promise<Agent[]>;
```

### Example

```ts theme={null}
const agents = await agent.list();
```

<span id="agent-get" aria-hidden="true" />

## `agent.get()`

Returns one agent by id.

### Signature

```ts theme={null}
static get(agentId: string): Promise<Agent>;
```

### Example

```ts theme={null}
const one = await agent.get(agentId);
```

<span id="agent-create" aria-hidden="true" />

## `agent.create()`

Creates a new agent. The server creates agentId, status, managed workspace,
timestamps, and version; supply an existing service-account user id only.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static create(data: AgentCreateInput): Promise<Agent>;
```

### Example

```ts theme={null}
const created = await agent.create({
  name: 'Ops copilot',
  serviceAccountUserId: userId,
});
```

<span id="agent-update" aria-hidden="true" />

## `agent.update()`

Updates mutable agent fields such as config, policy, or profile.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static update(agentId: string, data: AgentUpdateInput): Promise<Agent>;
```

### Example

```ts theme={null}
const updated = await agent.update(agentId, {
  desc: 'Handles operational runbooks.',
});
```

<span id="agent-listInbox" aria-hidden="true" />

## `agent.listInbox()`

Lists queued and historical inbox items for an agent.

### Signature

```ts theme={null}
static listInbox(agentId: string): Promise<AgentInboxItem[]>;
```

### Example

```ts theme={null}
const inbox = await agent.listInbox(agentId);
```

<span id="agent-getInboxItem" aria-hidden="true" />

## `agent.getInboxItem()`

Returns one inbox item for an agent.

### Signature

```ts theme={null}
static getInboxItem(
      agentId: string,
      agentInboxItemId: string,
    ): Promise<AgentInboxItem>;
```

### Example

```ts theme={null}
const item = await agent.getInboxItem(agentId, agentInboxItemId);
```

<span id="agent-pushInbox" aria-hidden="true" />

## `agent.pushInbox()`

Enqueues a new inbox item for an agent.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static pushInbox(
      agentId: string,
      data: AgentInboxItemCreateInput,
    ): Promise<AgentInboxItem>;
```

### Example

```ts theme={null}
const item = await agent.pushInbox(agentId, {
  instruction: 'Review failed deploy logs.',
});
```

<span id="agent-updateInboxItem" aria-hidden="true" />

## `agent.updateInboxItem()`

Updates an existing inbox item.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static updateInboxItem(
      agentId: string,
      agentInboxItemId: string,
      data: AgentInboxItemUpdateInput,
    ): Promise<AgentInboxItem>;
```

### Example

```ts theme={null}
const item = await agent.updateInboxItem(agentId, agentInboxItemId, {
  instruction: 'Review the updated deployment evidence.',
});
```

<span id="agent-removeInboxItem" aria-hidden="true" />

## `agent.removeInboxItem()`

Removes an inbox item.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static removeInboxItem(
      agentId: string,
      agentInboxItemId: string,
    ): Promise<AgentInboxItem>;
```

### Example

```ts theme={null}
await agent.removeInboxItem(agentId, agentInboxItemId);
```

<span id="agent-listPlugins" aria-hidden="true" />

## `agent.listPlugins()`

Lists agent plugins configured for an agent.

### Signature

```ts theme={null}
static listPlugins(agentId: string): Promise<AgentPlugin[]>;
```

### Example

```ts theme={null}
const tools = await agent.listPlugins(agentId);
```

<span id="agent-getPlugin" aria-hidden="true" />

## `agent.getPlugin()`

Returns one agent plugin definition for an agent.

### Signature

```ts theme={null}
static getPlugin(
      agentId: string,
      toolId: string,
    ): Promise<AgentPlugin>;
```

### Example

```ts theme={null}
const tool = await agent.getPlugin(agentId, toolId);
```

<span id="agent-listRuns" aria-hidden="true" />

## `agent.listRuns()`

Lists runs for an agent.

### Signature

```ts theme={null}
static listRuns(agentId: string): Promise<AgentRun[]>;
```

### Example

```ts theme={null}
const runs = await agent.listRuns(agentId);
```

<span id="agent-getRun" aria-hidden="true" />

## `agent.getRun()`

Returns one agent run.

### Signature

```ts theme={null}
static getRun(agentRunId: string): Promise<AgentRun>;
```

### Example

```ts theme={null}
const run = await agent.getRun(agentRunId);
```

<span id="agent-listRunEvents" aria-hidden="true" />

## `agent.listRunEvents()`

Lists persisted events for a run.

### Signature

```ts theme={null}
static listRunEvents(agentRunId: string): Promise<AgentRunEvent[]>;
```

### Example

```ts theme={null}
const events = await agent.listRunEvents(agentRunId);
```

<span id="agent-listRunThreads" aria-hidden="true" />

## `agent.listRunThreads()`

Lists assistant threads associated with a run.

### Signature

```ts theme={null}
static listRunThreads(agentRunId: string): Promise<AgentRunThread[]>;
```

### Example

```ts theme={null}
const threads = await agent.listRunThreads(agentRunId);
```

<span id="agent-startRun" aria-hidden="true" />

## `agent.startRun()`

Starts a new agent run.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static startRun(agentId: string, data: AgentRunInput): Promise<AgentRun>;
```

### Example

```ts theme={null}
const run = await agent.startRun(agentId, {
  instruction: 'Summarize today\\'s alerts.',
});
```

<span id="agent-resumeRun" aria-hidden="true" />

## `agent.resumeRun()`

Resumes a paused run.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static resumeRun(agentRunId: string): Promise<AgentRun>;
```

### Example

```ts theme={null}
const run = await agent.resumeRun(agentRunId);
```

<span id="agent-retryRun" aria-hidden="true" />

## `agent.retryRun()`

Retries a failed or completed run from its retry policy.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static retryRun(agentRunId: string): Promise<AgentRun>;
```

### Example

```ts theme={null}
const run = await agent.retryRun(agentRunId);
```

<span id="agent-tickRun" aria-hidden="true" />

## `agent.tickRun()`

Forces one autonomous tick for a run.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static tickRun(agentRunId: string): Promise<AgentRun>;
```

### Example

```ts theme={null}
const run = await agent.tickRun(agentRunId);
```

<span id="agent-cancelRun" aria-hidden="true" />

## `agent.cancelRun()`

Cancels a run, optionally recording a reason.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static cancelRun(
      agentRunId: string,
      data?: AgentRunCancelInput,
    ): Promise<AgentRun>;
```

### Example

```ts theme={null}
const run = await agent.cancelRun(agentRunId, { reason: 'Operator stop' });
```

<span id="agent-reconcileRuns" aria-hidden="true" />

## `agent.reconcileRuns()`

Reconciles stalled runs with the loop scheduler.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static reconcileRuns(): Promise<any>;
```

### Example

```ts theme={null}
await agent.reconcileRuns();
```

<span id="agent-listThreads" aria-hidden="true" />

## `agent.listThreads()`

Lists assistant threads visible through the agent helper.

### Signature

```ts theme={null}
static listThreads(
      query?: Record<string, any>,
    ): Promise<CollectionResult<AssistantThread>>;
```

### Example

```ts theme={null}
const threads = await agent.listThreads({ take: 20 });
```

<span id="agent-getThread" aria-hidden="true" />

## `agent.getThread()`

Returns one assistant thread.

### Signature

```ts theme={null}
static getThread(
      assistantThreadId: string,
      options?: { hideDeleted?: boolean },
    ): Promise<AssistantThread>;
```

### Example

```ts theme={null}
const thread = await agent.getThread(assistantThreadId);
```

<span id="agent-getThreadState" aria-hidden="true" />

## `agent.getThreadState()`

Returns the hidden runtime planning state for a thread.

### Signature

```ts theme={null}
static getThreadState(
      assistantThreadId: string,
    ): Promise<AssistantThreadState>;
```

### Example

```ts theme={null}
const state = await agent.getThreadState(assistantThreadId);
```

<span id="agent-getThreadGoal" aria-hidden="true" />

## `agent.getThreadGoal()`

Returns the current durable goal for a thread, if one exists.

### Signature

```ts theme={null}
static getThreadGoal(
      assistantThreadId: string,
    ): Promise<AssistantThreadGoal | null>;
```

<Note>No dedicated example is encoded in the current editor declaration. The signature is authoritative.</Note>

<span id="agent-setThreadGoal" aria-hidden="true" />

## `agent.setThreadGoal()`

Sets or replaces the durable thread goal without appending a user message.

### Signature

```ts theme={null}
static setThreadGoal(
      assistantThreadId: string,
      data: AssistantThreadGoalInput,
    ): Promise<AssistantThreadGoal>;
```

<Note>No dedicated example is encoded in the current editor declaration. The signature is authoritative.</Note>

<span id="agent-pauseThreadGoal" aria-hidden="true" />

## `agent.pauseThreadGoal()`

Pauses goal validation while preserving the objective.

### Signature

```ts theme={null}
static pauseThreadGoal(
      assistantThreadId: string,
    ): Promise<AssistantThreadGoal>;
```

<Note>No dedicated example is encoded in the current editor declaration. The signature is authoritative.</Note>

<span id="agent-resumeThreadGoal" aria-hidden="true" />

## `agent.resumeThreadGoal()`

Resumes goal validation for the current objective.

### Signature

```ts theme={null}
static resumeThreadGoal(
      assistantThreadId: string,
    ): Promise<AssistantThreadGoal>;
```

<Note>No dedicated example is encoded in the current editor declaration. The signature is authoritative.</Note>

<span id="agent-clearThreadGoal" aria-hidden="true" />

## `agent.clearThreadGoal()`

Clears the current durable goal without changing visible messages.

### Signature

```ts theme={null}
static clearThreadGoal(
      assistantThreadId: string,
    ): Promise<AssistantThreadGoal>;
```

<Note>No dedicated example is encoded in the current editor declaration. The signature is authoritative.</Note>

<span id="agent-getThreadShare" aria-hidden="true" />

## `agent.getThreadShare()`

Returns the current share state for a thread owned by the current user.

### Signature

```ts theme={null}
static getThreadShare(
      assistantThreadId: string,
    ): Promise<AssistantThreadShare | null>;
```

### Example

```ts theme={null}
const share = await agent.getThreadShare(assistantThreadId);
```

<span id="agent-enableThreadShare" aria-hidden="true" />

## `agent.enableThreadShare()`

Creates or re-enables a stable share link for a thread owned by the current user.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static enableThreadShare(
      assistantThreadId: string,
    ): Promise<AssistantThreadShare>;
```

### Example

```ts theme={null}
const share = await agent.enableThreadShare(assistantThreadId);
```

<span id="agent-disableThreadShare" aria-hidden="true" />

## `agent.disableThreadShare()`

Disables the stable share link for a thread owned by the current user.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static disableThreadShare(
      assistantThreadId: string,
    ): Promise<AssistantThreadShare>;
```

### Example

```ts theme={null}
await agent.disableThreadShare(assistantThreadId);
```

<span id="agent-getSharedThread" aria-hidden="true" />

## `agent.getSharedThread()`

Returns a read-only shared thread by share ID.

### Signature

```ts theme={null}
static getSharedThread(
      shareId: string,
    ): Promise<AssistantSharedThreadResponse>;
```

### Example

```ts theme={null}
const shared = await agent.getSharedThread(shareId);
```

<span id="agent-listSharedThreadMessages" aria-hidden="true" />

## `agent.listSharedThreadMessages()`

Lists visible messages for a shared thread.

### Signature

```ts theme={null}
static listSharedThreadMessages(
      shareId: string,
      query?: Record<string, any>,
    ): Promise<CollectionResult<AssistantMessage>>;
```

### Example

```ts theme={null}
const messages = await agent.listSharedThreadMessages(shareId, { take: 50 });
```

<span id="agent-getSharedThreadMessageExecutionDetails" aria-hidden="true" />

## `agent.getSharedThreadMessageExecutionDetails()`

Returns sanitized execution details for a visible shared-thread message.

### Signature

```ts theme={null}
static getSharedThreadMessageExecutionDetails(
      shareId: string,
      assistantMessageId: string,
    ): Promise<Record<string, any>>;
```

### Example

```ts theme={null}
const details = await agent.getSharedThreadMessageExecutionDetails(shareId, assistantMessageId);
```

<span id="agent-getSharedThreadMessageArtifact" aria-hidden="true" />

## `agent.getSharedThreadMessageArtifact()`

Returns one sanitized artifact for a visible shared-thread message.

### Signature

```ts theme={null}
static getSharedThreadMessageArtifact(
      shareId: string,
      assistantMessageId: string,
      artifactId: string,
    ): Promise<Record<string, any>>;
```

### Example

```ts theme={null}
const artifact = await agent.getSharedThreadMessageArtifact(shareId, assistantMessageId, artifactId);
```

<span id="agent-forkSharedThreadMessage" aria-hidden="true" />

## `agent.forkSharedThreadMessage()`

Forks a shared thread from a selected visible message.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static forkSharedThreadMessage(
      shareId: string,
      assistantMessageId: string,
      data?: AssistantForkMessageInput,
    ): Promise<AssistantThreadResponse>;
```

### Example

```ts theme={null}
const fork = await agent.forkSharedThreadMessage(shareId, assistantMessageId);
```

<span id="agent-createThread" aria-hidden="true" />

## `agent.createThread()`

Creates a new assistant thread and first message.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static createThread(
      data: AssistantMessageInput,
    ): Promise<AssistantThreadResponse>;
```

### Example

```ts theme={null}
const response = await agent.createThread({ content: 'Draft a release note.' });
```

<span id="agent-deleteThread" aria-hidden="true" />

## `agent.deleteThread()`

Soft-deletes a thread.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static deleteThread(assistantThreadId: string): Promise<void>;
```

### Example

```ts theme={null}
await agent.deleteThread(assistantThreadId);
```

<span id="agent-restoreThread" aria-hidden="true" />

## `agent.restoreThread()`

Restores a deleted thread.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static restoreThread(assistantThreadId: string): Promise<void>;
```

### Example

```ts theme={null}
await agent.restoreThread(assistantThreadId);
```

<span id="agent-listThreadMessages" aria-hidden="true" />

## `agent.listThreadMessages()`

Lists visible messages for a thread.

### Signature

```ts theme={null}
static listThreadMessages(
      assistantThreadId: string,
      query?: Record<string, any>,
    ): Promise<CollectionResult<AssistantMessage>>;
```

### Example

```ts theme={null}
const messages = await agent.listThreadMessages(assistantThreadId, { take: 50 });
```

<span id="agent-sendMessage" aria-hidden="true" />

## `agent.sendMessage()`

Sends a new message into an existing thread.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static sendMessage(
      assistantThreadId: string,
      data: AssistantMessageInput,
    ): Promise<AssistantThreadResponse>;
```

### Example

```ts theme={null}
const response = await agent.sendMessage(assistantThreadId, {
  content: 'Continue with the rollout checklist.',
});
```

<span id="agent-retryMessage" aria-hidden="true" />

## `agent.retryMessage()`

Retries one assistant message.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static retryMessage(
      assistantThreadId: string,
      assistantMessageId: string,
    ): Promise<AssistantThreadResponse>;
```

### Example

```ts theme={null}
const response = await agent.retryMessage(assistantThreadId, assistantMessageId);
```

<span id="agent-cancelThread" aria-hidden="true" />

## `agent.cancelThread()`

Cancels in-flight work on a thread.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static cancelThread(assistantThreadId: string, expectedVersion: number): Promise<void>;
```

### Example

```ts theme={null}
await agent.cancelThread(assistantThreadId, thread.version);
```

<span id="agent-forkMessage" aria-hidden="true" />

## `agent.forkMessage()`

Forks a thread from a selected message.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static forkMessage(
      assistantThreadId: string,
      assistantMessageId: string,
      data?: AssistantForkMessageInput,
    ): Promise<AssistantThreadResponse>;
```

### Example

```ts theme={null}
const fork = await agent.forkMessage(assistantThreadId, assistantMessageId);
```

<span id="agent-renameThread" aria-hidden="true" />

## `agent.renameThread()`

Renames a thread.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static renameThread(
      assistantThreadId: string,
      data: AssistantThreadTitleInput,
    ): Promise<AssistantThread>;
```

### Example

```ts theme={null}
const thread = await agent.renameThread(assistantThreadId, {
  title: 'Postmortem draft',
});
```

<span id="agent-resolveAction" aria-hidden="true" />

## `agent.resolveAction()`

Resolves an action-required checkpoint with an explicit payload.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static resolveAction(
      assistantThreadId: string,
      assistantActionRequiredId: string,
      data: AssistantActionResolutionInput,
    ): Promise<AssistantThreadResponse>;
```

### Example

```ts theme={null}
const response = await agent.resolveAction(assistantThreadId, actionId, {
  decision: 'approve',
});
```

<span id="agent-approveAction" aria-hidden="true" />

## `agent.approveAction()`

Approves an action-required checkpoint.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static approveAction(
      assistantThreadId: string,
      assistantActionRequiredId: string,
      options?: Omit<AssistantActionResolutionInput, 'decision'>,
    ): Promise<AssistantThreadResponse>;
```

### Example

```ts theme={null}
const response = await agent.approveAction(assistantThreadId, actionId);
```

<span id="agent-rejectAction" aria-hidden="true" />

## `agent.rejectAction()`

Rejects an action-required checkpoint.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static rejectAction(
      assistantThreadId: string,
      assistantActionRequiredId: string,
      options?: Omit<AssistantActionResolutionInput, 'decision'>,
    ): Promise<AssistantThreadResponse>;
```

### Example

```ts theme={null}
const response = await agent.rejectAction(assistantThreadId, actionId, {
  responseText: 'Need a narrower scope.',
});
```

<span id="agent-submitAction" aria-hidden="true" />

## `agent.submitAction()`

Submits operator input for an action-required checkpoint.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static submitAction(
      assistantThreadId: string,
      assistantActionRequiredId: string,
      options?: Omit<AssistantActionResolutionInput, 'decision'>,
    ): Promise<AssistantThreadResponse>;
```

### Example

```ts theme={null}
const response = await agent.submitAction(assistantThreadId, actionId, {
  responsePayload: { selectedPlanId: 'plan-1' },
});
```

<span id="agent-compactThread" aria-hidden="true" />

## `agent.compactThread()`

Triggers thread compaction.

Notes:

* No-op in debug mode.

### Signature

```ts theme={null}
static compactThread(
      assistantThreadId: string,
      options?: AssistantThreadCompactionRequest,
    ): Promise<AssistantThread>;
```

### Example

```ts theme={null}
const thread = await agent.compactThread(assistantThreadId, {
  force: true,
});
```