Apps: workflow management class

Supported in ADKPython v1.14.0

The App class is a top-level container for an entire Agent Development Kit (ADK) agent workflow. It is designed to manage the lifecycle, configuration, and state for a collection of agents grouped by a root agent. The App class separates the concerns of an agent workflow's overall operational infrastructure from individual agents' task-oriented reasoning.

App 类是整个 Agent Development Kit (ADK) 智能体工作流的顶层容器。它旨在管理由 根智能体 分组的一组智能体的生命周期、配置和状态。App 类将智能体工作流的总体操作基础设施与各个智能体的面向任务的推理分离开来。

Defining an App object in your ADK workflow is optional and changes how you organize your agent code and run your agents. From a practical perspective, you use the App class to configure the following features for your agent workflow:

在您的 ADK 工作流中定义 App 对象是可选的，它改变了您组织智能体代码和运行智能体的方式。从实际角度来看，您使用 App 类为您的智能体工作流配置以下功能：

在您的 ADK 工作流中定义 App 对象是可选的，它改变了您组织智能体代码和运行智能体的方式。从实际角度来看，您使用 App 类为您的智能体工作流配置以下功能：

• Context caching
• Context compression
• Agent resume
• Plugins

This guide explains how to use the App class for configuring and managing your ADK agent workflows.

本指南解释了如何使用 App 类来配置和管理您的 ADK 智能体工作流。

Note

此页面重点介绍 Python。其他语言的示例即将推出。

Purpose of App Class

App 类的目的

The App class addresses several architectural issues that arise when building complex agentic systems:

App 类解决了在构建复杂智能体系统时出现的几个架构问题：

Purpose of App Class

App 类的目的

The App class addresses several architectural issues that arise when building complex agentic systems:

App 类解决了在构建复杂智能体系统时出现的几个架构问题：

• Centralized configuration: Provides a single, centralized location for managing shared resources like API keys and database clients, avoiding the need to pass configuration down through every agent.
• Lifecycle management: The App class includes on startup and on shutdown hooks, which allow for reliable management of persistent resources such as database connection pools or in-memory caches that need to exist across multiple invocations.
• State scope: It defines an explicit boundary for application-level state with an app:* prefix making the scope and lifetime of this state clear to developers.

• Unit of deployment: The App concept establishes a formal deployable unit, simplifying versioning, testing, and serving of agentic applications.

• 集中配置: 提供单一的、集中式位置来管理共享资源(如 API 密钥和数据库客户端),避免了需要将配置传递到每个智能体的需求。

• 生命周期管理: App 类包括 启动时 和 关闭时 挂钩,这些挂钩允许可靠地管理持久资源(如数据库连接池或内存缓存),这些资源需要在多次调用中存在。
• 状态范围: 它使用 app:* 前缀为应用程序级别状态定义明确的边界,使此状态的范围和生命周期对开发人员清晰。
• 部署单元: App 概念建立了一个正式的可部署单元,简化了智能体应用程序的版本控制、测试和服务。

Define an App object

定义 App 对象

The App class is used as the primary container of your agent workflow and contains the root agent of the project. The root agent is the container for the primary controller agent and any additonal sub-agents.

App 类用作智能体工作流的主要容器,并包含项目的根智能体。根智能体是主控制器智能体和任何附加子智能体的容器。

Define app with root agent

使用根智能体定义应用程序

Create a root agent for your workflow by creating a subclass from the Agent base class. Then define an App object and configure it with the root agent object and optional features, as shown in the following sample code:

通过从 Agent 基类创建子类为工作流创建 根智能体。然后定义一个 App 对象,并使用 根智能体 对象和可选功能对其进行配置,如以下示例代码所示:

agent.py

from google.adk.agents.llm_agent import Agent
from google.adk.apps import App

root_agent = Agent(
    model='gemini-2.5-flash',
    name='greeter_agent',
    description='An agent that provides a friendly greeting.',
    instruction='Reply with Hello, World!',
)

app = App(
    name="agents",
    root_agent=root_agent,
    # Optionally include App-level features:
    # plugins, context_cache_config, resumability_config
)

Recommended: Use app variable name

In your agent project code, set your App object to the variable name app so it is compatible with the ADK command line interface runner tools.

Run your App agent

运行您的应用程序智能体

You can use the Runner class to run your agent workflow using the app parameter, as shown in the following code sample:

main.py

import asyncio
from dotenv import load_dotenv
from google.adk.runners import InMemoryRunner
from agent import app # import code from agent.py

load_dotenv() # load API keys and settings
# Set a Runner using the imported application object
runner = InMemoryRunner(app=app)

async def main():
    try:  # run_debug() requires ADK Python 1.18 or higher:
        response = await runner.run_debug("Hello there!")

    except Exception as e:
        print(f"An error occurred during agent execution: {e}")

if __name__ == "__main__":
    asyncio.run(main())

Version requirement for Runner.run_debug()

The Runner.run_debug() command requires ADK Python v1.18.0 or higher. You can also use Runner.run(), which requires more setup code. For more details, see the

Run your App agent with the main.py code using the following command:

python main.py

Next steps

下一步

For a more complete sample code implementation, see the Hello World App code example.

有关更完整的示例代码实现，请参阅 Hello World 应用程序 代码示例。