Merge branch 'main' into feat/responses_api_2

Author: zakahan

.gitleaks.toml

@@ -73,4 +73,4 @@ description = "Empty environment variables with KEY pattern"
 regex = '''os\.environ\[".*?KEY"\]\s*=\s*".+"'''
 
 [allowlist]
-paths = ["requirements.txt", "tests"]
+paths = ["requirements.txt", "tests", "veadk/realtime/client.py", "veadk/realtime/live.py"]

config.yaml.full

@@ -142,6 +142,11 @@ database:
   mem0:
     base_url: # default "https://api.mem0.ai/v1", using full https url including port
     api_key:  #api_key
+  tos_vector:
+    endpoint: tosvectors-cn-beijing.volces.com # default Volcengine TOS Vector endpoint
+    region: cn-beijing                  # default Volcengine TOS Vector region
+    bucket:
+    account_id:
 
 
 

docs/docs/agent/agent.md

@@ -17,7 +17,7 @@
 
 在代码中直接定义智能体是最常见且最灵活的方式。此方法便于动态调整参数、集成外部模块并进行单元测试。您可以创建一个最简单的 Agent，无需额外设置。**Agent 缺省属性将来自环境变量或默认值。**如下代码实现了一个最简化的 Agent 定义与运行：
 
-=== "代码"
+=== "Python"
 
     ```python title="agent.py" linenums="1" hl_lines="5"
     import asyncio
@@ -31,6 +31,66 @@
     print(response)
     ```
 
+=== "Golang"
+
+    ```golang title="agent.go" linenums="1" hl_lines="18"
+    package main
+
+    import (
+        "context"
+        "fmt"
+    
+        "github.com/google/uuid"
+        _ "github.com/volcengine/veadk-go/agent"
+        veagent "github.com/volcengine/veadk-go/agent/llmagent"
+        "google.golang.org/adk/agent"
+        "google.golang.org/adk/runner"
+        "google.golang.org/adk/session"
+        "google.golang.org/genai"
+    )
+    
+    func main() {
+        ctx := context.Background()
+        veAgent, err := veagent.New(&veagent.Config{})
+        if err != nil {
+            fmt.Printf("NewVeAgent failed: %v", err)
+            return
+        }
+    
+        appName := "veAgent_app"
+        userID := "user-1234"
+        sessionId := fmt.Sprintf("%s-%s", session.KeyPrefixTemp, uuid.NewString())
+        sessionService := session.InMemoryService()
+        agentRunner, err := runner.New(runner.Config{
+            AppName:        appName,
+            Agent:          veAgent,
+            SessionService: sessionService,
+        })
+        if err != nil {
+            fmt.Printf("New runner error:%v", err)
+            return
+        }
+    
+        _, err = sessionService.Create(ctx, &session.CreateRequest{
+            AppName:   appName,
+            UserID:    userID,
+            SessionID: sessionId,
+        })
+        if err != nil {
+            fmt.Printf("Create session error:%v", err)
+            return
+        }
+    
+        for event, err := range agentRunner.Run(ctx, userID, sessionId, genai.NewContentFromText("你好", genai.RoleUser), agent.RunConfig{StreamingMode: agent.StreamingModeNone}) {
+            if err != nil {
+                fmt.Printf("got unexpected error: %v", err)
+            }
+            fmt.Printf("got event: %s\n", event.Content.Parts[0].Text)
+        }
+    }
+    ```
+
+
 === "所需环境变量"
 
     环境变量列表：
@@ -50,34 +110,72 @@
 
 您也可以通过以下方式设置更多 Agent 元数据信息：
 
