跳转到内容
Awaken

集成 CopilotKit（AG-UI）

当你有一个 CopilotKit React 前端，并想通过 AG-UI 协议接入 awaken agent server 时，使用本页。

前置条件

Section titled “前置条件”
  • 已有可运行的 awaken runtime
  • awaken 启用了 server
  • Node.js 项目中已安装 @copilotkit/react-core 和 @copilotkit/react-ui
[dependencies]
awaken = { git = "https://github.com/AwakenWorks/awaken", features = ["server"] }
tokio = { version = "1", features = ["full"] }
async-trait = "0.1"
serde_json = "1"
tracing-subscriber = "0.3"

步骤

Section titled “步骤”
  1. 启动后端 server：
use std::sync::Arc;


use awaken::engine::GenaiExecutor;
use awaken::contract::storage::ThreadRunStore;
use awaken::registry_spec::ModelSpec;
use awaken::registry_spec::AgentSpec;
use awaken::stores::{InMemoryMailboxStore, InMemoryStore};
use awaken::AgentRuntimeBuilder;
use awaken::server::app::{ServerState, ServerConfig};
use awaken::server::mailbox::{Mailbox, MailboxConfig};
use awaken::server::routes::build_router;


#[tokio::main]
async fn main() {
    tracing_subscriber::fmt().with_target(true).init();


    let agent_spec = AgentSpec::new("copilotkit-agent")
        .with_model_id("gpt-4o-mini")
        .with_system_prompt(
            "You are a CopilotKit-powered assistant. \
             Update shared state and suggest actions when appropriate.",
        )
        .with_max_rounds(10);


    let runtime = AgentRuntimeBuilder::new()
        .with_provider("openai", Arc::new(GenaiExecutor::new()))
        .with_model(ModelSpec::new("gpt-4o-mini", "openai", "gpt-4o-mini"))
        .with_agent_spec(agent_spec)
        .build()
        .expect("failed to build runtime");
    let runtime = Arc::new(runtime);


    let store = Arc::new(InMemoryStore::new());
    let resolver = runtime.resolver_arc();


    let mailbox_store = Arc::new(InMemoryMailboxStore::new());
    let mailbox = Arc::new(Mailbox::new(
        runtime.clone(),
        mailbox_store as Arc<dyn awaken::contract::MailboxStore>,
        store.clone() as Arc<dyn ThreadRunStore>,
        format!("copilotkit:{}", std::process::id()),
        MailboxConfig::default(),
    ));


    let state = ServerState::new(
        runtime,
        mailbox,
        store as Arc<dyn ThreadRunStore>,
        resolver,
        ServerConfig {
            address: "127.0.0.1:3000".into(),
            ..Default::default()
        },
    );


    let app = build_router().with_state(state);


    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .expect("failed to bind");
    axum::serve(listener, app).await.expect("server crashed");
}

服务器会自动在以下路径注册 AG-UI 路由：

AG-UI 路由包括：

  • POST /v1/ag-ui/run
  • POST /v1/ag-ui/threads/:thread_id/runs
  • POST /v1/ag-ui/agents/:agent_id/runs
  • POST /v1/ag-ui/threads/:thread_id/interrupt
  • GET /v1/ag-ui/threads/:thread_id/replay
  • GET /v1/ag-ui/threads/:id/messages

Replay 路由要求接入 ProtocolReplayLog，用于按 thread 回放持久协议 frame； 普通 live reconnect 仍然使用活动 SSE stream。

  1. 安装 CopilotKit：
Terminal window
npm install @copilotkit/react-core @copilotkit/react-ui
  1. 用 CopilotKit provider 包裹应用：
import { CopilotKit } from "@copilotkit/react-core";
import { CopilotChat } from "@copilotkit/react-ui";
import "@copilotkit/react-ui/styles.css";


export default function App() {
  return (
    <CopilotKit runtimeUrl="http://localhost:3000/v1/ag-ui/run">
      <CopilotChat
        labels={{ title: "Agent", initial: "How can I help?" }}
      />
    </CopilotKit>
  );
}
  1. 分别启动后端和前端。

验证

Section titled “验证”
  1. 打开页面
  2. 在 CopilotChat 中发送消息
  3. 确认聊天 UI 中有流式回复
  4. 查看后端日志里的 RunStart / RunFinish

常见错误

Section titled “常见错误”
错误原因修复
浏览器 CORS 错误未配置 CORS 中间件给 axum router 加 CORS
CopilotKit 提示 connection failedruntimeUrl 错了指向 http://localhost:3000/v1/ag-ui/run（AG-UI 的 run 端点，不是命名空间）
有事件但 UI 不更新AG-UI 事件格式不兼容确认 CopilotKit 版本匹配
/v1/ag-ui/run 返回 404没开 server feature在 Cargo.toml 里启用

相关示例

Section titled “相关示例”
  • examples/copilotkit-starter/agent/src/main.rs

关键文件

Section titled “关键文件”
路径作用
crates/awaken-server/src/protocols/ag_ui/http.rsAG-UI 路由
crates/awaken-server/src/protocols/ag_ui/encoder.rsAG-UI encoder
crates/awaken-server/src/routes.rs总路由
crates/awaken-server/src/app.rsServerState / ServerConfig
examples/copilotkit-starter/agent/src/main.rsCopilotKit starter 后端入口

相关

Section titled “相关”