From 18a00396a3861118323396f8aa849519b0bac1dd Mon Sep 17 00:00:00 2001 From: "shijinyu.7" Date: Wed, 17 Dec 2025 12:55:28 +0800 Subject: [PATCH] docs: add veadk-go agent, viking knowledge and web_search tool --- docs/docs/agent/agent.md | 184 +++++++-- docs/docs/agent/agents.md | 9 +- docs/docs/knowledgebase/overview.md | 407 ++++++++++++-------- docs/docs/tools/builtin.md | 55 ++- docs/examples/agent/agents/llm_agent.go | 78 ++++ docs/examples/knowledge/viking_knowledge.go | 124 ++++++ docs/examples/tools/web_search/agent.go | 54 +++ 7 files changed, 702 insertions(+), 209 deletions(-) create mode 100644 docs/examples/agent/agents/llm_agent.go create mode 100644 docs/examples/knowledge/viking_knowledge.go create mode 100644 docs/examples/tools/web_search/agent.go diff --git a/docs/docs/agent/agent.md b/docs/docs/agent/agent.md index 097dbb1d..dffecd09 100644 --- a/docs/docs/agent/agent.md +++ b/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,15 +110,33 @@ 您也可以通过以下方式设置更多 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 的系统提示词，用于定义其行为和响应风格。 @@ -66,18 +144,38 @@ root_agent = 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) -``` ### 通过配置文件 diff --git a/docs/docs/agent/agents.md b/docs/docs/agent/agents.md index 2b81a19d..01811988 100644 --- a/docs/docs/agent/agents.md +++ b/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" + ``` + + === "环境变量" 环境变量列表： diff --git a/docs/docs/knowledgebase/overview.md b/docs/docs/knowledgebase/overview.md index 3e2b0684..c91f64ff 100644 --- a/docs/docs/knowledgebase/overview.md +++ b/docs/docs/knowledgebase/overview.md @@ -190,188 +190,253 @@ database: #### 知识库初始化(从变量加载)： -```python -APP_NAME = "viking_demo" +=== "Python" + + ```python + APP_NAME = "viking_demo" + + mock_data = [ + """西格蒙德·弗洛伊德（Sigmund Freud，1856年5月6日-1939年9月23日）是精神分析的创始人。 + 精神分析既是一种治疗精神疾病的方法，也是一种解释人类行为的理论。弗洛伊德认为，我们童年时期的经历对我们的成年生活有很大的影响，并且塑造了我们的个性。 + 例如，源自人们曾经的创伤经历的焦虑感，会隐藏在意识深处，并且可能在成年期间引起精神问题（以神经症的形式）。""", + """阿尔弗雷德·阿德勒（Alfred Adler，1870年2月7日-1937年5月28日），奥地利精神病学家，人本主义心理学先驱，个体心理学的创始人。 + 曾追随弗洛伊D探讨神经症问题，但也是精神分析学派内部第一个反对弗洛伊德的心理学体系的心理学家。 + 著有《自卑与超越》《人性的研究》《个体心理学的理论与实践》《自卑与生活》等。""", + ] + kb = KnowledgeBase( + backend="viking", # 这里设置为viking + app_name=APP_NAME, + ) + res = kb.collection_status() + + if not res["existed"]: + kb.create_collection() # viking需要专门create一下 + + kb.add_from_text(mock_data) + ``` + +=== "Golang" + + ```golang + knowledgeBase, err := knowledgebase.NewKnowledgeBase( + ktypes.VikingBackend, + knowledgebase.WithBackendConfig( + &viking_knowledge_backend.Config{ + Index: "veadk_go_test_kg", + CreateIfNotExist: true, // 当 Index 不存在时会自动创建 + TosConfig: &ve_tos.Config{ + Bucket: "veadk-go-bucket", + }, + }), + ) + if err != nil { + log.Fatal("NewVikingKnowledgeBackend error: ", err) + } + + mock_data := []string{ + `西格蒙德·弗洛伊德（Sigmund Freud，1856年5月6日-1939年9月23日）是精神分析的创始人。 + 精神分析既是一种治疗精神疾病的方法，也是一种解释人类行为的理论。弗洛伊德认为，我们童年时期的经历对我们的成年生活有很大的影响，并且塑造了我们的个性。 + 例如，源自人们曾经的创伤经历的焦虑感，会隐藏在意识深处，并且可能在成年期间引起精神问题（以神经症的形式）。`, + `阿尔弗雷德·阿德勒（Alfred Adler，1870年2月7日-1937年5月28日），奥地利精神病学家，人本主义心理学先驱，个体心理学的创始人。 + 曾追随弗洛伊德探讨神经症问题，但也是精神分析学派内部第一个反对弗洛伊德的心理学体系的心理学家。 + 著有《自卑与超越》《人性的研究》《个体心理学的理论与实践》《自卑与生活》等。`} + + if err = knowledgeBase.Backend.AddFromText(mock_data); err != nil { + log.Fatal("AddFromText error: ", err) + return + } + ``` -mock_data = [ - """西格蒙德·弗洛伊德（Sigmund Freud，1856年5月6日-1939年9月23日）是精神分析的创始人。 - 精神分析既是一种治疗精神疾病的方法，也是一种解释人类行为的理论。弗洛伊德认为，我们童年时期的经历对我们的成年生活有很大的影响，并且塑造了我们的个性。 - 例如，源自人们曾经的创伤经历的焦虑感，会隐藏在意识深处，并且可能在成年期间引起精神问题（以神经症的形式）。""", - """阿尔弗雷德·阿德勒（Alfred Adler，1870年2月7日-1937年5月28日），奥地利精神病学家，人本主义心理学先驱，个体心理学的创始人。 - 曾追随弗洛伊D探讨神经症问题，但也是精神分析学派内部第一个反对弗洛伊德的心理学体系的心理学家。 - 著有《自卑与超越》《人性的研究》《个体心理学的理论与实践》《自卑与生活》等。""", -] -kb = KnowledgeBase( - backend="viking", # 这里设置为viking - app_name=APP_NAME, -) -res = kb.collection_status() - -if not res["existed"]: - kb.create_collection() # viking需要专门create一下 - -kb.add_from_text(mock_data) -``` #### Agent代码初始化： -```python -agent = Agent( - name="chat_agent", - model_name="doubao-seed-1-6-250615", - description="你是一个优秀的助手，你可以和用户进行对话。", - instruction="""你是一个优秀的助手。当被提问时，请遵循以下步骤： -1. 首先，根据你的内部知识，生成一个初步的回答。 -2. 然后，查询你的知识库，寻找与问题相关的信息来验证或丰富你的答案。 -3. 最后，结合你的内部知识和知识库中的信息，给出一个全面、准确的最终答案。""", - knowledgebase=kb, - tools=[calculate_date_difference], -) - -``` +=== "Python" + + ```python + agent = Agent( + name="chat_agent", + model_name="doubao-seed-1-6-250615", + description="你是一个优秀的助手，你可以和用户进行对话。", + instruction="""你是一个优秀的助手。当被提问时，请遵循以下步骤： + 1. 首先，根据你的内部知识，生成一个初步的回答。 + 2. 然后，查询你的知识库，寻找与问题相关的信息来验证或丰富你的答案。 + 3. 最后，结合你的内部知识和知识库中的信息，给出一个全面、准确的最终答案。""", + knowledgebase=kb, + tools=[calculate_date_difference], + ) + ``` + +=== "Golang" + + ```golang + cfg := veagent.Config{ + Config: llmagent.Config{ + Name: "chat_agent", + Description: "你是一个优秀的助手，你可以和用户进行对话。", + Instruction: `你是一个优秀的助手。当被提问时，请遵循以下步骤：\n1. 首先，根据你的内部知识，生成一个初步的回答。\n2. 然后，查询你的知识库，寻找与问题相关的信息来验证或丰富你的答案。\n3. 最后，结合你的内部知识和知识库中的信息，给出一个全面、准确的最终答案。`, + Tools: []tool.Tool{calculateDateDifferenceTool}, + }, + ModelName: "doubao-seed-1-6-250615", + KnowledgeBase: knowledgeBase, + } + + veAgent, err := veagent.New(&cfg) + if err != nil { + fmt.Printf("NewLLMAgent failed: %v", err) + return + } + ``` #### #### 完整代码： -```python -import os -from uuid import uuid4 -import yaml - -os.environ["LITELLM_LOGGING"] = "False" -os.environ["LOGGING_LEVEL"] = "DEBUG" - -import asyncio -from datetime import datetime - -from veadk import Agent, Runner -from veadk.knowledgebase import KnowledgeBase - -# 从config.yaml读取配置 -with open('config.yaml', 'r') as f: - config = yaml.safe_load(f) - -# 打印配置结构用于调试 -print("Config structure:", config) - -# 设置环境变量（使用get方法避免KeyError） -if config.get('database') and config['database'].get('viking'): - os.environ["DATABASE_VIKING_PROJECT"] = config['database']['viking'].get('project', 'default') - os.environ["DATABASE_VIKING_REGION"] = config['database']['viking'].get('region', 'cn-beijing') -else: - print("Warning: Viking database config not found, using defaults") - os.environ["DATABASE_VIKING_PROJECT"] = 'default' - os.environ["DATABASE_VIKING_REGION"] = 'cn-beijing' - -if config.get('database') and config['database'].get('tos'): - os.environ["DATABASE_TOS_BUCKET"] = config['database']['tos'].get('bucket', 'test-wangyue') -else: - print("Warning: TOS config not found, using default") - os.environ["DATABASE_TOS_BUCKET"] = 'test-wangyue' - -if config.get('volcengine'): - os.environ["VOLCENGINE_ACCESS_KEY"] = config['volcengine'].get('access_key', '') - os.environ["VOLCENGINE_SECRET_KEY"] = config['volcengine'].get('secret_key', '') -else: - print("Warning: Volcengine config not found") - os.environ["VOLCENGINE_ACCESS_KEY"] = '' - os.environ["VOLCENGINE_SECRET_KEY"] = '' - -# 验证环境变量 -assert os.getenv("DATABASE_VIKING_PROJECT") and os.getenv("DATABASE_VIKING_REGION"), ( - "请设置config.yaml里的viking参数" -) -assert os.getenv("VOLCENGINE_ACCESS_KEY") and os.getenv("VOLCENGINE_SECRET_KEY"), ( - "请在config.yaml里设置火山ak和sk" -) -assert os.getenv("DATABASE_TOS_BUCKET"), "请在config.yaml里设置tos相关的参数" - -APP_NAME = "viking_demo" - -mock_data = [ - """西格蒙德·弗洛伊德（Sigmund Freud，1856年5月6日-1939年9月23日）是精神分析的创始人。 - 精神分析既是一种治疗精神疾病的方法，也是一种解释人类行为的理论。弗洛伊德认为，我们童年时期的经历对我们的成年生活有很大的影响，并且塑造了我们的个性。 - 例如，源自人们曾经的创伤经历的焦虑感，会隐藏在意识深处，并且可能在成年期间引起精神问题（以神经症的形式）。""", - """阿尔弗雷德·阿德勒（Alfred Adler，1870年2月7日-1937年5月28日），奥地利精神病学家，人本主义心理学先驱，个体心理学的创始人。 - 曾追随弗洛伊德探讨神经症问题，但也是精神分析学派内部第一个反对弗洛伊德的心理学体系的心理学家。 - 著有《自卑与超越》《人性的研究》《个体心理学的理论与实践》《自卑与生活》等。""", -] -kb = KnowledgeBase( - backend="viking", # 这里设置为viking - app_name=APP_NAME, -) -res = kb.collection_status() - -if not res["existed"]: - kb.create_collection() # viking需要专门create一下 - -kb.add_from_text(mock_data) -#kb.add_from_files(["tmp/demo.txt"]) - -def calculate_date_difference(date1: str, date2: str) -> int: - """ - 计算两个日期之间的天数差异 - 参数: - date1: 第一个日期，格式为"YYYY-MM-DD" - date2: 第二个日期，格式为"YYYY-MM-DD" - 返回: - 两个日期之间的天数差异（绝对值） - """ - # 解析日期字符串为datetime对象 - try: - d1 = datetime.strptime(date1, "%Y-%m-%d") - d2 = datetime.strptime(date2, "%Y-%m-%d") - except ValueError as e: - raise ValueError(f"日期格式错误，请使用YYYY-MM-DD格式: {e}") - # 计算日期差并返回绝对值 - delta = d2 - d1 - return abs(delta.days) - -agent = Agent( - name="chat_agent", - model_name="doubao-seed-1-6-250615", - description="你是一个优秀的助手，你可以和用户进行对话。", - instruction="你是一个优秀的助手，你可以和用户进行对话。", - knowledgebase=kb, - tools=[calculate_date_difference], -) - -runner = Runner( - agent, - app_name=APP_NAME, -) - -async def main(): - """ - 主函数，用于运行agent - """ - session_id = uuid4().hex - while True: - try: - print(" - -您: ", end="") - message = input() - if message.strip().lower() == "exit": - break - print(" - -Agent: ") - completion = await runner.run( - messages=message, - session_id=session_id, - ) - print(completion) - - except (KeyboardInterrupt, EOFError): - break - -if __name__ == "__main__": - asyncio.run(main()) -``` +=== "Python" + + ```python + import os + from uuid import uuid4 + import yaml + + os.environ["LITELLM_LOGGING"] = "False" + os.environ["LOGGING_LEVEL"] = "DEBUG" + + import asyncio + from datetime import datetime + + from veadk import Agent, Runner + from veadk.knowledgebase import KnowledgeBase + + # 从config.yaml读取配置 + with open('config.yaml', 'r') as f: + config = yaml.safe_load(f) + + # 打印配置结构用于调试 + print("Config structure:", config) + + # 设置环境变量（使用get方法避免KeyError） + if config.get('database') and config['database'].get('viking'): + os.environ["DATABASE_VIKING_PROJECT"] = config['database']['viking'].get('project', 'default') + os.environ["DATABASE_VIKING_REGION"] = config['database']['viking'].get('region', 'cn-beijing') + else: + print("Warning: Viking database config not found, using defaults") + os.environ["DATABASE_VIKING_PROJECT"] = 'default' + os.environ["DATABASE_VIKING_REGION"] = 'cn-beijing' + + if config.get('database') and config['database'].get('tos'): + os.environ["DATABASE_TOS_BUCKET"] = config['database']['tos'].get('bucket', 'test-wangyue') + else: + print("Warning: TOS config not found, using default") + os.environ["DATABASE_TOS_BUCKET"] = 'test-wangyue' + + if config.get('volcengine'): + os.environ["VOLCENGINE_ACCESS_KEY"] = config['volcengine'].get('access_key', '') + os.environ["VOLCENGINE_SECRET_KEY"] = config['volcengine'].get('secret_key', '') + else: + print("Warning: Volcengine config not found") + os.environ["VOLCENGINE_ACCESS_KEY"] = '' + os.environ["VOLCENGINE_SECRET_KEY"] = '' + + # 验证环境变量 + assert os.getenv("DATABASE_VIKING_PROJECT") and os.getenv("DATABASE_VIKING_REGION"), ( + "请设置config.yaml里的viking参数" + ) + assert os.getenv("VOLCENGINE_ACCESS_KEY") and os.getenv("VOLCENGINE_SECRET_KEY"), ( + "请在config.yaml里设置火山ak和sk" + ) + assert os.getenv("DATABASE_TOS_BUCKET"), "请在config.yaml里设置tos相关的参数" + + APP_NAME = "viking_demo" + + mock_data = [ + """西格蒙德·弗洛伊德（Sigmund Freud，1856年5月6日-1939年9月23日）是精神分析的创始人。 + 精神分析既是一种治疗精神疾病的方法，也是一种解释人类行为的理论。弗洛伊德认为，我们童年时期的经历对我们的成年生活有很大的影响，并且塑造了我们的个性。 + 例如，源自人们曾经的创伤经历的焦虑感，会隐藏在意识深处，并且可能在成年期间引起精神问题（以神经症的形式）。""", + """阿尔弗雷德·阿德勒（Alfred Adler，1870年2月7日-1937年5月28日），奥地利精神病学家，人本主义心理学先驱，个体心理学的创始人。 + 曾追随弗洛伊德探讨神经症问题，但也是精神分析学派内部第一个反对弗洛伊德的心理学体系的心理学家。 + 著有《自卑与超越》《人性的研究》《个体心理学的理论与实践》《自卑与生活》等。""", + ] + kb = KnowledgeBase( + backend="viking", # 这里设置为viking + app_name=APP_NAME, + ) + res = kb.collection_status() + + if not res["existed"]: + kb.create_collection() # viking需要专门create一下 + + kb.add_from_text(mock_data) + #kb.add_from_files(["tmp/demo.txt"]) + + def calculate_date_difference(date1: str, date2: str) -> int: + """ + 计算两个日期之间的天数差异 + 参数: + date1: 第一个日期，格式为"YYYY-MM-DD" + date2: 第二个日期，格式为"YYYY-MM-DD" + 返回: + 两个日期之间的天数差异（绝对值） + """ + # 解析日期字符串为datetime对象 + try: + d1 = datetime.strptime(date1, "%Y-%m-%d") + d2 = datetime.strptime(date2, "%Y-%m-%d") + except ValueError as e: + raise ValueError(f"日期格式错误，请使用YYYY-MM-DD格式: {e}") + # 计算日期差并返回绝对值 + delta = d2 - d1 + return abs(delta.days) + + agent = Agent( + name="chat_agent", + model_name="doubao-seed-1-6-250615", + description="你是一个优秀的助手，你可以和用户进行对话。", + instruction="你是一个优秀的助手，你可以和用户进行对话。", + knowledgebase=kb, + tools=[calculate_date_difference], + ) + + runner = Runner( + agent, + app_name=APP_NAME, + ) + + async def main(): + """ + 主函数，用于运行agent + """ + session_id = uuid4().hex + while True: + try: + print(" + + 您: ", end="") + message = input() + if message.strip().lower() == "exit": + break + print(" + + Agent: ") + completion = await runner.run( + messages=message, + session_id=session_id, + ) + print(completion) + + except (KeyboardInterrupt, EOFError): + break + + if __name__ == "__main__": + asyncio.run(main()) + ``` + +=== "Golang" + + ```golang + --8<-- "examples/knowledge/viking_knowledge.go" + ``` #### 运行结果： diff --git a/docs/docs/tools/builtin.md b/docs/docs/tools/builtin.md index 5d232513..a07d0d80 100644 --- a/docs/docs/tools/builtin.md +++ b/docs/docs/tools/builtin.md @@ -9,13 +9,46 @@ 2. **配置**：初始化工具并按需提供参数。 3. **注册**：将工具实例添加至 Agent 的 `tools` 列表。 -```python -from veadk import Agent -from veadk.tools.builtin_tools.web_search import websearch +=== "Python" -# 在 Agent 初始化时注册工具 -# Agent(tools=[websearch], other_params...) -``` + ```python + from veadk import Agent + from veadk.tools.builtin_tools.web_search import websearch + + # 在 Agent 初始化时注册工具 + # Agent(tools=[websearch], other_params...) + ``` + +=== "Golang" + + ```golang + import ( + "log" + + veagent "github.com/volcengine/veadk-go/agent/llmagent" + "github.com/volcengine/veadk-go/tool/builtin_tools/web_search" + "google.golang.org/adk/agent/llmagent" + "google.golang.org/adk/tool" + ) + + func main() { + webSearch, err := web_search.NewWebSearchTool(&web_search.Config{}) + if err != nil { + log.Fatalf("NewWebSearchTool failed: %v", err) + return + } + cfg := veagent.Config{ + Config: llmagent.Config{ + Tools: []tool.Tool{webSearch}, + }, + } + veAgent, err := veagent.New(&cfg) + if err != nil { + log.Fatalf("NewLLMAgent failed: %v", err) + return + } + } + ``` 工具注册后，Agent 会根据 **用户提示** 和 **指令** 自主决定是否调用。框架将在调用时自动执行工具。 @@ -46,12 +79,20 @@ veADK 集成了以下火山引擎工具： 1. 需要配置火山引擎 AK、SK 或者使用火山引 IAM 授权的临时 StsToken 2. 需要配置用于 Agent 推理模型的API Key -=== "代码" +=== "Python" ```python --8<-- "examples/tools/web_search/agent.py" ``` +=== "Golang" + + ```golang + --8<-- "examples/tools/web_search/agent.go" + ``` + + + === "环境变量" 环境变量列表： diff --git a/docs/examples/agent/agents/llm_agent.go b/docs/examples/agent/agents/llm_agent.go new file mode 100644 index 00000000..8223f69a --- /dev/null +++ b/docs/examples/agent/agents/llm_agent.go @@ -0,0 +1,78 @@ +package main + +import ( + "context" + "fmt" + "log" + "os" + + veagent "github.com/volcengine/veadk-go/agent/llmagent" + vetool "github.com/volcengine/veadk-go/tool" + "google.golang.org/adk/agent" + "google.golang.org/adk/agent/llmagent" + "google.golang.org/adk/cmd/launcher" + "google.golang.org/adk/cmd/launcher/full" + "google.golang.org/adk/session" + "google.golang.org/adk/tool" +) + +func main() { + ctx := context.Background() + + getCityWeatherTool, err := vetool.GetCityWeatherTool() + if err != nil { + fmt.Printf("GetCityWeatherTool failed: %v", err) + return + } + + weatherReporter, err := veagent.New(&veagent.Config{ + Config: llmagent.Config{ + Name: "weather_reporter", + Description: "A weather reporter agent to report the weather.", + Tools: []tool.Tool{getCityWeatherTool}, + }, + }) + if err != nil { + fmt.Printf("NewLLMAgent weatherReporter failed: %v", err) + return + } + + suggester, err := veagent.New(&veagent.Config{ + Config: llmagent.Config{ + Name: "suggester", + Description: "A suggester agent that can give some clothing suggestions according to a city's weather.", + Instruction: `Provide clothing suggestions based on weather temperature: + wear a coat when temperature is below 15°C, wear long sleeves when temperature is between 15-25°C, + wear short sleeves when temperature is above 25°C.`, + }, + }) + if err != nil { + fmt.Printf("NewLLMAgent suggester failed: %v", err) + return + } + + rootAgent, err := veagent.New(&veagent.Config{ + Config: llmagent.Config{ + Name: "planner", + Description: "A planner that can generate a suggestion according to a city's weather.", + Instruction: `Invoke weather reporter agent first to get the weather, + then invoke suggester agent to get the suggestion. Return the final response to user.`, + SubAgents: []agent.Agent{weatherReporter, suggester}, + }, + }) + if err != nil { + fmt.Printf("NewLLMAgent rootAgent failed: %v", err) + return + } + + config := &launcher.Config{ + AgentLoader: agent.NewSingleLoader(rootAgent), + SessionService: session.InMemoryService(), + } + + l := full.NewLauncher() + if err = l.Execute(ctx, config, os.Args[1:]); err != nil { + log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax()) + } + +} diff --git a/docs/examples/knowledge/viking_knowledge.go b/docs/examples/knowledge/viking_knowledge.go new file mode 100644 index 00000000..7b6af33c --- /dev/null +++ b/docs/examples/knowledge/viking_knowledge.go @@ -0,0 +1,124 @@ +package main + +import ( + "context" + "fmt" + "log" + "math" + "os" + "strings" + "time" + + veagent "github.com/volcengine/veadk-go/agent/llmagent" + "github.com/volcengine/veadk-go/integrations/ve_tos" + "github.com/volcengine/veadk-go/knowledgebase" + "github.com/volcengine/veadk-go/knowledgebase/backend/viking_knowledge_backend" + "github.com/volcengine/veadk-go/knowledgebase/ktypes" + "google.golang.org/adk/agent" + "google.golang.org/adk/agent/llmagent" + "google.golang.org/adk/cmd/launcher" + "google.golang.org/adk/cmd/launcher/full" + "google.golang.org/adk/session" + "google.golang.org/adk/tool" + "google.golang.org/adk/tool/functiontool" +) + +func main() { + ctx := context.Background() + knowledgeBase, err := knowledgebase.NewKnowledgeBase( + ktypes.VikingBackend, + knowledgebase.WithBackendConfig( + &viking_knowledge_backend.Config{ + Index: "veadk_go_test_kg", + CreateIfNotExist: true, + TosConfig: &ve_tos.Config{ + Bucket: "veadk-go-bucket", + }, + }), + ) + if err != nil { + log.Fatal("NewVikingKnowledgeBackend error: ", err) + } + + mock_data := []string{ + `西格蒙德·弗洛伊德（Sigmund Freud，1856年5月6日-1939年9月23日）是精神分析的创始人。 + 精神分析既是一种治疗精神疾病的方法，也是一种解释人类行为的理论。弗洛伊德认为，我们童年时期的经历对我们的成年生活有很大的影响，并且塑造了我们的个性。 + 例如，源自人们曾经的创伤经历的焦虑感，会隐藏在意识深处，并且可能在成年期间引起精神问题（以神经症的形式）。`, + `阿尔弗雷德·阿德勒（Alfred Adler，1870年2月7日-1937年5月28日），奥地利精神病学家，人本主义心理学先驱，个体心理学的创始人。 + 曾追随弗洛伊德探讨神经症问题，但也是精神分析学派内部第一个反对弗洛伊德的心理学体系的心理学家。 + 著有《自卑与超越》《人性的研究》《个体心理学的理论与实践》《自卑与生活》等。`} + + if err = knowledgeBase.Backend.AddFromText(mock_data); err != nil { + log.Fatal("AddFromText error: ", err) + return + } + + calculateDateDifferenceTool, err := CalculateDateDifferenceTool() + if err != nil { + log.Fatal("CalculateDateDifferenceTool error: ", err) + return + } + + cfg := veagent.Config{ + Config: llmagent.Config{ + Name: "chat_agent", + Description: "你是一个优秀的助手，你可以和用户进行对话。", + Instruction: `你是一个优秀的助手。当被提问时，请遵循以下步骤：\n1. 首先，根据你的内部知识，生成一个初步的回答。\n2. 然后，查询你的知识库，寻找与问题相关的信息来验证或丰富你的答案。\n3. 最后，结合你的内部知识和知识库中的信息，给出一个全面、准确的最终答案。`, + Tools: []tool.Tool{calculateDateDifferenceTool}, + }, + ModelName: "doubao-seed-1-6-250615", + KnowledgeBase: knowledgeBase, + } + + veAgent, err := veagent.New(&cfg) + if err != nil { + fmt.Printf("NewLLMAgent failed: %v", err) + return + } + + config := &launcher.Config{ + AgentLoader: agent.NewSingleLoader(veAgent), + SessionService: session.InMemoryService(), + } + + l := full.NewLauncher() + if err = l.Execute(ctx, config, os.Args[1:]); err != nil { + log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax()) + } +} + +type CalculateDateDifferenceArgs struct { + Date1 string `json:"date1" jsonschema:"第一个日期，格式为YYYY-MM-DD"` + Date2 string `json:"date2" jsonschema:"第二个日期，格式为YYYY-MM-DD"` +} + +func CalculateDateDifferenceTool() (tool.Tool, error) { + handler := func(ctx tool.Context, args CalculateDateDifferenceArgs) (map[string]any, error) { + diff, err := CalculateDateDifference(args.Date1, args.Date2) + if err != nil { + return nil, err + } + return map[string]any{"result": diff}, nil + } + return functiontool.New( + functiontool.Config{ + Name: "calculate date difference", + Description: "计算两个日期之间的天数差异\nArgs:\n\tdate1: 第一个日期，格式为YYYY-MM-DD\n\tdate2: 第二个日期，格式为YYYY-MM-DD\nReturns:\n\t两个日期之间的天数差异（绝对值）", + }, + handler, + ) +} + +func CalculateDateDifference(date1 string, date2 string) (int, error) { + d1, err := time.Parse("2006-01-02", strings.TrimSpace(date1)) + if err != nil { + return 0, fmt.Errorf("日期格式错误，请使用YYYY-MM-DD格式: %v", err) + } + d2, err := time.Parse("2006-01-02", strings.TrimSpace(date2)) + if err != nil { + return 0, fmt.Errorf("日期格式错误，请使用YYYY-MM-DD格式: %v", err) + } + delta := d2.Sub(d1) + days := int(math.Abs(delta.Hours() / 24)) + return days, nil +} diff --git a/docs/examples/tools/web_search/agent.go b/docs/examples/tools/web_search/agent.go new file mode 100644 index 00000000..a0a31b52 --- /dev/null +++ b/docs/examples/tools/web_search/agent.go @@ -0,0 +1,54 @@ +package main + +import ( + "context" + "log" + "os" + + veagent "github.com/volcengine/veadk-go/agent/llmagent" + "github.com/volcengine/veadk-go/common" + "github.com/volcengine/veadk-go/tool/builtin_tools/web_search" + "github.com/volcengine/veadk-go/utils" + "google.golang.org/adk/agent" + "google.golang.org/adk/cmd/launcher" + "google.golang.org/adk/cmd/launcher/full" + "google.golang.org/adk/session" + "google.golang.org/adk/tool" +) + +func main() { + ctx := context.Background() + sessionService := session.InMemoryService() + + cfg := &veagent.Config{ + ModelName: common.DEFAULT_MODEL_AGENT_NAME, + ModelAPIBase: common.DEFAULT_MODEL_AGENT_API_BASE, + ModelAPIKey: utils.GetEnvWithDefault(common.MODEL_AGENT_API_KEY), + } + cfg.Name = "WebSearchAgent" + cfg.Description = "An agent that can get result from Web Search" + cfg.Instruction = "You are a helpful assistant that can provide information use web search tool." + + webSearch, err := web_search.NewWebSearchTool(&web_search.Config{}) + if err != nil { + log.Fatalf("NewWebSearchTool failed: %v", err) + return + } + + cfg.Tools = []tool.Tool{webSearch} + + rootAgent, err := veagent.New(cfg) + if err != nil { + log.Fatalf("Failed to create agent: %v", err) + } + + config := &launcher.Config{ + AgentLoader: agent.NewSingleLoader(rootAgent), + SessionService: sessionService, + } + + l := full.NewLauncher() + if err = l.Execute(ctx, config, os.Args[1:]); err != nil { + log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax()) + } +}