-```python title="agent.py" linenums="1" hl_lines="4-6"
-from veadk import Agent, Runner
+=== "Python"
+
+    ```python title="agent.py" linenums="1" hl_lines="4-6"
+    from veadk import Agent, Runner
+    
+    root_agent = Agent(
+        name="life_assistant",
+        description="生活助手",
+        instruction="你是一个生活助手，你可以回答用户的问题。",
+    )
+    ```
+
+=== "Golang"
+
+    ```golang title="agent.go" linenums="1" hl_lines="2-4"
+    cfg := &veagent.Config{}
+	cfg.Name = "life_assistant"
+	cfg.Description = "生活助手"
+	cfg.Instruction = "你是一个生活助手，你可以回答用户的问题。"
+
+	veAgent, err := veagent.New(cfg)
+	if err != nil {
+		fmt.Printf("NewVeAgent failed: %v", err)
+		return
+	}
+    ```
 
-root_agent = Agent(
-    name="life_assistant",
-    description="生活助手",
-    instruction="你是一个生活助手，你可以回答用户的问题。",
-)
-```
 
 其中，`name` 代表 Agent 的名称，`description` 是对 Agent 功能的简单描述（在Agent Tree中唯一标识某个Agent），`instruction` 是 Agent 的系统提示词，用于定义其行为和响应风格。
 
 #### 使用不同模型
 
 如果您想使用本地模型或其他提供商的模型，可以在初始化时指定模型相关配置：
 
-```python title="agent.py" linenums="1" hl_lines="4-7"
-from veadk import Agent
+=== "Python"
 
-agent = Agent(
-    model_provider="...",
-    model_name="...",
-    model_api_key="...",
-    model_api_base="..."
-)
-```
+    ```python title="agent.py" linenums="1" hl_lines="4-7"
+    from veadk import Agent
+    
+    agent = Agent(
+        model_provider="...",
+        model_name="...",
+        model_api_key="...",
+        model_api_base="..."
+    )
+    ```
+
+=== "Golang"
+
+    ```golang title="agent.go" linenums="1" hl_lines="2-4"
+    cfg := &veagent.Config{
+		ModelName: "...",
+		ModelAPIBase: "...",
+		ModelAPIKey: "...",
+	}
+    
+    veAgent, err := veagent.New(cfg)
+	if err != nil {
+		fmt.Printf("NewVeAgent failed: %v", err)
+		return
+	}
+    ```
 
