Skip to content

Resume stopped agents

恢复已停止的智能体

Supported in ADKPython v1.14.0

An ADK agent's execution can be interrupted by various factors including dropped network connections, power failure, or a required external system going offline. The Resume feature of ADK allows an agent workflow to pick up where it left off, avoiding the need to restart the entire workflow. In ADK Python 1.16 and higher, you can configure an ADK workflow to be resumable, so that it tracks the execution of the workflow and then allows you to resume it after an unexpected interruption.

ADK 智能体的执行可能会因各种因素而中断,包括网络连接断开、电源故障或必需的外部系统离线。ADK 的恢复功能允许智能体工作流从中断的地方继续,避免了重新启动整个工作流的需要。在 ADK Python 1.16 及更高版本中,您可以配置 ADK 工作流为可恢复的,以便它跟踪工作流的执行,然后允许您在意外中断后恢复它。

This guide explains how to configure your ADK agent workflow to be resumable. If you use Custom Agents, you can update them to be resumable. For more information, see Add resume to custom Agents.

本指南说明了如何将您的 ADK 智能体工作流配置为可恢复的。如果您使用自定义智能体,可以更新它们以使其可恢复。有关更多信息,请参阅为自定义智能体添加恢复功能。

Add resumable configuration

添加可恢复配置

Enable the Resume function for an agent workflow by applying a Resumability configuration to the App object of your ADK workflow, as shown in the following code example:

通过将恢复能力配置应用到 ADK 工作流的 App 对象,为智能体工作流启用恢复功能,如以下代码示例所示:

app = App(
    name='my_resumable_agent',
    root_agent=root_agent,
    # Set resumability config to enable resumability.
    # 设置可恢复性配置以启用可恢复性。
    resumability_config=ResumabilityConfig(
        is_resumable=True,
    ),
)

Caution: Long Running Functions, Confirmations, Authentication

注意:长期运行函数、确认、身份验证

For agents that use Long Running Functions, Confirmations, or Authentication requiring user input, adding a resumable confirmation changes how these features operate. For more information, see documentation for those features.

对于使用长期运行函数、确认或身份验证需要用户输入的智能体,添加可恢复确认会更改这些功能的运行方式。有关更多信息,请参阅这些功能的文档。

Note: Custom Agents

注意:自定义智能体

Resume is not supported by default for Custom Agents. You must update the agent code for a Custom Agent to support the Resume feature. For information on modifying Custom Agents to support incremental resume functionality, see Add resume to custom Agents.

默认情况下,自定义智能体不支持恢复功能。您必须更新自定义智能体的智能体代码以支持恢复功能。有关修改自定义智能体以支持增量恢复功能的信息,请参阅为自定义智能体添加恢复功能。

Resume a stopped workflow

恢复已停止的工作流

When an ADK workflow stops execution you can resume the workflow using a command containing the Invocation ID for the workflow instance, which can be found in the Event history of the workflow. Make sure the ADK API server is running, in case it was interruted or powered off, and then run the following command to resume the workflow, as shown in the following API request example.

当 ADK 工作流停止执行时,您可以使用包含工作流实例的调用 ID 的命令恢复工作流,该调用 ID 可以在工作流的事件历史中找到。确保 ADK API 服务器正在运行,以防它被中断或关闭,然后运行以下命令以恢复工作流,如以下 API 请求示例所示。

# restart API server if needed:
# 如果需要,重新启动 API 服务器:
adk api_server my_resumable_agent/

# resume agent:
# 恢复智能体:
curl -X POST http://localhost:8000/run_sse \
 -H "Content-Type: application/json" \
 -d '{
   "app_name": "my_resumable_agent",
   "user_id": "u_123",
   "session_id": "s_abc",
   "invocation_id": "invocation-123",
 }'

You can also resume a workflow using the Runner object Run Async method, as shown below:

您也可以使用 Runner 对象的 Run Async 方法恢复工作流,如下所示:

runner.run_async(user_id='u_123', session_id='s_abc', 
    invocation_id='invocation-123')

# When new_message is set to a function response,
# we are trying to resume a long running function.
# 当 new_message 设置为函数响应时,
# 我们正尝试恢复长期运行的函数。

Custom Agents

自定义智能体

To enable the Resume feature for Custom Agents, you must update the agent code to track the execution state. The key steps are:

要为自定义智能体启用恢复功能,您必须更新智能体代码以跟踪执行状态。关键步骤是:

  1. Import Required Classes: Import ResumabilityConfig from google.adk.apps.app and Resumable from google.adk.agents. 导入必需的类:从 google.adk.apps.app 导入 ResumabilityConfig,从 google.adk.agents 导入 Resumable。
  2. Configure Agent as Resumable: Set the is_resumable parameter to True in the ResumabilityConfig. 将智能体配置为可恢复:在 ResumabilityConfig 中将 is_resumable 参数设置为 True。
  3. Track Execution State: Implement state tracking within your agent's run method to capture where the agent was interrupted. 跟踪执行状态:在智能体的 run 方法中实现状态跟踪,以捕获智能体被中断的位置。

The following example shows a simple Custom Agent that implements the Resume feature:

以下示例显示了一个实现恢复功能的简单自定义智能体:

from google.adk.agents import Agent, Resumable
from google.adk.apps.app import App, ResumabilityConfig

@Resumable
class MyResumableAgent(Agent):
    async def run_async(self, invocation_context: InvocationContext):
        # Track execution state
        # 跟踪执行状态
        execution_state = invocation_context.session.state.get("execution_step", 0)

        if execution_state == 0:
            # First step of the workflow
            # 工作流的第一步
            yield Event(
                actions=EventActions(
                    state_delta={"execution_step": 1}
                ),
                content=types.Content(
                    parts=[types.Part(text="Starting first step...")]
                )
            )
        elif execution_state == 1:
            # Resume from second step
            # 从第二步恢复
            yield Event(
                actions=EventActions(
                    state_delta={"execution_step": 2}
                ),
                content=types.Content(
                    parts=[types.Part(text="Continuing from second step...")]
                )
            )

# Configure the app with resumability
# 使用可恢复性配置应用
app = App(
    name='my_resumable_agent',
    root_agent=MyResumableAgent(...),
    resumability_config=ResumabilityConfig(
        is_resumable=True,
    ),
)

Limitations

限制

The Resume feature has the following limitations:

恢复功能具有以下限制:

  • State Persistence: The Resume feature relies on the persistence mechanism of the SessionService being used. If the SessionService is InMemorySessionService, state will be lost when the application restarts. 状态持久性:恢复功能依赖于所使用的 SessionService 的持久性机制。如果 SessionService 是 InMemorySessionService,则应用程序重启时状态将丢失。
  • Long Running Functions: When resuming from a long running function, the function will restart from the beginning. 长期运行函数:从长期运行的函数恢复时,该函数将从头重新开始。
  • External State: Changes made to external systems (databases, APIs, etc.) are not automatically rolled back when resuming. 外部状态:对外部系统(数据库、API 等)所做的更改在恢复时不会自动回滚。