runtime

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

assistant-ui Runtime

assistant-ui 运行时

Always consult assistant-ui.com/llms.txt for latest API.

请始终参考assistant-ui.com/llms.txt获取最新API。

References

参考文档

./references/local-runtime.md -- useLocalRuntime deep dive
./references/external-store.md -- useExternalStoreRuntime deep dive
./references/thread-list.md -- Thread list management
./references/state-hooks.md -- State access hooks
./references/types.md -- Type definitions

./references/local-runtime.md -- useLocalRuntime 深度解析
./references/external-store.md -- useExternalStoreRuntime 深度解析
./references/thread-list.md -- 线程列表管理
./references/state-hooks.md -- 状态访问钩子
./references/types.md -- 类型定义

Runtime Hierarchy

运行时层级结构

AssistantRuntime
├── ThreadListRuntime (thread management)
│   ├── ThreadListItemRuntime (per-thread item)
│   └── ...
└── ThreadRuntime (current thread)
    ├── ComposerRuntime (input state)
    └── MessageRuntime[] (per-message)
        └── MessagePartRuntime[] (per-content-part)

AssistantRuntime
├── ThreadListRuntime (thread management)
│   ├── ThreadListItemRuntime (per-thread item)
│   └── ...
└── ThreadRuntime (current thread)
    ├── ComposerRuntime (input state)
    └── MessageRuntime[] (per-message)
        └── MessagePartRuntime[] (per-content-part)

State Access (Modern API)

状态访问（现代API）

tsx

import { useAssistantApi, useAssistantState, useAssistantEvent } from "@assistant-ui/react";

function ChatControls() {
  const api = useAssistantApi();
  const messages = useAssistantState(s => s.thread.messages);
  const isRunning = useAssistantState(s => s.thread.isRunning);

  useAssistantEvent("message-added", (e) => {
    console.log("New message:", e.message);
  });

  return (
    <div>
      <button onClick={() => api.thread().append({
        role: "user",
        content: [{ type: "text", text: "Hello!" }],
      })}>
        Send
      </button>
      {isRunning && (
        <button onClick={() => api.thread().cancelRun()}>Cancel</button>
      )}
    </div>
  );
}

tsx

import { useAssistantApi, useAssistantState, useAssistantEvent } from "@assistant-ui/react";

function ChatControls() {
  const api = useAssistantApi();
  const messages = useAssistantState(s => s.thread.messages);
  const isRunning = useAssistantState(s => s.thread.isRunning);

  useAssistantEvent("message-added", (e) => {
    console.log("New message:", e.message);
  });

  return (
    <div>
      <button onClick={() => api.thread().append({
        role: "user",
        content: [{ type: "text", text: "Hello!" }],
      })}>
        Send
      </button>
      {isRunning && (
        <button onClick={() => api.thread().cancelRun()}>Cancel</button>
      )}
    </div>
  );
}

Thread Operations

线程操作

tsx

const api = useAssistantApi();
const thread = api.thread();

// Append message
thread.append({ role: "user", content: [{ type: "text", text: "Hello" }] });

// Cancel generation
thread.cancelRun();

// Get current state
const state = thread.getState();  // { messages, isRunning, ... }

tsx

const api = useAssistantApi();
const thread = api.thread();

// Append message
thread.append({ role: "user", content: [{ type: "text", text: "Hello" }] });

// Cancel generation
thread.cancelRun();

// Get current state
const state = thread.getState();  // { messages, isRunning, ... }

Message Operations

消息操作

tsx

const message = api.thread().message(0);  // By index

message.edit({ role: "user", content: [{ type: "text", text: "Updated" }] });
message.reload();

tsx

const message = api.thread().message(0);  // By index

message.edit({ role: "user", content: [{ type: "text", text: "Updated" }] });
message.reload();

Events

事件

tsx

useAssistantEvent("thread-started", () => {});
useAssistantEvent("thread-ended", () => {});
useAssistantEvent("message-added", ({ message }) => {});
useAssistantEvent("run-started", () => {});
useAssistantEvent("run-ended", () => {});

tsx

useAssistantEvent("thread-started", () => {});
useAssistantEvent("thread-ended", () => {});
useAssistantEvent("message-added", ({ message }) => {});
useAssistantEvent("run-started", () => {});
useAssistantEvent("run-ended", () => {});

Capabilities

功能支持

tsx

const caps = useAssistantState(s => s.thread.capabilities);
// { cancel, edit, reload, copy, speak, attachments }

tsx

const caps = useAssistantState(s => s.thread.capabilities);
// { cancel, edit, reload, copy, speak, attachments }

Quick Reference

快速参考

tsx

// Get messages
const messages = useAssistantState(s => s.thread.messages);

// Check running state
const isRunning = useAssistantState(s => s.thread.isRunning);

// Append message
api.thread().append({ role: "user", content: [{ type: "text", text: "Hi" }] });

// Cancel generation
api.thread().cancelRun();

// Edit message
api.thread().message(index).edit({ ... });

// Reload message
api.thread().message(index).reload();

tsx

// Get messages
const messages = useAssistantState(s => s.thread.messages);

// Check running state
const isRunning = useAssistantState(s => s.thread.isRunning);

// Append message
api.thread().append({ role: "user", content: [{ type: "text", text: "Hi" }] });

// Cancel generation
api.thread().cancelRun();

// Edit message
api.thread().message(index).edit({ ... });

// Reload message
api.thread().message(index).reload();

Common Gotchas

常见问题

"Cannot read property of undefined"

Ensure hooks are called inside
```
AssistantRuntimeProvider
```

State not updating

Use selectors with
```
useAssistantState
```
to prevent unnecessary re-renders

Messages array empty

Check runtime is configured
Verify API response format

"Cannot read property of undefined"

确保在
```
AssistantRuntimeProvider
```
内部调用钩子

State not updating

使用
```
useAssistantState
```
的选择器来避免不必要的重渲染

Messages array empty

检查运行时是否已配置
验证API响应格式