-由于 VeADK 的 Agent 基于 [LiteLLM]() 实现，因此您可以使用 LiteLLM 支持的所有模型提供商。您可以查看 [LiteLLM 支持的模型提供商列表](https://docs.litellm.ai/docs/providers)来设置 `model_provider` 参数。
+由于 python VeADK 的 Agent 基于 [LiteLLM]() 实现，因此您可以使用 LiteLLM 支持的所有模型提供商。您可以查看 [LiteLLM 支持的模型提供商列表](https://docs.litellm.ai/docs/providers)来设置 `model_provider` 参数。
+
+golang 暂不支持 LiteLLM，因此 VeADK 的 Agent 基于 OpenAI 实现，因此您可以使用所有支持OpenAI协议的模型。
 
 #### 设置模型客户端
 
@@ -98,20 +196,46 @@ agent = Agent(model=llm)
 
 此外，您还可以根据[火山引擎方舟大模型平台](https://www.volcengine.com/product/ark)的能力，指定一些[额外选项](https://www.volcengine.com/docs/82379/1494384?lang=zh)，例如您可以禁用豆包 1.6 系列模型的思考能力，以实现更加快速的响应：
 
-```python title="agent.py" linenums="1" hl_lines="7"
-import asyncio
+=== "Python"
 
-from veadk import Agent, Runner
+    ```python title="agent.py" linenums="1" hl_lines="7"
+    import asyncio
+    
+    from veadk import Agent, Runner
+    
+    agent = Agent(
+        model_name="doubao-seed-1.6-250615",
+        model_extra_config={"extra_body": {"thinking": {"type": "disabled"}}},
+    )
+    runner = Runner(agent=agent)
+    
+    response = asyncio.run(runner.run(messages="hi!"))
+    print(response)
+    ```
 
-agent = Agent(
-    model_name="doubao-seed-1.6-250615",
-    model_extra_config={"extra_body": {"thinking": {"type": "disabled"}}},
-)
-runner = Runner(agent=agent)
+=== "Golang"
+
+    ```golang title="agent.go" linenums="1" hl_lines="6-14"
+    import (
+        _ "github.com/volcengine/veadk-go/agent"
+        veagent "github.com/volcengine/veadk-go/agent/llmagent"
+    )
+    
+    veAgent, err := veagent.New(&veagent.Config{
+		ModelExtraConfig: map[string]any{
+			"extra_body": map[string]any{
+				"thinking": map[string]string{
+					"type": "disabled",
+				},
+			},
+		},
+	})
+	if err != nil {
+		fmt.Printf("NewVeAgent failed: %v", err)
+		return
+	}
+    ```
 
-response = asyncio.run(runner.run(messages="hi!"))
-print(response)
-```
 
 ### 通过配置文件
 

docs/docs/agent/agents.md

@@ -53,12 +53,19 @@ graph LR
     H --> I["最终回答: 根据北京天气给出穿衣建议"]
 ```
 
-=== "代码"
+=== "Python"
 
     ```python
     --8<-- "examples/agent/agents/llm_agent.py"
     ```
 
+=== "Golang"
+
+    ```python
+    --8<-- "examples/agent/agents/llm_agent.go"
+    ```
+
+
 === "环境变量"
 
     环境变量列表：

docs/docs/agent/prompt.md

@@ -0,0 +1,49 @@
+# Prompt 管理
+
+在实际生产过程中，Prompt 需要进行版本管理与动态下发，VeADK 提供了 Prompt 管理模块，用户可以通过 Prompt 管理功能来进行 Prompt 的模板化与热更新，在运行时动态切换 Prompt 版本。
+
+## CozeLoop 提示词管理
+
+在使用 CozeLoop 进行提示词管理前，您需要安装 Python 版本的 `cozeloop` SDK：
+
+```bash
+pip install cozeloop
+```
+
+您可以通过 CozeLoop 云端提示词管理功能来对接您的 Agent 系统提示词。例如：
+
+```python title="agent.py" linenums="1" hl_lines="4 6-11 13"
+import asyncio
+
+from veadk import Agent, Runner
+from veadk.prompts.prompt_manager import CozeloopPromptManager
+
+prompt_manager = CozeloopPromptManager(
+    cozeloop_workspace_id="",   # CozeLoop workspace ID
+    cozeloop_token="",          # CozeLoop token
+    prompt_key="",    # CozeLoop 中创建的 Prompt Key
+    label="production",         # CozeLoop 中创建的 Prompt 标签
+)
+
+agent = Agent(name="test_prompt_mgr", prompt_manager=prompt_manager)
+
+runner = Runner(agent=agent)
+
+response = asyncio.run(runner.run(messages="你的任务是什么？"))
+print(response)
+```
+
+!!! note "提示"
+    CozeLoop 会在本地进行 Prompt 缓存，**更新时间为 1 分钟**。当获取 Prompt 失败时，会返回 VeADK 默认的 Agent 系统提示词。
+
+您可以在日志中看到，每次处理用户请求之前，都会执行 `CozeloopPromptManager` 中的 `get_prompt` 方法，来获取最新的 Prompt 模板内容。效果如下：
+
+![img](../assets/images/agents/cozeloop_prompt_mgr.png)
+
+更加详细的说明，请参考 [CozeLoop 提示词管理](https://loop.coze.cn/open/docs/cozeloop/what-is-prompt)。
+
+## 实现您自己的 Prompt Manager
+
+若您想实现更高阶的 Prompt 模板或变量组合，您可以继承 `PromptManager` 类，实现自定义的 Prompt 管理逻辑。
+
+在实现自定义 Prompt Manager 时，您需要实现 `get_prompt` 方法，该方法会在每次处理用户请求之前被调用，用于获取最新的 Prompt 模板内容。

docs/docs/assets/images/agents/cozeloop_prompt_mgr.png

@@ -86,8 +86,8 @@ A: 实现错误处理和重试逻辑。
 
 ## 相关资源
 
-- [Agent Identity 产品介绍](./1.agent-identity-intro.md)
-- [OAuth2 M2M 认证](./3.oauth2-m2m-outbound.md)
-- [OAuth2 USER_FEDERATION 认证](./4.oauth2-user-federation-outbound.md)
-- [Trusted MCP 认证](./trusted-mcp-outbound.md)
+- [Agent Identity 产品介绍](https://www.volcengine.com/docs/86848/2080920?lang=zh)
+- [API Key 认证](https://volcengine.github.io/veadk-python/auth/api-key-outbound/)
+- [OAuth2 USER_FEDERATION 认证](https://volcengine.github.io/veadk-python/auth/oauth2-user-federation-outbound/)
+- [Trusted MCP 认证](https://volcengine.github.io/veadk-python/auth/trusted-mcp-outbound/)
 - [Agent Identity API 参考](https://www.volcengine.com/docs/86848/1918752)