Merge pull request #186 from TencentCloudBase/feature/obser_coze

Feature/obser coze

Author: Formergg

httpfunctions/coze-python/.env.example

@@ -15,4 +15,7 @@ COZE_BOT_ID=your_bot_id_here
 # COZE_API_BASE=https://api.coze.cn
 
 # Optional: Debug mode (enable detailed logging)
-# DEBUG=true
+# DEBUG=true
+
+# Trace log to stdout (已通过代码配置启用，无需环境变量)
+# AUTO_TRACES_STDOUT=true

httpfunctions/coze-python/README.md

@@ -49,6 +49,9 @@ python -m pip install -r ./requirements.txt \
 ```bash
 COZE_API_TOKEN=your_api_token_here
 COZE_BOT_ID=your_bot_id_here
+
+# Trace log to stdout（可选）
+AUTO_TRACES_STDOUT=true
 ```
 
 **环境变量说明**：
@@ -398,3 +401,68 @@ A: 通过客户端请求的 `forwarded_props.parameters` 动态传递，它会
 **Q: 支持哪些 Coze API 功能？**
 A: 支持 Coze Chat V3 API 的所有功能，包括流式响应和推理内容。
 
+---
+
+## 可观测性配置
+
+本项目支持 OpenTelemetry 协议的可观测性（Observability）功能，可以追踪 Coze Agent 的执行链路（traces）并导出到控制台或 OTLP 后端（如 Langfuse、Jaeger 等）。
+
+### 启用方式
+
+本项目提供两种启用可观测性的方式：
+
+#### 方式一：环境变量（推荐用于部署环境）
+
+在 `.env` 文件中设置：
+
+```bash
+# 启用可观测性（设为 true、1、yes 均可启用，设为 false 或 0 则关闭）
+AUTO_TRACES_STDOUT=true
+```
+
+或在 CloudBase 云函数控制台的环境变量设置中，添加：
+
+| 变量名 | 值 |
+|--------|-----|
+| `AUTO_TRACES_STDOUT` | `true` |
+
+#### 方式二：代码配置（推荐用于开发调试）
+
+在 `app.py` 中修改 `AgentServiceApp` 的初始化：
+
+```python
+from cloudbase_agent.observability.server import ConsoleTraceConfig
+
+# 显式传入可观测性配置
+AgentServiceApp(observability=ConsoleTraceConfig()).run(lambda: {"agent": agent})
+```
+
+### 关闭可观测性
+
+如需关闭可观测性功能，可采用以下任一方式：
+
+**方式一：本地开发（.env 文件）**
+
+```bash
+# 关闭可观测性
+AUTO_TRACES_STDOUT=false
+```
+
+**方式二：云函数控制台（部署环境）**
+
+在 CloudBase 云函数控制台的环境变量设置中，添加：
+
+| 变量名 | 值 |
+|--------|-----|
+| `AUTO_TRACES_STDOUT` | `false` |
+
+**方式三：代码配置**
+
+```python
+AgentServiceApp(observability=None).run(lambda: {"agent": agent})
+```
+
+### 输出格式
+
+启用后， traces 将以 JSON 格式输出到 stdout，每行一个 span，便于使用 `grep`、`jq` 等工具分析。
+

httpfunctions/coze-python/agent.py

@@ -51,16 +51,19 @@ def create_jwt_request_preprocessor():
     
     Extracts user_id from JWT 'sub' field in Authorization header
     and writes to request.forwarded_props.user_id.
+    
+    Note: This is a middleware generator following the onion model.
     """
     from ag_ui.core import RunAgentInput
     from fastapi import Request
 
-    def jwt_preprocessor(request: RunAgentInput, http_context: Request) -> None:
+    def jwt_preprocessor(request: RunAgentInput, http_context: Request):
         user_id = extract_user_id_from_request(http_context)
         if user_id:
             if not request.forwarded_props:
                 request.forwarded_props = {}
             request.forwarded_props["user_id"] = user_id
+        yield  # Required for middleware generator pattern
 
     return jwt_preprocessor
 

httpfunctions/coze-python/app.py

@@ -1,23 +1,32 @@
 # -*- coding: utf-8 -*-
 """Coze Agent Application Entry Point."""
 
+import os
 import sys
 from dotenv import load_dotenv
 
 load_dotenv()
 
 from cloudbase_agent.server import AgentServiceApp
+from cloudbase_agent.observability.server import ConsoleTraceConfig
 from agent import build_coze_agent, create_jwt_request_preprocessor
 
 
+def is_observability_enabled():
+    value = os.environ.get("AUTO_TRACES_STDOUT", "").lower()
+    return value not in ("false", "0")
+
+
 def main():
     """Application entry point."""
     try:
         agent = build_coze_agent()
-        AgentServiceApp().run(
-            lambda: {"agent": agent},
-            request_preprocessor=create_jwt_request_preprocessor(),
-        )
+        
+        observability = ConsoleTraceConfig() if is_observability_enabled() else None
+        
+        app = AgentServiceApp(observability=observability)
+        app.use(create_jwt_request_preprocessor())
+        app.run(lambda: {"agent": agent})
     except ValueError as e:
         print(f"Configuration Error: {e}", file=sys.stderr)
         sys.exit(1)

httpfunctions/coze-python/requirements.txt

@@ -1,5 +1,6 @@
-cloudbase-agent-core==0.1.11
-cloudbase-agent-server==0.1.16
-cloudbase-agent-coze==0.1.17
+cloudbase-agent-core==0.1.12
+cloudbase-agent-server==0.1.21
+cloudbase-agent-coze==0.1.18
+cloudbase-agent-observability==0.1.2
 cozepy>=0.20.0
 python-dotenv>=1.2.1