英文原地址：Chapter 5: Tool Use
概述
到目前为止，我们讨论的智能体模式主要涉及在语言模型之间编排交互，并在智能体的内部工作流中管理信息流（链式处理、路由、并行化、反思）。然而，要让智能体真正有用并与现实世界或外部系统交互，它们需要具备使用工具的能力。
工具使用模式通常通过一种称为函数调用（Function Calling）的机制来实现，使智能体能够与外部 API、数据库、服务进行交互，甚至执行代码。它允许位于智能体核心的 LLM 根据用户请求或任务的当前状态，决定何时以及如何使用特定的外部函数。
该过程通常包括：
- 工具定义： 将外部函数或能力定义并描述给 LLM。该描述包括函数的用途、名称，以及它所接受的参数及其类型和说明。
- LLM 决策： LLM 接收用户请求和可用的工具定义。基于其对请求和工具的理解，LLM 决定是否需要调用一个或多个工具来完成请求。
- 函数调用生成： 如果 LLM 决定使用某个工具，它会生成结构化输出（通常为 JSON 对象），其中指定要调用的工具名称以及从用户请求中提取并传递给该工具的参数（参数）。
- 工具执行： 智能体框架或编排层拦截该结构化输出。它识别所请求的工具，并使用提供的参数执行实际的外部函数。
- 观察/结果： 工具执行的输出或结果会返回给智能体。
- LLM 处理（可选但常见）： LLM 将工具的输出作为上下文，并据此为用户制定最终回应，或决定工作流中的下一步（可能涉及调用另一个工具、反思，或提供最终答案）。
这种模式至关重要，因为它打破了 LLM 训练数据的局限，使其能够获取最新信息、执行其内部无法完成的计算、与用户特定数据交互，或触发现实世界中的操作。函数调用是连接 LLM 推理能力与大量外部可用功能之间鸿沟的技术机制。
虽然"函数调用"恰当地描述了调用特定的预定义代码函数，但考虑更广义的"工具调用"概念也很有用。这个更宽泛的术语承认智能体的能力可以远远超出简单的函数执行。"工具"可以是传统的函数，也可以是复杂的 API 端点、对数据库的请求，甚至是对另一位专业智能体的指令。这种视角让我们能够设想更复杂的系统，例如，一个主智能体可能将复杂的数据分析任务委派给专门的"分析智能体"，或通过其 API 查询外部知识库。从"工具调用"的角度思考，更能体现智能体作为编排者，在多样化的数字资源和其他智能实体生态系统中发挥全部潜力。
像 LangChain、LangGraph 和 Google Agent Developer Kit（ADK）这样的框架，为定义工具并将其集成到智能体工作流中提供了强大的支持，通常会利用现代 LLMs（如 Gemini 或 OpenAI 系列）所具备的原生函数调用能力。在这些框架的"画布"上，你先定义工具，然后配置智能体（通常是 LLM 智能体）以了解并能够使用这些工具。
工具使用是构建强大、交互式且具备外部感知能力智能体的基石模式。
实际应用与使用场景
当智能体需要超越仅生成文本、去执行某个动作或检索特定的动态信息时，工具使用模式几乎适用于任何场景：
1. 来自外部来源的信息检索 访问实时数据或不在 LLM 训练数据中的信息。
- 用例： 天气智能体。
- 工具： 一个天气 API，输入地点并返回当前天气状况。
- 流程： 用户询问"伦敦的天气怎么样？"，LLM 识别到需要使用天气工具，用"London"调用该工具，工具返回数据，LLM 将数据整理为用户友好的回复。
2. 与数据库和 API 交互 对结构化数据执行查询、更新或其他操作。
- 用例： 电商智能体。
- 工具： 通过 API 调用检查产品库存、获取订单状态或处理支付。
- 流程： 用户询问"产品 X 有库存吗？"，LLM 调用库存 API，工具返回库存数量，LLM 告知用户库存状态。
3. 执行计算和数据分析 使用外部计算器、数据分析库或统计工具。
- 用例： 金融智能体。
- 工具： 一个计算器功能、一个股票市场数据 API、一个电子表格工具。
- 流程： 用户询问"现在 AAPL 的价格是多少，如果我以 150 美元买入 100 股，潜在利润是多少？"，LLM 调用股票 API，获得当前价格，然后调用计算器工具，得到结果并格式化回复。
4. 通信 发送电子邮件、消息或向外部通信服务发出 API 调用。
- 用例： 私人助理智能体。
- 工具： 电子邮件发送 API。
- 流程： 用户说："给 John 发送一封关于明天会议的邮件。"，LLM 使用从请求中提取的收件人、主题和正文调用电子邮件工具。
5. 运行代码 在安全环境中运行代码片段以执行特定任务。
- 用例： 编程助手智能体。
- 工具： 代码解释器。
- 流程： 用户提供一个 Python 代码片段并询问"这段代码做什么？"，LLM 使用解释器工具运行代码并分析其输出。
6. 控制其他系统或设备 与智能家居设备、物联网平台或其他连接系统进行交互。
- 用例： 智能家居智能体。
- 工具： 用于控制智能灯的 API。
- 流程： 用户说："关闭客厅灯"，LLM 使用该命令和目标设备调用智能家居工具。
工具使用将语言模型从文本生成器转变为能够在数字或物理世界中感知、推理和行动的智能体 
实战代码示例（LangChain）
在 LangChain 框架中，实现工具使用是一个两阶段的过程。首先，定义一个或多个工具，通常通过封装现有的 Python 函数或其他可运行组件。随后，这些工具会绑定到语言模型上，从而在模型判断需要调用外部函数以满足用户请求时，赋予其生成结构化工具调用请求的能力。
以下实现将通过首先定义一个简单函数来模拟信息检索工具来演示这一原理。随后，将构建并配置一个智能体，以便在响应用户输入时利用该工具。运行此示例需要安装核心 LangChain 库以及与模型相关的提供方包。此外，还需要与所选语言模型服务进行正确的身份验证，通常通过在本地环境中配置的 API 密钥来完成，这是必备的前提条件。
python
import os, getpass
import asyncio
import nest_asyncio
from typing import List
from dotenv import load_dotenv
import logging
from langchain_google_genai import ChatGoogleGenerativeAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.tools import tool as langchain_tool
from langchain.agents import create_tool_calling_agent, AgentExecutor
# UNCOMMENT
# Prompt the user securely and set API keys as an environment variables
os.environ["GOOGLE_API_KEY"] = getpass.getpass("Enter your Google API key: ")
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")
try:
# A model with function/tool calling capabilities is required.
llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash", temperature=0)
print(f"✅ Language model initialized: {llm.model}")
except Exception as e:
print(f"🛑 Error initializing language model: {e}")
llm = None
# --- Define a Tool ---
@langchain_tool
def search_information(query: str) -> str:
"""
Provides factual information on a given topic. Use this tool to find answers to phrases
like 'capital of France' or 'weather in London?'.
"""
print(f"\n--- 🛠️ Tool Called: search_information with query: '{query}' ---")
# Simulate a search tool with a dictionary of predefined results.
simulated_results = {
"weather in london": "The weather in London is currently cloudy with a temperature of 15°C.",
"capital of france": "The capital of France is Paris.",
"population of earth": "The estimated population of Earth is around 8 billion people.",
"tallest mountain": "Mount Everest is the tallest mountain above sea level.",
"default": f"Simulated search result for '{query}': No specific information found, but the topic seems interesting."
}
result = simulated_results.get(query.lower(), simulated_results["default"])
print(f"--- TOOL RESULT: {result} ---")
return result
tools = [search_information]
# --- Create a Tool-Calling Agent ---
if llm:
# This prompt template requires an `agent_scratchpad` placeholder for the agent's internal steps.
agent_prompt = ChatPromptTemplate.from_messages([
("system", "You are a helpful assistant."),
("human", "{input}"),
("placeholder", "{agent_scratchpad}"),
])
# Create the agent, binding the LLM, tools, and prompt together.
agent = create_tool_calling_agent(llm, tools, agent_prompt)
# AgentExecutor is the runtime that invokes the agent and executes the chosen tools.
# The 'tools' argument is not needed here as they are already bound to the agent.
agent_executor = AgentExecutor(agent=agent, verbose=True, tools=tools)
async def run_agent_with_tool(query: str):
"""Invokes the agent executor with a query and prints the final response."""
print(f"\n--- 🏃 Running Agent with Query: '{query}' ---")
try:
response = await agent_executor.ainvoke({"input": query})
print("\n--- ✅ Final Agent Response ---")
print(response["output"])
except Exception as e:
print(f"\n🛑 An error occurred during agent execution: {e}")
async def main():
"""Runs all agent queries concurrently."""
tasks = [
run_agent_with_tool("What is the capital of France?"),
run_agent_with_tool("What's the weather like in London?"),
run_agent_with_tool("Tell me something about dogs.") # Should trigger the default tool response
]
await asyncio.gather(*tasks)
nest_asyncio.apply()
asyncio.run(main())该代码使用 LangChain 库和 Google Gemini 模型设置了一个可调用工具的智能体。它定义了一个名为 search_information 的工具，用于模拟对特定查询提供事实性答案。该工具对 "weather in london"、"capital of france" 和 "population of earth" 提供预设响应，并对其他查询提供默认响应。初始化了一个 ChatGoogleGenerativeAI 模型，确保其具备工具调用能力。创建了一个 ChatPromptTemplate 来引导智能体的交互。通过 create_tool_calling_agent 函数将语言模型、工具和提示组合为一个智能体。随后设置了一个 AgentExecutor 来管理智能体的执行与工具调用。定义了异步函数 run_agent_with_tool，用于以给定查询调用智能体并打印结果。主异步函数准备了多个将并发运行的查询，这些查询用于测试 search_information 工具的特定响应和默认响应。最后，通过 asyncio.run(main()) 执行所有智能体任务。代码在进行智能体设置和执行前包含对 LLM 成功初始化的检查。
实战代码示例（CrewAI）
这段代码提供了一个在 CrewAI 框架中实现函数调用（Tools）的实用示例。它设置了一个简单的场景，让一个智能体配备了用于查询信息的工具。该示例特别演示了如何使用这个智能体和工具获取模拟的股票价格。
python
# pip install crewai langchain-openai
import os
from crewai import Agent, Task, Crew
from crewai.tools import tool
import logging
# --- Best Practice: Configure Logging ---
# A basic logging setup helps in debugging and tracking the crew's execution.
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
# --- Set up your API Key ---
# For production, it's recommended to use a more secure method for key management
# like environment variables loaded at runtime or a secret manager.
#
# Set the environment variable for your chosen LLM provider (e.g., OPENAI_API_KEY)
# os.environ["OPENAI_API_KEY"] = "YOUR_API_KEY"
# os.environ["OPENAI_MODEL_NAME"] = "gpt-4o"
# --- 1. Refactored Tool: Returns Clean Data ---
# The tool now returns raw data (a float) or raises a standard Python error.
# This makes it more reusable and forces the agent to handle outcomes properly.
@tool("Stock Price Lookup Tool")
def get_stock_price(ticker: str) -> float:
"""
Fetches the latest simulated stock price for a given stock ticker symbol.
Returns the price as a float. Raises a ValueError if the ticker is not found.
"""
logging.info(f"Tool Call: get_stock_price for ticker '{ticker}'")
simulated_prices = {
"AAPL": 178.15,
"GOOGL": 1750.30,
"MSFT": 425.50,
}
price = simulated_prices.get(ticker.upper())
if price is not None:
return price
else:
# Raising a specific error is better than returning a string.
# The agent is equipped to handle exceptions and can decide on the next action.
raise ValueError(f"Simulated price for ticker '{ticker.upper()}' not found.")
# --- 2. Define the Agent ---
# The agent definition remains the same, but it will now leverage the improved tool.
financial_analyst_agent = Agent(
role='Senior Financial Analyst',
goal='Analyze stock data using provided tools and report key prices.',
backstory="You are an experienced financial analyst adept at using data sources to find stock information. You provide clear, direct answers.",
verbose=True,
tools=[get_stock_price],
# Allowing delegation can be useful, but is not necessary for this simple task.
allow_delegation=False,
)
# --- 3. Refined Task: Clearer Instructions and Error Handling ---
# The task description is more specific and guides the agent on how to react
# to both successful data retrieval and potential errors.
analyze_aapl_task = Task(
description=(
"What is the current simulated stock price for Apple (ticker: AAPL)? "
"Use the 'Stock Price Lookup Tool' to find it. "
"If the ticker is not found, you must report that you were unable to retrieve the price."
),
expected_output=(
"A single, clear sentence stating the simulated stock price for AAPL. "
"For example: 'The simulated stock price for AAPL is $178.15.' "
"If the price cannot be found, state that clearly."
),
agent=financial_analyst_agent,
)
# --- 4. Formulate the Crew ---
# The crew orchestrates how the agent and task work together.
financial_crew = Crew(
agents=[financial_analyst_agent],
tasks=[analyze_aapl_task],
verbose=True # Set to False for less detailed logs in production
)
# --- 5. Run the Crew within a Main Execution Block ---
# Using a __name__ == "__main__": block is a standard Python best practice.
def main():
"""Main function to run the crew."""
# Check for API key before starting to avoid runtime errors.
if not os.environ.get("OPENAI_API_KEY"):
print("ERROR: The OPENAI_API_KEY environment variable is not set.")
print("Please set it before running the script.")
return
print("\n## Starting the Financial Crew...")
print("---------------------------------")
# The kickoff method starts the execution.
result = financial_crew.kickoff()
print("\n---------------------------------")
print("## Crew execution finished.")
print("\nFinal Result:\n", result)
if __name__ == "__main__":
main()这段代码演示了一个使用 Crew.ai 库来模拟财务分析任务的简单应用。它定义了一个自定义工具 get_stock_price，用于模拟查询预定义股票代码的股价。该工具被设计为：对有效的股票代码返回浮点数，对无效的股票代码抛出 ValueError。创建了一个名为 financial_analyst_agent 的 Crew.ai Agent，角色为高级财务分析师。该智能体被赋予 get_stock_price 工具以进行交互。定义了一个名为 analyze_aapl_task 的 Task，专门指示智能体使用该工具查找 AAPL 的模拟股价。任务描述包含了在使用该工具时如何处理成功与失败两种情况的明确指示。随后组建了一个 Crew，由 financial_analyst_agent 和 analyze_aapl_task 组成。为智能体和团队都启用了 verbose 设置，以在执行过程中提供详细日志。脚本的主体部分在标准的 if name == "main": 块中使用 kickoff() 方法运行团队的任务。在启动团队之前，它会检查是否设置了 OPENAI_API_KEY 环境变量，这是智能体正常运行所必需的。 随后会将该团队执行的结果（即任务的输出）打印到控制台。代码还包含基本的日志配置，以便更好地追踪团队的操作和工具调用。它使用环境变量来管理 API 密钥，但同时指出在生产环境中建议采用更安全的方法。简而言之，核心逻辑展示了如何定义工具、智能体和任务，以在 Crew.ai 中创建协作式工作流。
实战代码示例（ADK）
Google Agent Developer Kit（ADK）包含一个原生集成工具库，可直接纳入智能体的能力范围。
Google 搜索： 此类组件的一个主要示例是 Google Search 工具。该工具作为通往 Google 搜索引擎的直接接口，为智能体提供执行网页搜索和检索外部信息的功能。
python
from google.adk.agents import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.tools import google_search
from google.genai import types
import nest_asyncio
import asyncio
# Define variables required for Session setup and Agent execution
APP_NAME="Google Search_agent"
USER_ID="user1234"
SESSION_ID="1234"
# Define Agent with access to search tool
root_agent = ADKAgent(
name="basic_search_agent",
model="gemini-2.0-flash-exp",
description="Agent to answer questions using Google Search.",
instruction="I can answer your questions by searching the internet. Just ask me anything!",
tools=[google_search] # Google Search is a pre-built tool to perform Google searches.
)
# Agent Interaction
async def call_agent(query):
"""
Helper function to call the agent with a query.
"""
# Session and Runner
session_service = InMemorySessionService()
session = await session_service.create_session(app_name=APP_NAME, user_id=USER_ID, session_id=SESSION_ID)
runner = Runner(agent=root_agent, app_name=APP_NAME, session_service=session_service)
content = types.Content(role='user', parts=[types.Part(text=query)])
events = runner.run(user_id=USER_ID, session_id=SESSION_ID, new_message=content)
for event in events:
if event.is_final_response():
final_response = event.content.parts[0].text
print("Agent Response: ", final_response)
nest_asyncio.apply()
asyncio.run(call_agent("what's the latest ai news?"))此代码演示了如何使用适用于 Python 的 Google ADK 创建并使用一个基础智能体。该智能体旨在通过将 Google 搜索作为工具来回答问题。首先，导入来自 IPython、google.adk 和 google.genai 的必要库。定义应用名称、用户 ID 和会话 ID 的常量。创建一个名为"basic_search_agent"的 Agent 实例，并提供描述与指令以表明其用途。它被配置为使用 Google 搜索工具，这是 ADK 提供的预构建工具。初始化一个 InMemorySessionService（参见第 8 章）以管理该智能体的会话。为指定的应用、用户和会话 ID 创建一个新会话。实例化一个 Runner，将创建的智能体与会话服务关联。该 runner 负责在会话中执行智能体的交互。定义一个辅助函数 call_agent，以简化向智能体发送查询并处理响应的过程。在 call_agent 内部，用户的查询被格式化为角色为"user"的 types.Content 对象。调用 runner.run 方法，并传入用户 ID、会话 ID 以及新的消息内容。 runner.run 方法返回一个表示智能体行动和响应的事件列表。代码会遍历这些事件以找到最终响应。如果某个事件被识别为最终响应，则会提取该响应的文本内容。随后，提取出的智能体响应会被打印到控制台。最后，调用 call_agent 函数并传入查询 "what's the latest ai news?"，以演示智能体的实际运行。
代码执行： Google ADK 提供了用于专门任务的集成组件，包括用于动态代码执行的环境。built_in_code_execution 工具为智能体提供了一个沙盒化的 Python 解释器。这使模型能够编写并运行代码，以执行计算任务、操作数据结构以及执行过程化脚本。此类功能对于解决需要确定性逻辑和精确计算的问题至关重要，而这些问题超出了仅依赖概率性语言生成的能力范围。
python
import os, getpass
import asyncio
import nest_asyncio
from typing import List
from dotenv import load_dotenv
import logging
from google.adk.agents import Agent as ADKAgent, LlmAgent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.tools import google_search
from google.adk.code_executors import BuiltInCodeExecutor
from google.genai import types
# Define variables required for Session setup and Agent execution
APP_NAME="calculator"
USER_ID="user1234"
SESSION_ID="session_code_exec_async"
# Agent Definition
code_agent = LlmAgent(
name="calculator_agent",
model="gemini-2.0-flash",
code_executor=BuiltInCodeExecutor(),
instruction="""You are a calculator agent.
When given a mathematical expression, write and execute Python code to calculate the result.
Return only the final numerical result as plain text, without markdown or code blocks.
""",
description="Executes Python code to perform calculations.",
)
# Agent Interaction (Async)
async def call_agent_async(query):
# Session and Runner
session_service = InMemorySessionService()
session = await session_service.create_session(app_name=APP_NAME, user_id=USER_ID, session_id=SESSION_ID)
runner = Runner(agent=code_agent, app_name=APP_NAME, session_service=session_service)
content = types.Content(role='user', parts=[types.Part(text=query)])
print(f"\n--- Running Query: {query} ---")
final_response_text = "No final text response captured."
try:
# Use run_async
async for event in runner.run_async(user_id=USER_ID, session_id=SESSION_ID, new_message=content):
print(f"Event ID: {event.id}, Author: {event.author}")
# --- Check for specific parts FIRST ---
# has_specific_part = False
if event.content and event.content.parts and event.is_final_response():
for part in event.content.parts: # Iterate through all parts
if part.executable_code:
# Access the actual code string via .code
print(f" Debug: Agent generated code:\n```python\n{part.executable_code.code}\n```")
has_specific_part = True
elif part.code_execution_result:
# Access outcome and output correctly
print(f" Debug: Code Execution Result: {part.code_execution_result.outcome} - Output:\n{part.code_execution_result.output}")
has_specific_part = True
# Also print any text parts found in any event for debugging
elif part.text and not part.text.isspace():
print(f" Text: '{part.text.strip()}'")
# Do not set has_specific_part=True here, as we want the final response logic below
# --- Check for final response AFTER specific parts ---
text_parts = [part.text for part in event.content.parts if part.text]
final_result = "".join(text_parts)
print(f"==> Final Agent Response: {final_result}")
except Exception as e:
print(f"ERROR during agent run: {e}")
print("-" * 30)
# Main async function to run the examples
async def main():
await call_agent_async("Calculate the value of (5 + 7) * 3")
await call_agent_async("What is 10 factorial?")
# Execute the main async function
try:
nest_asyncio.apply()
asyncio.run(main())
except RuntimeError as e:
# Handle specific error when running asyncio.run in an already running loop (like Jupyter/Colab)
if "cannot be called from a running event loop" in str(e):
print("\nRunning in an existing event loop (like Colab/Jupyter).")
print("Please run `await main()` in a notebook cell instead.")
# If in an interactive environment like a notebook, you might need to run:
# await main()
else:
raise e # Re-raise other runtime errors该脚本使用 Google 的 Agent Development Kit（ADK）来创建一个通过编写并执行 Python 代码解决数学问题的智能体。它定义了一个被明确指示充当计算器的 LlmAgent，并为其配备了 built_in_code_execution 工具。主要逻辑位于 call_agent_async 函数中，该函数将用户的查询发送给智能体的 runner 并处理产生的事件。在该函数内部，一个异步循环遍历事件，打印生成的 Python 代码及其执行结果以便调试。代码仔细区分了这些中间步骤与包含数值答案的最终事件。最后，一个 main 函数使用两个不同的数学表达式运行该智能体，以展示其执行计算的能力。
企业搜索： 这段代码使用 Python 的 google.adk 库定义了一个 Google ADK 应用。它具体使用了 VSearchAgent，该智能体旨在通过搜索指定的 Vertex AI Search 数据存储来回答问题。代码初始化了一个名为"q2_strategy_vsearch_agent"的 VSearchAgent，提供了描述、使用的模型（"gemini-2.0-flash-exp"）以及 Vertex AI Search 数据存储的 ID。DATASTORE_ID 预计通过环境变量进行设置。随后为该智能体设置了一个 Runner，使用 InMemorySessionService 管理对话历史。定义了一个异步函数 call_vsearch_agent_async 用于与智能体交互。该函数接收一个查询，构建消息内容对象，并调用 runner 的 run_async 方法将查询发送给智能体。函数会在响应到达时将智能体的响应以流式方式回显到控制台。同时，它还会打印最终响应的信息，包括来自数据存储的任何来源归因。代码包含错误处理，用于在智能体执行期间捕获异常，并提供有关潜在问题（如数据存储 ID 不正确或缺少权限）的信息性消息。 还提供了另一个异步函数 run_vsearch_example，用于演示如何使用示例查询调用智能体。主执行块会检查是否设置了 DATASTORE_ID，然后使用 asyncio.run 运行示例。它还包含一个检查，用于处理代码在已有事件循环环境（如 Jupyter 笔记本）中运行的情况。
python
import asyncio
from google.genai import types
from google.adk import agents
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
import os
# --- Configuration ---
# Ensure you have set your GOOGLE_API_KEY and DATASTORE_ID environment variables
# For example:
# os.environ["GOOGLE_API_KEY"] = "YOUR_API_KEY"
# os.environ["DATASTORE_ID"] = "YOUR_DATASTORE_ID"
DATASTORE_ID = os.environ.get("DATASTORE_ID")
# --- Application Constants ---
APP_NAME = "vsearch_app"
USER_ID = "user_123" # Example User ID
SESSION_ID = "session_456" # Example Session ID
# --- Agent Definition (Updated with the newer model from the guide) ---
vsearch_agent = agents.VSearchAgent(
name="q2_strategy_vsearch_agent",
description="Answers questions about Q2 strategy documents using Vertex AI Search.",
model="gemini-2.0-flash-exp", # Updated model based on the guide's examples
datastore_id=DATASTORE_ID,
model_parameters={"temperature": 0.0}
)
# --- Runner and Session Initialization ---
runner = Runner(
agent=vsearch_agent,
app_name=APP_NAME,
session_service=InMemorySessionService(),
)
# --- Agent Invocation Logic ---
async def call_vsearch_agent_async(query: str):
"""Initializes a session and streams the agent's response."""
print(f"User: {query}")
print("Agent: ", end="", flush=True)
try:
# Construct the message content correctly
content = types.Content(role='user', parts=[types.Part(text=query)])
# Process events as they arrive from the asynchronous runner
async for event in runner.run_async(
user_id=USER_ID,
session_id=SESSION_ID,
new_message=content
):
# For token-by-token streaming of the response text
if hasattr(event, 'content_part_delta') and event.content_part_delta:
print(event.content_part_delta.text, end="", flush=True)
# Process the final response and its associated metadata
if event.is_final_response():
print() # Newline after the streaming response
if event.grounding_metadata:
print(f" (Source Attributions: {len(event.grounding_metadata.grounding_attributions)} sources found)")
else:
print(" (No grounding metadata found)")
print("-" * 30)
except Exception as e:
print(f"\nAn error occurred: {e}")
print("Please ensure your datastore ID is correct and that the service account has the necessary permissions.")
print("-" * 30)
# --- Run Example ---
async def run_vsearch_example():
# Replace with a question relevant to YOUR datastore content
await call_vsearch_agent_async("Summarize the main points about the Q2 strategy document.")
await call_vsearch_agent_async("What safety procedures are mentioned for lab X?")
# --- Execution ---
if __name__ == "__main__":
if not DATASTORE_ID:
print("Error: DATASTORE_ID environment variable is not set.")
else:
try:
asyncio.run(run_vsearch_example())
except RuntimeError as e:
# This handles cases where asyncio.run is called in an environment
# that already has a running event loop (like a Jupyter notebook).
if "cannot be called from a running event loop" in str(e):
print("Skipping execution in a running event loop. Please run this script directly.")
else:
raise e总体而言，这段代码为构建一个利用 Vertex AI Search、基于数据存储中的信息来回答问题的对话式 AI 应用提供了基础框架。它演示了如何定义智能体、设置运行器，并在流式传输响应的同时以异步方式与智能体交互。重点在于从特定的数据存储中检索和综合信息以回答用户查询。
Vertex 扩展： Vertex AI 扩展是一种结构化的 API 封装器，使模型能够连接外部 API，以进行实时数据处理和动作执行。扩展提供企业级的安全性、数据隐私和性能保证。它们可用于生成和运行代码、查询网站以及分析私有数据存储中的信息等任务。Google 为常见用例（如 Code Interpreter 和 Vertex AI Search）提供了预构建扩展，同时也支持自定义扩展。扩展的主要优势包括强大的企业级控制，以及与其他 Google 产品的无缝集成。扩展与函数调用的关键区别在于其执行方式：Vertex AI 会自动执行扩展，而函数调用则需要由用户或客户端手动执行。
回顾
是什么（What）
LLMs 是强大的文本生成器，但它们从根本上与外部世界脱节。它们的知识是静态的，受限于其训练数据，而且缺乏执行操作或检索实时信息的能力。这一内在限制使它们无法完成需要与外部 API、数据库或服务交互的任务。缺少连接这些外部系统的桥梁，它们在解决现实世界问题时的实用性将受到极大限制。
为什么（Why）
Tool Use 模式（常通过函数调用实现）为这一问题提供了标准化的解决方案。其工作方式是以 LLM 能理解的方式向其描述可用的外部函数或"工具"。基于用户请求，具备智能体能力的 LLM 随后可以决定是否需要工具，并生成结构化数据对象（如 JSON），指定调用哪个函数以及使用哪些参数。一个编排层会执行该函数调用，获取结果并将其反馈给 LLM。这样，LLM 就能在最终回复中纳入最新的外部信息或操作结果，从而有效地获得行动能力。
经验法则（Rule of Thumb）
当智能体需要突破 LLM 的内部知识并与外部世界互动时，请使用工具使用（Tool Use）模式。这对于需要实时数据（例如，查询天气、股票价格）、访问私有或专有信息（例如，查询公司数据库）、执行精确计算、运行代码，或在其他系统中触发操作（例如，发送电子邮件、控制智能设备）的任务至关重要。
工具使用（Tool Use）设计模式 
关键点
- 工具使用（函数调用）使智能体能够与外部系统交互并获取动态信息。
- 这涉及定义具备清晰描述和参数的工具，使 LLM 能够理解。
- LLM 决定何时使用工具，并生成结构化的函数调用。
- 智能体框架执行实际的工具调用，并将结果返回给 LLM。
- 工具使用对于构建能够执行现实世界操作并提供最新信息的智能体至关重要。
- LangChain 通过 @tool 装饰器简化工具定义，并提供 create_tool_calling_agent 和 AgentExecutor 用于构建使用工具的智能体。
- Google ADK 提供了许多非常实用的预构建工具，例如 Google Search、Code Execution 和 Vertex AI Search Tool。
总结
工具使用（Tool Use）模式是一个关键的架构原则，用于将大型语言模型的功能范围扩展到其固有的文本生成能力之外。通过赋予模型与外部软件和数据源交互的能力，这一范式使智能体能够执行操作、进行计算，并从其他系统检索信息。该过程涉及模型在判断有必要满足用户查询时，生成结构化请求以调用外部工具。诸如 LangChain、Google ADK 和 Crew AI 等框架提供了结构化的抽象和组件，以促进这些外部工具的集成。这些框架负责向模型暴露工具规格，并解析其后续的工具使用请求。这简化了能够在外部数字环境中交互并采取行动的复杂智能体系统的开发。
参考资料
- LangChain Documentation (Tools): python.langchain.com/docs/integr...
- Google Agent Developer Kit (ADK) Documentation (Tools): google.github.io/adk-docs/to...
- OpenAI Function Calling Documentation: platform.openai.com/docs/guides...
- CrewAI Documentation (Tools): docs.crewai.com/concepts/to...