@cloudbase/agent-server 1.0.1-alpha.7 → 1.0.1-alpha.9

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @cloudbase/agent-server
 
+## 1.0.1-alpha.8
+
+### Patch Changes
+
+- alpha release 0.1.2-alpha.1
+  - Update all public packages to version 0.1.2-alpha.1
+  - Trigger automated alpha release workflow
+  - Includes latest features and improvements
+
+- Updated dependencies
+  - @cloudbase/agent-shared@1.0.1-alpha.8
+
+## 1.0.1-alpha.7
+
+### Patch Changes
+
+- alpha release 0.1.2-alpha.1
+  - Update all public packages to version 0.1.2-alpha.1
+  - Trigger automated alpha release workflow
+  - Includes latest features and improvements
+
+- Updated dependencies
+  - @cloudbase/agent-shared@1.0.1-alpha.7
+
 ## 1.0.1-alpha.6
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,253 @@
+# @cloudbase/agent-server
+
+将 AG-UI 兼容的 Agent 部署为 HTTP 服务。
+
+## 什么是 AG-UI？
+
+[AG-UI](https://ag-ui.com/) 是一个开放、轻量级、基于事件的协议，用于标准化 AI Agent 与用户界面的交互。它让 Agent 可以：
+
+- 实时流式对话
+- 双向状态同步
+- 前端工具集成（Client Tools）
+- 人机协作（Human-in-the-loop）
+
+## 这个包解决什么问题？
+
+- **快速部署 Agent 为 HTTP 服务**：一行代码将 Agent 部署为支持 AG-UI 协议的 HTTP 服务
+- **多端点支持**：自动创建 `/send-message`、`/healthz` 等端点
+- **云函数兼容**：自动适配腾讯云开发 HTTP 云函数环境
+
+### 架构图
+
+```mermaid
+flowchart LR
+    Client[AG-UI 客户端] -->|AG-UI 协议| Server["@cloudbase/agent-server"]
+    Server --> Adapter[Adapter<br/>LangGraph / LangChain]
+    Adapter --> Agent[Agent 框架]
+```
+
+## 配合使用
+
+| 包名 | 作用 |
+|------|------|
+| `@cloudbase/agent-adapter-langgraph` | LangGraph 工作流适配器 |
+| `@cloudbase/agent-adapter-langchain` | LangChain Agent 适配器 |
+| `express` | HTTP 服务框架 |
+
+## 安装
+
+```bash
+pnpm add @cloudbase/agent-server express
+```
+
+## 快速开始
+
+### 方式一：使用 run（最简单）
+
+```typescript
+import { run } from "@cloudbase/agent-server";
+import { LanggraphAgent } from "@cloudbase/agent-adapter-langgraph";
+import { workflow } from "./workflow.js"; // 你的 LangGraph 工作流
+
+run({
+  createAgent: () => ({
+    agent: new LanggraphAgent({ workflow }),
+  }),
+  port: 9000,
+});
+```
+
+### 方式二：使用 createExpressServer
+
+创建一个配置好的 Express 应用：
+
+```typescript
+import { createExpressServer } from "@cloudbase/agent-server";
+import { LanggraphAgent } from "@cloudbase/agent-adapter-langgraph";
+import { workflow } from "./workflow.js";
+
+const app = createExpressServer({
+  createAgent: () => ({
+    agent: new LanggraphAgent({ workflow }),
+  }),
+});
+
+app.listen(9000, () => console.log("Listening on 9000!"));
+```
+
+### 方式三：使用 createExpressRoutes
+
+将路由挂载到现有的 Express 应用：
+
+```typescript
+import { createExpressRoutes } from "@cloudbase/agent-server";
+import { LanggraphAgent } from "@cloudbase/agent-adapter-langgraph";
+import { workflow } from "./workflow.js";
+import express from "express";
+
+const app = express();
+
+createExpressRoutes({
+  createAgent: () => ({
+    agent: new LanggraphAgent({ workflow }),
+  }),
+  express: app,
+});
+
+app.listen(9000, () => console.log("Listening on 9000!"));
+```
+
+## API 参考
+
+### run
+
+创建并启动 HTTP 服务。
+
+```typescript
+run({
+  createAgent,
+  port: 9000,
+});
+```
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `createAgent` | `AgentCreator` | Agent 创建函数，见下方说明 |
+| `port` | `number \| string` | 监听端口 |
+| `basePath` | `string` | 可选，路由基础路径，默认为 `/`，云函数环境默认为 `/v1/aibot/bots/:agentId/` |
+| `cors` | `boolean \| CorsOptions` | 可选，CORS 配置，默认启用 |
+| `logger` | `Logger` | 可选，日志实例，用于记录服务端日志 |
+
+### createExpressServer
+
+创建一个配置好的 Express 应用。
+
+```typescript
+const app = createExpressServer({
+  createAgent,
+  cors: true,       // 可选，默认启用 CORS
+});
+```
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `createAgent` | `AgentCreator` | Agent 创建函数，见下方说明 |
+| `basePath` | `string` | 可选，路由基础路径 |
+| `cors` | `boolean \| CorsOptions` | 可选，CORS 配置，默认启用 |
+| `logger` | `Logger` | 可选，日志实例，用于记录服务端日志 |
+
+### createExpressRoutes
+
+将 AG-UI 路由挂载到现有的 Express 应用。
+
+```typescript
+createExpressRoutes({
+  createAgent,
+  express: app,
+  basePath,         // 可选
+});
+```
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `createAgent` | `AgentCreator` | Agent 创建函数，见下方说明 |
+| `express` | `Express` | Express 应用实例 |
+| `basePath` | `string` | 可选，路由基础路径，默认为 `/`，云函数环境默认为 `/v1/aibot/bots/:agentId/` |
+| `logger` | `Logger` | 可选，日志实例，用于记录服务端日志 |
+
+## 自动创建的端点
+
+| 端点 | 说明 |
+|------|------|
+| `{basePath}send-message` | AG-UI 消息发送端点 |
+| `{basePath}healthz` | 健康检查端点 |
+
+## createAgent 参数
+
+`createAgent` 返回一个对象：
+- `agent`：符合 [AG-UI 协议](https://docs.ag-ui.com) 的 Agent
+- `cleanup`：可选，请求结束后的清理函数
+
+```typescript
+type AgentCreator = (context?: {
+  request: Request;     // 当前 HTTP 请求（Web Standard Request）
+  logger?: Logger;      // 日志实例（带 requestId 上下文）
+  requestId?: string;   // 请求追踪 ID
+}) => AgentCreatorResult | Promise<AgentCreatorResult>; // 支持异步
+
+type AgentCreatorResult = {
+  agent: AbstractAgent | { toAGUIAgent(): AbstractAgent }; // AG-UI 兼容的 Agent
+  cleanup?: () => void; // 可选，清理函数
+};
+```
+
+使用适配器将你的 Agent 框架转换为 AG-UI 兼容的 Agent：
+
+| 适配器 | 包名 | 说明 |
+|--------|------|------|
+| `LanggraphAgent` | `@cloudbase/agent-adapter-langgraph` | LangGraph 工作流适配器 |
+| `LangchainAgent` | `@cloudbase/agent-adapter-langchain` | LangChain Agent 适配器 |
+
+```typescript
+import { LanggraphAgent } from "@cloudbase/agent-adapter-langgraph";
+
+createAgent: () => ({
+  agent: new LanggraphAgent({ workflow }),
+})
+```
+
+**高级用法：** `createAgent` 可以接收请求上下文，也支持异步：
+
+```typescript
+createAgent: async (context) => {
+  console.log("Request ID:", context.requestId);
+  return { agent: new LanggraphAgent({ workflow }) };
+}
+```
+
+## Logger
+
+`logger` 参数用于记录服务端日志。需要实现以下接口：
+
+```typescript
+interface Logger {
+  info?(message: string): void;
+  info?(obj: object, message?: string): void;
+  debug?(message: string): void;
+  debug?(obj: object, message?: string): void;
+  warn?(message: string): void;
+  warn?(obj: object, message?: string): void;
+  error?(message: string): void;
+  error?(obj: object, message?: string): void;
+  trace?(message: string): void;
+  trace?(obj: object, message?: string): void;
+  child?(bindings: object): Logger; // 创建带上下文的子 logger
+}
+```
+
+**示例：**
+
+```typescript
+// 开发环境：使用 console
+run({ createAgent, logger: console, port: 9000 });
+
+// 生产环境：使用 pino
+import pino from "pino";
+run({ createAgent, logger: pino({ level: "info" }), port: 9000 });
+```
+
+## 文档
+
+📚 完整文档请参阅 [云开发 Agent 开发指南](https://docs.cloudbase.net/ai/agent-development/)
+
+## 相关资源
+
+- [AG-UI 协议](https://docs.cloudbase.net/ai/agent-development/ag-ui-protocol)
+- [框架开发指南](https://docs.cloudbase.net/ai/agent-development/frameworks/)
+- [部署指南](https://docs.cloudbase.net/ai/agent-development/deploy/)

package/dist/index.d.ts

@@ -1,10 +1,12 @@
+import * as _cloudbase_agent_observability_server from '@cloudbase/agent-observability/server';
 import { CreateCopilotRuntimeServerOptions } from '@copilotkit/runtime';
 import { CopilotRuntimeOptions } from '@copilotkit/runtime/v2';
 import expressLib, { Express } from 'express';
 import * as _ag_ui_client from '@ag-ui/client';
 import { AbstractAgent, RunAgentInput } from '@ag-ui/client';
 import cors from 'cors';
-import { SendMessageInput } from '@cloudbase/agent-shared';
+import { Logger, SendMessageInput } from '@cloudbase/agent-shared';
+export { LogFn, Logger, createConsoleLogger, isErrorWithCode, noopLogger } from '@cloudbase/agent-shared';
 import { Repeater } from '@repeaterjs/repeater';
 import * as _whatwg_node_server from '@whatwg-node/server';
 import { OpenAI } from 'openai';
@@ -16,6 +18,10 @@ import { OpenAI } from 'openai';
 interface AgentCreatorContext {
     /** The incoming HTTP request (Web Standard Request) */
     request: Request;
+    /** Logger instance for this request (with requestId context). Only available when using AGUI routes. */
+    logger?: Logger;
+    /** Unique request ID for tracing. Only available when using AGUI routes. */
+    requestId?: string;
 }
 type AgentCreatorRet = {
     agent: AbstractAgent | {
@@ -34,16 +40,61 @@ interface ICreateServer {
     cors?: boolean | cors.CorsOptions;
     useAGUI?: boolean;
     aguiOptions?: AGUIOptions;
+    /**
+     * Logger instance for structured logging.
+     *
+     * @default noopLogger (silent - no output)
+     *
+     * @example
+     * // Development: see all logs
+     * createExpressServer({ createAgent, logger: console });
+     *
+     * // Production: structured JSON logs
+     * import pino from 'pino';
+     * createExpressServer({ createAgent, logger: pino({ level: 'info' }) });
+     */
+    logger?: Logger;
+    /**
+     * Observability configuration for trace exporters.
+     *
+     * Requires @cloudbase/agent-observability package to be installed.
+     * If the package is not installed, this option is silently ignored.
+     *
+     * @example
+     * // Console exporter (from env AUTO_TRACES_STDOUT)
+     * createExpressServer({ createAgent, observability: { type: 'console' } });
+     *
+     * // OTLP exporter (Langfuse, Jaeger, etc.)
+     * createExpressServer({
+     *   createAgent,
+     *   observability: {
+     *     type: 'otlp',
+     *     url: 'https://cloud.langfuse.com/api/public/otlp/v1/traces',
+     *     headers: { 'Authorization': 'Basic xxx' }
+     *   }
+     * });
+     *
+     * // Multiple exporters
+     * createExpressServer({
+     *   createAgent,
+     *   observability: [
+     *     { type: 'console' },
+     *     { type: 'otlp', url: 'http://localhost:4318/v1/traces' }
+     *   ]
+     * });
+     */
+    observability?: _cloudbase_agent_observability_server.ObservabilityConfig | _cloudbase_agent_observability_server.ObservabilityConfig[];
 }
 interface IRun extends ICreateServer {
     port?: number | string;
 }
 interface ICreateExpressRoutes extends Omit<ICreateServer, "cors"> {
     express: Express;
+    observability?: ICreateServer['observability'];
 }
 declare function run(props: IRun): void;
 declare function createExpressServer(props: ICreateServer): Express;
-declare function createExpressRoutes({ createAgent, basePath: _basePath, express, useAGUI: _useAGUI, aguiOptions, }: ICreateExpressRoutes): expressLib.Express;
+declare function createExpressRoutes({ createAgent, basePath: _basePath, express, useAGUI: _useAGUI, aguiOptions, logger: _logger, observability, }: ICreateExpressRoutes): expressLib.Express;
 interface AGUIOptions {
     runtimeOptions?: Partial<CopilotRuntimeOptions>;
     endpointOptions?: Partial<CreateCopilotRuntimeServerOptions>;
@@ -86,10 +137,21 @@ declare function handler$1(input: RunAgentInput, agent: AbstractAgent): Repeater
     rawEvent?: any;
 }, any, unknown>;
 
-declare function createServerAdapter$1(createAgent: AgentCreator): _whatwg_node_server.ServerAdapter<{}, _whatwg_node_server.ServerAdapterBaseObject<{}, (request: Request) => Promise<Response>>>;
+/**
+ * Options for createServerAdapter
+ */
+interface CreateServerAdapterOptions {
+    /**
+     * Logger instance for structured logging.
+     * @default noopLogger (silent)
+     */
+    logger?: Logger;
+}
+declare function createServerAdapter$1(createAgent: AgentCreator, options?: CreateServerAdapterOptions): _whatwg_node_server.ServerAdapter<{}, _whatwg_node_server.ServerAdapterBaseObject<{}, (request: Request) => Promise<Response>>>;
 
+type index$3_CreateServerAdapterOptions = CreateServerAdapterOptions;
 declare namespace index$3 {
-  export { createServerAdapter$1 as createServerAdapter, handler$1 as handler };
+  export { type index$3_CreateServerAdapterOptions as CreateServerAdapterOptions, createServerAdapter$1 as createServerAdapter, handler$1 as handler };
 }
 
 declare const serverAdapter: _whatwg_node_server.ServerAdapter<{}, _whatwg_node_server.ServerAdapterBaseObject<{}, () => Response>>;
@@ -119,4 +181,63 @@ declare namespace index {
   export { index$2 as healthz, index$1 as openai, index$4 as sendMessage, index$3 as sendMessageAGUI };
 }
 
-export { type AgentCreator, type AgentCreatorContext, index as agui, createExpressRoutes, createExpressServer, run };
+/**
+ * Generates a unique request ID for tracing.
+ *
+ * The request ID is used to:
+ * 1. Correlate all logs from a single request
+ * 2. Include in error responses for debugging
+ * 3. Trace requests across distributed systems
+ *
+ * @param prefix - Optional prefix for the request ID (default: 'req')
+ * @returns A unique request ID string
+ *
+ * @example
+ * generateRequestId() // => 'req-a1b2c3d4-e5f6-7890-abcd-ef1234567890'
+ * generateRequestId('agui') // => 'agui-a1b2c3d4-e5f6-7890-abcd-ef1234567890'
+ */
+declare function generateRequestId(prefix?: string): string;
+/**
+ * Extracts request ID from incoming request headers.
+ * Supports common request ID header conventions.
+ *
+ * Header priority (first found wins):
+ * 1. x-request-id
+ * 2. x-correlation-id
+ * 3. x-trace-id
+ *
+ * @param headers - Request headers (Headers object or plain object)
+ * @returns The request ID from headers, or undefined if not found
+ */
+declare function extractRequestId(headers: Headers | Record<string, string | string[] | undefined>): string | undefined;
+/**
+ * Gets or generates a request ID.
+ * First tries to extract from headers, then generates a new one.
+ *
+ * @param headers - Request headers
+ * @param prefix - Prefix for generated IDs (default: 'req')
+ * @returns Request ID (either extracted or generated)
+ */
+declare function getOrGenerateRequestId(headers: Headers | Record<string, string | string[] | undefined>, prefix?: string): string;
+
+/**
+ * AG-Kit Error Handling
+ *
+ * Error handling follows these rules:
+ * 1. Pre-stream errors: Return JSON `{error: {code, message}, requestId}`
+ * 2. In-stream errors: Emit RunError event `{type: "RUN_ERROR", code, message}`
+ *
+ * Adapters can:
+ * - Directly emit RunError events into the stream
+ * - Throw errors with a `code` property (server extracts and converts to RunError)
+ * - Throw other errors (server uses fallback INTERNAL_ERROR code)
+ */
+declare const ErrorCode: {
+    /** Invalid request format or parameters (400) */
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+    /** Internal server error (500) */
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+export { type AgentCreator, type AgentCreatorContext, ErrorCode, type ErrorCodeType, index as agui, createExpressRoutes, createExpressServer, extractRequestId, generateRequestId, getOrGenerateRequestId, run };

package/dist/index.js

@@ -29,9 +29,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ErrorCode: () => ErrorCode,
   agui: () => agui_exports,
+  createConsoleLogger: () => import_agent_shared2.createConsoleLogger,
   createExpressRoutes: () => createExpressRoutes,
   createExpressServer: () => createExpressServer,
+  extractRequestId: () => extractRequestId,
+  generateRequestId: () => generateRequestId,
+  getOrGenerateRequestId: () => getOrGenerateRequestId,
+  isErrorWithCode: () => import_agent_shared3.isErrorWithCode,
+  noopLogger: () => import_agent_shared2.noopLogger,
   run: () => run
 });
 module.exports = __toCommonJS(index_exports);
@@ -231,9 +238,199 @@ function handler2(input, agent) {
 // src/agui/sendMessageAGUI/server.ts
 var import_server3 = require("@whatwg-node/server");
 var import_client2 = require("@ag-ui/client");
+var import_uuid3 = require("uuid");
+
+// src/logger/index.ts
+var import_agent_shared2 = require("@cloudbase/agent-shared");
+
+// src/logger/request-id.ts
 var import_uuid2 = require("uuid");
-function createServerAdapter2(createAgent) {
+function generateRequestId(prefix = "req") {
+  return `${prefix}-${(0, import_uuid2.v4)()}`;
+}
+function extractRequestId(headers) {
+  const headerNames = ["x-request-id", "x-correlation-id", "x-trace-id"];
+  for (const name of headerNames) {
+    let value;
+    if (headers instanceof Headers) {
+      value = headers.get(name) || void 0;
+    } else {
+      const raw = headers[name];
+      value = Array.isArray(raw) ? raw[0] : raw;
+    }
+    if (value) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function getOrGenerateRequestId(headers, prefix = "req") {
+  return extractRequestId(headers) || generateRequestId(prefix);
+}
+
+// src/agui/sendMessageAGUI/schemas.ts
+var import_v4 = require("zod/v4");
+var FunctionCallSchema = import_v4.z.object({
+  name: import_v4.z.string(),
+  arguments: import_v4.z.string()
+});
+var ToolCallSchema = import_v4.z.object({
+  id: import_v4.z.string(),
+  type: import_v4.z.literal("function"),
+  function: FunctionCallSchema
+});
+var ToolSchema = import_v4.z.object({
+  name: import_v4.z.string(),
+  description: import_v4.z.string(),
+  parameters: import_v4.z.any()
+});
+var TextInputContentSchema = import_v4.z.object({
+  type: import_v4.z.literal("text"),
+  text: import_v4.z.string()
+});
+var BinaryInputContentObjectSchema = import_v4.z.object({
+  type: import_v4.z.literal("binary"),
+  mimeType: import_v4.z.string(),
+  id: import_v4.z.string().optional(),
+  url: import_v4.z.string().optional(),
+  data: import_v4.z.string().optional(),
+  filename: import_v4.z.string().optional()
+});
+var ensureBinaryPayload = (value, ctx) => {
+  if (!value.id && !value.url && !value.data) {
+    ctx.addIssue({
+      code: import_v4.z.ZodIssueCode.custom,
+      message: "BinaryInputContent requires at least one of id, url, or data.",
+      path: ["id"]
+    });
+  }
+};
+var BinaryInputContentSchema = BinaryInputContentObjectSchema.superRefine((value, ctx) => {
+  ensureBinaryPayload(value, ctx);
+});
+var InputContentBaseSchema = import_v4.z.discriminatedUnion("type", [
+  TextInputContentSchema,
+  BinaryInputContentObjectSchema
+]);
+var InputContentSchema = InputContentBaseSchema.superRefine(
+  (value, ctx) => {
+    if (value.type === "binary") {
+      ensureBinaryPayload(value, ctx);
+    }
+  }
+);
+var BaseMessageSchema = import_v4.z.object({
+  id: import_v4.z.string(),
+  role: import_v4.z.string(),
+  content: import_v4.z.string().optional(),
+  name: import_v4.z.string().optional()
+});
+var DeveloperMessageSchema = BaseMessageSchema.extend({
+  role: import_v4.z.literal("developer"),
+  content: import_v4.z.string()
+});
+var SystemMessageSchema = BaseMessageSchema.extend({
+  role: import_v4.z.literal("system"),
+  content: import_v4.z.string()
+});
+var AssistantMessageSchema = BaseMessageSchema.extend({
+  role: import_v4.z.literal("assistant"),
+  content: import_v4.z.string().optional(),
+  toolCalls: import_v4.z.array(ToolCallSchema).optional()
+});
+var UserMessageSchema = BaseMessageSchema.extend({
+  role: import_v4.z.literal("user"),
+  content: import_v4.z.union([import_v4.z.string(), import_v4.z.array(InputContentSchema)])
+});
+var ToolMessageSchema = import_v4.z.object({
+  id: import_v4.z.string(),
+  content: import_v4.z.string(),
+  role: import_v4.z.literal("tool"),
+  toolCallId: import_v4.z.string(),
+  error: import_v4.z.string().optional()
+});
+var ActivityMessageSchema = import_v4.z.object({
+  id: import_v4.z.string(),
+  role: import_v4.z.literal("activity"),
+  activityType: import_v4.z.string(),
+  content: import_v4.z.record(import_v4.z.string(), import_v4.z.any())
+});
+var MessageSchema = import_v4.z.discriminatedUnion("role", [
+  DeveloperMessageSchema,
+  SystemMessageSchema,
+  AssistantMessageSchema,
+  UserMessageSchema,
+  ToolMessageSchema,
+  ActivityMessageSchema
+]);
+var ContextSchema = import_v4.z.object({
+  description: import_v4.z.string(),
+  value: import_v4.z.string()
+});
+var ServerRunAgentInputSchema = import_v4.z.object({
+  threadId: import_v4.z.string().optional(),
+  // Modified: optional instead of required
+  runId: import_v4.z.string(),
+  parentRunId: import_v4.z.string().optional(),
+  state: import_v4.z.any(),
+  messages: import_v4.z.array(MessageSchema),
+  tools: import_v4.z.array(ToolSchema),
+  context: import_v4.z.array(ContextSchema),
+  forwardedProps: import_v4.z.any()
+});
+
+// src/errors/index.ts
+var import_agent_shared3 = require("@cloudbase/agent-shared");
+var ErrorCode = {
+  /** Invalid request format or parameters (400) */
+  INVALID_REQUEST: "INVALID_REQUEST",
+  /** Internal server error (500) */
+  INTERNAL_ERROR: "INTERNAL_ERROR"
+};
+
+// src/agui/sendMessageAGUI/server.ts
+var startObservation;
+var setupObservability;
+var observabilityLoadAttempted = false;
+async function loadObservability() {
+  if (!observabilityLoadAttempted) {
+    observabilityLoadAttempted = true;
+    try {
+      const obs = await import("@cloudbase/agent-observability");
+      const obsServer = await import("@cloudbase/agent-observability/server");
+      startObservation = obs.startObservation;
+      setupObservability = obsServer.setupObservability;
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+  return !!startObservation;
+}
+async function ensureObservabilityReady() {
+  if (!setupObservability) return false;
+  try {
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error("Observability setup timeout")), 2e3);
+    });
+    await Promise.race([
+      setupObservability(),
+      timeoutPromise
+    ]);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+function createServerAdapter2(createAgent, options) {
+  var _a;
+  const { logger: parentLogger = import_agent_shared2.noopLogger } = options ?? {};
+  const adapterLogger = ((_a = parentLogger.child) == null ? void 0 : _a.call(parentLogger, { component: "sendMessageAGUI" })) ?? parentLogger;
   return (0, import_server3.createServerAdapter)(async (request) => {
+    var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+    const requestId = getOrGenerateRequestId(request.headers, "agui");
+    const logger = ((_a2 = adapterLogger.child) == null ? void 0 : _a2.call(adapterLogger, { requestId })) ?? adapterLogger;
+    (_b = logger.info) == null ? void 0 : _b.call(logger, "Request received");
     const inputRes = await safeAsync(async () => {
       const rawInput = await request.json();
       const inputWithDefaults = {
@@ -242,16 +439,24 @@ function createServerAdapter2(createAgent) {
         state: {},
         forwardedProps: {},
         ...rawInput,
-        runId: typeof rawInput.runId === "string" && rawInput.runId ? rawInput.runId : (0, import_uuid2.v4)()
+        runId: typeof rawInput.runId === "string" && rawInput.runId ? rawInput.runId : (0, import_uuid3.v4)()
       };
-      return import_client2.RunAgentInputSchema.parse(inputWithDefaults);
+      return ServerRunAgentInputSchema.parse(inputWithDefaults);
     });
     if ("error" in inputRes) {
       const { error } = inputRes;
-      console.error("[AGUI Server] Pre-stream error:", error);
+      (_c = logger.warn) == null ? void 0 : _c.call(
+        logger,
+        { err: error instanceof Error ? error.message : String(error) },
+        "Input validation failed"
+      );
       return new Response(
         JSON.stringify({
-          error: error instanceof Error ? error.message : String(error)
+          error: {
+            code: ErrorCode.INVALID_REQUEST,
+            message: error instanceof Error ? error.message : String(error)
+          },
+          requestId
         }),
         {
           status: 400,
@@ -259,8 +464,25 @@ function createServerAdapter2(createAgent) {
         }
       );
     }
+    const input = inputRes.result;
+    const lastUserMessage = input.messages.filter((m) => m.role === "user").pop();
+    (_f = logger.debug) == null ? void 0 : _f.call(
+      logger,
+      {
+        runId: input.runId,
+        threadId: input.threadId,
+        messageCount: input.messages.length,
+        toolCount: ((_d = input.tools) == null ? void 0 : _d.length) ?? 0,
+        tools: (_e = input.tools) == null ? void 0 : _e.map((t) => t.name),
+        lastUserMessage: typeof (lastUserMessage == null ? void 0 : lastUserMessage.content) === "string" ? lastUserMessage.content.slice(0, 200) : void 0
+      },
+      "Input validated"
+    );
+    (_g = logger.trace) == null ? void 0 : _g.call(logger, { input }, "Full request input");
     const createAgentRes = await safeAsync(async () => {
-      const res = await Promise.resolve(createAgent({ request }));
+      const res = await Promise.resolve(
+        createAgent({ request, logger, requestId })
+      );
       return {
         cleanup: res.cleanup,
         agent: "toAGUIAgent" in res.agent ? res.agent.toAGUIAgent() : res.agent
@@ -268,10 +490,16 @@ function createServerAdapter2(createAgent) {
     });
     if ("error" in createAgentRes) {
       const { error } = createAgentRes;
-      console.error("[AGUI Server] Pre-stream error:", error);
+      (_h = logger.error) == null ? void 0 : _h.call(logger, { err: error }, "Agent creation failed");
+      const errorCode = (0, import_agent_shared3.isErrorWithCode)(error) ? error.code : ErrorCode.INTERNAL_ERROR;
+      const errorMessage = error instanceof Error ? error.message : String(error);
       return new Response(
         JSON.stringify({
-          error: error instanceof Error ? error.message : String(error)
+          error: {
+            code: errorCode,
+            message: errorMessage
+          },
+          requestId
         }),
         {
           status: 500,
@@ -279,38 +507,116 @@ function createServerAdapter2(createAgent) {
         }
       );
     }
-    const events = handler2(inputRes.result, createAgentRes.result.agent);
-    let heartbeat;
+    const hasObservability = await loadObservability();
+    let serverSpan = null;
+    let serverContextData = null;
+    if (hasObservability && startObservation) {
+      try {
+        const isReady = await ensureObservabilityReady();
+        if (isReady) {
+          serverSpan = startObservation(
+            "AG-UI.Server",
+            {
+              "http.method": request.method,
+              "http.url": request.url,
+              "http.host": request.headers.get("host") || "unknown",
+              "http.user_agent": request.headers.get("user-agent") || "unknown",
+              "agui.thread_id": inputRes.result.threadId,
+              "agui.run_id": inputRes.result.runId
+            },
+            { asType: "span" }
+          );
+          const spanContext = serverSpan.otelSpan.spanContext();
+          serverContextData = {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+            traceFlags: spanContext.traceFlags
+          };
+          inputRes.result.forwardedProps = {
+            ...inputRes.result.forwardedProps,
+            __agui_server_context: serverContextData
+          };
+          (_i = logger.debug) == null ? void 0 : _i.call(logger, "\u2713 Server span created:", {
+            traceId: serverContextData.traceId,
+            spanId: serverContextData.spanId
+          });
+        } else {
+          (_j = logger.debug) == null ? void 0 : _j.call(logger, "Observability not ready, skipping span creation");
+        }
+      } catch (e) {
+        (_k = logger.debug) == null ? void 0 : _k.call(logger, "Failed to create server span:", e);
+      }
+    }
     let cleanupCalled = false;
     const safeCleanup = () => {
-      var _a, _b;
+      var _a3, _b2, _c2;
       if (!cleanupCalled) {
         cleanupCalled = true;
         try {
-          (_b = (_a = createAgentRes.result).cleanup) == null ? void 0 : _b.call(_a);
+          (_b2 = (_a3 = createAgentRes.result).cleanup) == null ? void 0 : _b2.call(_a3);
         } catch (e) {
-          console.error(e);
+          (_c2 = logger.error) == null ? void 0 : _c2.call(logger, { err: e }, "Cleanup error");
         }
       }
     };
+    const eventsResult = safe(
+      () => handler2(
+        inputRes.result,
+        createAgentRes.result.agent
+      )
+    );
+    if ("error" in eventsResult) {
+      const { error } = eventsResult;
+      (_l = logger.error) == null ? void 0 : _l.call(logger, { err: error }, "Run agent failed");
+      const errorCode = (0, import_agent_shared3.isErrorWithCode)(error) ? error.code : ErrorCode.INTERNAL_ERROR;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return new Response(
+        JSON.stringify({
+          error: {
+            code: errorCode,
+            message: errorMessage
+          },
+          requestId
+        }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    }
+    const { result: events } = eventsResult;
+    let heartbeat;
     const stream = new ReadableStream({
       async start(controller) {
+        var _a3, _b2, _c2, _d2, _e2;
         const encoder = new TextEncoder();
         heartbeat = setInterval(() => {
           controller.enqueue(encoder.encode(":ping\n\n"));
         }, 15 * 1e3);
+        let eventCount = 0;
         try {
           for await (const event of events) {
+            eventCount++;
+            (_a3 = logger.debug) == null ? void 0 : _a3.call(
+              logger,
+              { eventType: event.type, eventCount },
+              "Emitting SSE event"
+            );
+            (_b2 = logger.trace) == null ? void 0 : _b2.call(logger, { aguiEvent: event }, "SSE event content");
             const sseChunk = `data: ${JSON.stringify(event)}
 
 `;
             controller.enqueue(encoder.encode(sseChunk));
           }
+          (_c2 = logger.info) == null ? void 0 : _c2.call(logger, { eventCount }, "Request completed");
         } catch (error) {
-          console.error("[AGUI Server] Stream error:", error);
+          (_d2 = logger.error) == null ? void 0 : _d2.call(logger, { err: error }, "Stream error");
+          const errorCode = (0, import_agent_shared3.isErrorWithCode)(error) ? error.code : ErrorCode.INTERNAL_ERROR;
+          const errorMessage = error instanceof Error ? error.message : String(error);
           const errorEvent = {
             type: import_client2.EventType.RUN_ERROR,
-            message: error instanceof Error ? error.message : String(error)
+            code: errorCode,
+            message: errorMessage
           };
           controller.enqueue(
             encoder.encode(`data: ${JSON.stringify(errorEvent)}
@@ -321,11 +627,21 @@ function createServerAdapter2(createAgent) {
           if (heartbeat) clearInterval(heartbeat);
           controller.close();
           safeCleanup();
+          if (serverSpan) {
+            serverSpan.end();
+            (_e2 = logger.debug) == null ? void 0 : _e2.call(logger, "\u2713 Server span ended");
+          }
         }
       },
       cancel() {
+        var _a3, _b2;
+        (_a3 = logger.info) == null ? void 0 : _a3.call(logger, "Request cancelled by client");
         if (heartbeat) clearInterval(heartbeat);
         safeCleanup();
+        if (serverSpan) {
+          serverSpan.end();
+          (_b2 = logger.debug) == null ? void 0 : _b2.call(logger, "\u2713 Server span ended (cancelled)");
+        }
       }
     });
     const headers = new Headers({
@@ -345,6 +661,15 @@ async function safeAsync(fn) {
     return { error };
   }
 }
+function safe(fn) {
+  try {
+    return {
+      result: fn()
+    };
+  } catch (error) {
+    return { error };
+  }
+}
 
 // src/agui/healthz/index.ts
 var healthz_exports = {};
@@ -362,7 +687,7 @@ __export(openai_exports, {
 });
 
 // src/agui/openai/handler.ts
-var import_uuid3 = require("uuid");
+var import_uuid4 = require("uuid");
 var import_repeater3 = require("@repeaterjs/repeater");
 function handler3(input, agent) {
   var _a;
@@ -374,12 +699,12 @@ function handler3(input, agent) {
         description: tool.function.description,
         parameters: tool.function.parameters
       })),
-      conversationId: (0, import_uuid3.v4)()
+      conversationId: (0, import_uuid4.v4)()
     },
     agent
   );
   return new import_repeater3.Repeater(async (push, stop) => {
-    const id = (0, import_uuid3.v4)();
+    const id = (0, import_uuid4.v4)();
     let tools = [];
     let lastWithToolCall = false;
     let maxIndex = 0;
@@ -543,6 +868,13 @@ var import_cors = __toESM(require("cors"));
 var import_async_hooks = require("async_hooks");
 var import_server8 = require("@whatwg-node/server");
 var DefaultFetchAPI = __toESM(require("@whatwg-node/fetch"));
+async function setupObservabilityIfAvailable(configs) {
+  try {
+    const { setupObservability: setupObservability2 } = await import("@cloudbase/agent-observability/server");
+    await setupObservability2(configs);
+  } catch (error) {
+  }
+}
 var preparedAgentStorage = new import_async_hooks.AsyncLocalStorage();
 function agentCloneFn() {
   const preparedAgent = preparedAgentStorage.getStore();
@@ -576,16 +908,27 @@ function createExpressRoutes({
   basePath: _basePath,
   express,
   useAGUI: _useAGUI,
-  aguiOptions
+  aguiOptions,
+  logger: _logger,
+  observability
 }) {
+  var _a, _b, _c;
   const useAGUI = _useAGUI ?? true;
+  const logger = _logger ?? import_agent_shared2.noopLogger;
   const basePath = _basePath ?? (process.env.TENCENTCLOUD_RUNENV === "SCF" ? "/v1/aibot/bots/:agentId/" : "/");
-  const sendMessageServerAdapter = useAGUI ? sendMessageAGUI_exports.createServerAdapter(createAgent) : sendMessage_exports.createServerAdapter(createAgent);
+  const serverLogger = ((_a = logger.child) == null ? void 0 : _a.call(logger, { component: "server" })) ?? logger;
+  (_b = serverLogger.debug) == null ? void 0 : _b.call(serverLogger, { basePath, useAGUI }, "Initializing server routes");
+  if (observability) {
+    setupObservabilityIfAvailable(observability).catch(() => {
+    });
+  }
+  const sendMessageServerAdapter = useAGUI ? sendMessageAGUI_exports.createServerAdapter(createAgent, { logger: serverLogger }) : sendMessage_exports.createServerAdapter(createAgent);
   if (useAGUI) {
     createAGUIRoute({
       basePath,
       express,
       createAgent,
+      logger: serverLogger,
       ...aguiOptions || {}
     });
   }
@@ -594,6 +937,7 @@ function createExpressRoutes({
   express.use(`${basePath}send-message`, sendMessageServerAdapter);
   express.use(`${basePath}healthz`, healthzServerAdapter);
   express.use(`${basePath}chat/completions`, openaiServerAdapter);
+  (_c = serverLogger.info) == null ? void 0 : _c.call(serverLogger, { basePath }, "Server routes initialized");
   return express;
 }
 var AGUIRpcHandlerPromise = null;
@@ -602,11 +946,13 @@ function getAGUIRpcHandler({
   runtimeOptions,
   basePath,
   endpointOptions,
-  request
+  request,
+  logger,
+  requestId
 }) {
   if (AGUIRpcHandlerPromise) return AGUIRpcHandlerPromise;
   AGUIRpcHandlerPromise = (async () => {
-    const { agent } = await createAgent({ request });
+    const { agent } = await createAgent({ request, logger, requestId });
     const templateAgent = "toAGUIAgent" in agent ? agent.toAGUIAgent() : agent;
     templateAgent.clone = agentCloneFn;
     const runtime = new import_runtime.CopilotRuntime({
@@ -629,12 +975,21 @@ function createAGUIRoute({
   basePath,
   createAgent,
   runtimeOptions,
-  endpointOptions
+  endpointOptions,
+  logger
 }) {
+  var _a;
+  const routeLogger = ((_a = logger.child) == null ? void 0 : _a.call(logger, { component: "agui-route" })) ?? logger;
   express.post(`${basePath}agui`, import_express.default.json(), async (req, res) => {
+    var _a2, _b;
     const webRequest = (0, import_server8.normalizeNodeRequest)(req, DefaultFetchAPI);
+    const requestId = getOrGenerateRequestId(webRequest.headers, "agui");
+    const requestLogger = ((_a2 = routeLogger.child) == null ? void 0 : _a2.call(routeLogger, { requestId })) ?? routeLogger;
+    (_b = requestLogger.info) == null ? void 0 : _b.call(requestLogger, { path: `${basePath}agui` }, "Request received");
     const { agent: rawAgent, cleanup } = await createAgent({
-      request: webRequest
+      request: webRequest,
+      logger: requestLogger,
+      requestId
     });
     const preparedAgent = "toAGUIAgent" in rawAgent ? rawAgent.toAGUIAgent() : rawAgent;
     preparedAgent.clone = agentCloneFn;
@@ -643,7 +998,9 @@ function createAGUIRoute({
       basePath,
       runtimeOptions,
       endpointOptions,
-      request: webRequest
+      request: webRequest,
+      logger: requestLogger,
+      requestId
     });
     preparedAgentStorage.run(preparedAgent, () => {
       rpcHandler(req, res);
@@ -658,8 +1015,15 @@ function isCorsOptions(cors2) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ErrorCode,
   agui,
+  createConsoleLogger,
   createExpressRoutes,
   createExpressServer,
+  extractRequestId,
+  generateRequestId,
+  getOrGenerateRequestId,
+  isErrorWithCode,
+  noopLogger,
   run
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/agent-server",
-  "version": "1.0.1-alpha.7",
+  "version": "1.0.1-alpha.9",
   "main": "dist/index.js",
   "files": [
     "dist/",
@@ -20,13 +20,19 @@
     "express": "^5.1.0",
     "openai": "6.3.0",
     "uuid": "^10.0.0",
-    "zod": "^4.1.12",
-    "@cloudbase/agent-shared": "^1.0.1-alpha.7"
+    "@cloudbase/agent-shared": "^1.0.1-alpha.9"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "optionalDependencies": {
+    "@cloudbase/agent-observability": "1.0.1-alpha.9"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
-    "tsup": "^8.5.0"
+    "tsup": "^8.5.0",
+    "zod": "^4.0.0"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",