服务注册¶
Supported in ADKPython v1.34.0
通过为会话、制品、记忆以及 Agent2Agent (A2A) 任务存储注册自定义服务,扩展 ADK 运行时能力。注册自定义服务允许你将自己的后端系统和存储提供商集成到你的智能体中。
你可以使用以下任一方法注册自定义服务:
services.yaml:适用于使用简单构造函数实例化的服务的 YAML 配置文件。services.py:适用于需要自定义初始化或复杂逻辑的服务的 Python 脚本。
使用 services.yaml 注册服务¶
使用 services.yaml 或 services.yml 文件注册可以通过简单构造函数(例如 MyService(uri="..."))实例化的服务。将此文件放置在智能体目录(用于 adk run)或智能体根目录(用于 adk web 和 adk api_server)中。
在 services.yaml 中定义你的自定义服务:
services:
- scheme: mysession
type: session
class: my_custom_package.modules.MyCustomSessionService
- scheme: myartifact
type: artifact
class: my_custom_package.storage.MyCustomArtifactService
- scheme: mymemory
type: memory
class: my_custom_package.modules.MyCustomMemoryService
- scheme: mytaskstore
type: task_store
class: my_custom_package.tasks.MyCustomTaskStore
services.yaml 文件支持以下属性:
scheme:触发自定义服务的 URI Scheme(例如mysession://)。type:服务类型,可以是session、artifact、memory或task_store。class:服务实现类的完整限定类名。
使用 services.py 注册服务¶
对于复杂的初始化或需要对服务创建过程进行更多控制的情况,可以使用放置在与 services.yaml 相同位置的 services.py 文件。
在 services.py 中注册自定义 session、artifact 和 memory 服务:
from google.adk.cli.service_registry import get_service_registry
from my_custom_package.modules import MyCustomSessionService
from my_custom_package.storage import MyCustomArtifactService
from my_custom_package.memory import MyCustomMemoryService
def my_session_factory(uri: str, **kwargs):
# 在此处添加你的自定义逻辑。
return MyCustomSessionService(uri=uri, **kwargs)
def my_artifact_factory(uri: str, **kwargs):
"""用于实例化自定义制品服务的工厂函数。"""
return MyCustomArtifactService(uri=uri, **kwargs)
def my_memory_factory(uri: str, **kwargs):
"""用于实例化自定义记忆服务的工厂函数。"""
return MyCustomMemoryService(uri=uri, **kwargs)
# 获取注册表。
registry = get_service_registry()
# 注册会话、制品和记忆服务。
registry.register_session_service("mysession", my_session_factory)
registry.register_artifact_service("myartifact", my_artifact_factory)
registry.register_memory_service("mymemory", my_memory_factory)
示例脚本执行以下任务:
- 导入
get_service_registry以获取服务注册表实例。 - 定义接收 URI 和关键字参数并返回自定义服务实例的工厂函数(例如
my_session_factory)。 - 使用
register_session_service、register_artifact_service和register_memory_service将工厂函数注册到所需的 Scheme(例如mysession)。
加载服务¶
当你使用 ADK 命令行工具(adk run、adk web 或 adk api_server)运行智能体时,ADK 会自动发现并从 services.yaml(或 services.yml)及 services.py 中加载自定义服务。
发现位置¶
ADK 根据你运行的命令定位配置文件:
adk run:在智能体目录中发现服务文件。adk web和adk api_server:在传递给命令的智能体根目录中发现服务文件。
加载顺序与优先级¶
当目标目录中同时存在 services.yaml 和 services.py 时:
- 加载顺序:ADK 首先加载
services.yaml,然后加载services.py。 - 优先级:如果两个文件中定义了具有相同 Scheme 的服务,则以
services.py中的定义为准。