ADK 实战：使用 ApplicationIntegrationToolset 构建 Jira 问题管理 Agent

ADK 实战使用 ApplicationIntegrationToolset 构建 Jira 问题管理 Agent【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python导读本文围绕 ADK 仓库中的官方示例 application_integration_agent 展开讲解如何通过ApplicationIntegrationToolset将 Google Cloud 的 Integration Connectors 能力注入 ADK Agent使大模型能够直接对 Jira 中的 Issues、Projects 等实体执行增删改查操作。读完本文你将掌握该 Toolset 的核心参数含义、连接配置流程、Agent 代码编写方式以及基于 ADK CLI 的运行与交互方法并能将同一套模式迁移到其他受支持的连接器上。示例概览一个管理 Jira 问题的 ADK Agent该示例的目标非常明确让用户用自然语言管理 Jira 上的问题Issue。示例代码位于 contributing/samples/integrations/application_integration_agent/目录结构如下contributing/samples/integrations/application_integration_agent/ ├── README.md # 示例说明文档 ├── __init__.py # 包入口导出 agent 模块 └── agent.py # Agent 核心代码从源码结构看这是一个“代码优先code-first”的最小示例只用一个 Python 文件就完成了 Agent 的定义没有额外的 YAML 配置或会话配置文件。__init__.py仅做from . import agent的导入导出保证该目录可以被 ADK 作为独立示例包加载。前置条件准备 Jira 集成连接与环境变量1. 在 Google Cloud 中创建 Integration Connection要使用ApplicationIntegrationToolset第一步是在 Google Cloud 中完成以下准备在 Google Cloud 项目中启用并配置 Integration Connectors使其能够与你的 Jira 实例通信创建一条指向 Jira 的 Connection连接器并完成 Jira 实例地址、认证凭据等配置记录这条连接的三个关键信息Connection Name连接名称、Project ID所在 GCP 项目 ID和Location连接所在区域如 us-central1。这三个值将作为后续 Agent 运行时连接 Jira 的依据缺一不可。2. 配置环境变量在agent.py所在目录或你已有的环境变量文件中创建.env文件写入以下内容CONNECTION_NAMEYOUR_JIRA_CONNECTION_NAME CONNECTION_PROJECTYOUR_GOOGLE_CLOUD_PROJECT_ID CONNECTION_LOCATIONYOUR_CONNECTION_LOCATION示例代码在模块加载时通过load_dotenv()读取该文件因此必须保证.env与agent.py位于同一目录或由load_dotenv能够找到的位置否则 Agent 会在创建 Toolset 时因缺少配置而失败。代码解析agent.py 逐段拆解完整的示例代码位于 agent.py其核心逻辑分为三步加载环境变量、创建 Toolset、组装 Agent。第一步加载环境变量from dotenv import load_dotenv # Load environment variables from .env file load_dotenv() connection_name os.getenv(CONNECTION_NAME) connection_project os.getenv(CONNECTION_PROJECT) connection_location os.getenv(CONNECTION_LOCATION)这里使用了python-dotenv的load_dotenv()将.env中的三个变量读入进程环境随后通过os.getenv取出。注意此处读取的是字符串如果环境变量缺失os.getenv会返回NoneToolset 构造时会因参数不合法而报错因此务必保证配置完整。第二步实例化 ApplicationIntegrationToolsetjira_toolset ApplicationIntegrationToolset( projectconnection_project, locationconnection_location, connectionconnection_name, entity_operations{Issues: [], Projects: []}, tool_name_prefixjira_issue_manager, )这是整个示例的灵魂。ApplicationIntegrationToolset导入自google.adk.tools.application_integration_tool见 application_integration_tool/init.py它会根据指定的 Integration 或 Connection 资源**自动生成一组工具Tool**供 Agent 调用。这里的关键参数project/location/connection分别对应 .env 中配置的 GCP 项目 ID、区域和 Jira 连接名用于定位云端的连接资源entity_operations{Issues: [], Projects: []}声明要暴露的实体及其操作。值传空列表表示该实体支持的全部操作都暴露给 Agent从源码注释“empty list for actions means all operations on the entity are supported”可以确认这一点。也就是说示例允许 Agent 对 Jira 的 Issues 和 Projects 两个实体执行其连接器支持的所有操作例如 LIST列出、CREATE创建、UPDATE更新、GET获取详情、DELETE删除tool_name_prefixjira_issue_manager生成工具时统一加上的名称前缀。从源码看最终生成的工具名形如jira_issue_manager_list_Issues、jira_issue_manager_create_Issues等见 integration_client.py 中 operationId 的拼接逻辑。第三步创建 LlmAgent 并挂载工具root_agent LlmAgent( nameIssue_Management_Agent, instruction..., tools[jira_toolset], )Agent 名为Issue_Management_Agent直接将整个 Toolset 作为tools传入。系统提示词instruction中包含了几条值得借鉴的工程化指引基于工具结果作答要求模型严格依据工具返回的数据进行回答并允许按用户要求做格式化出错自愈如果工具调用返回错误模型应理解错误原因并尝试修复如补齐缺失的参数、从用户请求中推断默认值后重试自行完成数学运算如果用户请求涉及 count、max、min 等计算先调用工具取数再在回答中给出计算结果。这三条提示词显著提升了 Agent 在多轮工具调用场景下的鲁棒性是生产级提示词设计中“让模型自我纠错、自我补全”的典型写法。ApplicationIntegrationToolset 参数全解结合 application_integration_toolset.py 的构造函数该 Toolset 支持两类资源模式参数如下参数类型说明projectstr必填GCP 项目 IDlocationstr必填GCP 区域如us-central1integrationstr要对接的 Application Integration 名称与 connection 模式二选一triggerslist[str]Integration 的触发器列表如[api_trigger/test_trigger]connection_template_overridestr覆盖默认ExecuteConnection集成名称connectionstrIntegration Connector 连接名与 integration 模式二选一entity_operationsdict[str, list[str]]实体到操作列表的映射如{Issues: [LIST, CREATE]}空列表表示全部操作actionslist[str]连接支持的 action 列表tool_name_prefixstr生成工具的名称前缀tool_instructionsstr追加到工具描述中的说明文字可引导模型正确使用工具service_account_jsonstr服务账号 JSON 字符串不传时使用默认凭据auth_scheme/auth_credentialAuthScheme / AuthCredential自定义认证方案与凭据用于 OAuth 等场景credential_keystr认证凭据的 key配合AuthConfig使用tool_filterToolPredicate / list[str]对生成的工具进行过滤可传谓词或工具名列表构造函数在初始化时会对入参做校验必须提供integration或者同时提供connection与entity_operations或actions否则抛出ValueError见 application_integration_toolset.py 与 application_integration_toolset.py。从源码还可以看到工具集的导出在get_tools()中进行application_integration_toolset.py连接模式connection下工具在初始化时即被解析为IntegrationConnectorTool列表get_tools()负责按tool_filter过滤并在存在交换后的认证凭据exchanged_auth_credential时克隆出携带新凭据的工具副本。底层原理工具是如何从连接“长”出来的理解示例背后的实现能帮你更准确地推断它能做什么、不能做什么。该 Toolset 的完整调用链如下1. ConnectionsClient拉取连接元数据ConnectionsClient 负责与connectors.googleapis.com通信get_connection_details()拉取连接的服务目录serviceName、主机host与authOverrideEnabled标志get_entity_schema_and_operations(entity)通过connectionSchemaMetadata:getEntityType获取指定实体的 JSON Schema 与可用操作并轮询操作结果直到完成_poll_operationget_action_schema(action)通过connectionSchemaMetadata:getAction获取 action 的输入/输出 Schema。2. IntegrationClient组装 OpenAPI SpecIntegrationClient 的get_openapi_spec_for_connection()基于上述 Schema 动态组装出一份 OpenAPI 3.0.1 规范spec。实体操作被映射为LIST_ENTITIES、GET_ENTITY、CREATE_ENTITY、UPDATE_ENTITY、DELETE_ENTITYaction 被映射为EXECUTE_ACTION/EXECUTE_QUERY每个操作生成一个 POST 端点operationId 形如{tool_name_prefix}_{operation}_{entity}。这份 spec 会被交给 ADK 的 OpenAPI 解析管线处理。3. IntegrationConnectorTool执行时的包装器最终暴露给模型的是 IntegrationConnectorTool它包装了一个RestApiTool在每次调用时通过ToolAuthHandler准备认证凭据若认证处于 pending 状态则返回“需要授权”的提示把connection_name、service_name、host、entity、operation、action等连接上下文注入请求参数若连接启用了 OAuth 动态认证则将 access token 写入dynamic_auth_config最终委托内部的RestApiTool.call()完成真实 HTTP 请求。因此模型看到的是jira_issue_manager_list_Issues这类语义清晰的工具名而底层执行的是带完整连接上下文的 REST 调用这既保证了声明与执行的解耦也让模型更容易做出正确的工具选择。运行与交互从安装到提问安装依赖示例依赖google-adk与python-dotenv。确认环境已安装 ADK 后如缺少python-dotenv可一并安装。启动 Agent在 ADK 仓库根目录下用 ADK CLI 运行该示例adk run contributing/samples/integrations/application_integration_agentadk run会加载该目录下的agent.py通过__init__.py找到root_agent并以交互式命令行界面启动 Agent。交互提问启动后直接输入与 Jira 问题管理相关的自然语言指令即可例如Can you list me all the issues ?—— 列出所有 IssueCan you list me all the projects ?—— 列出所有 ProjectCan you create an issue: Bug in product XYZ in project ABC ?—— 在项目 ABC 中创建一条 Issue。得益于系统提示词中的“出错自愈”与“自行计算”策略你还可以进一步追问数量、最大值等衍生问题Agent 会先调用工具取数再给出结论而不是凭空回答。注意事项与限制网络与凭据是硬前提该示例在导入阶段就会调用 Integration Connectors API。仓库的示例加载测试 test_samples.py 明确将integrations/application_integration_agent列入SKIP_LOAD原因是“在 import 时调用 Integration Connectors API”。这意味着离线环境、未配置 GCP 凭据或未创建连接时导入即失败必须在具备有效凭据与已创建连接的环境下运行。实体操作以连接器实际支持为准entity_operations传空列表虽表示“全部操作”但最终暴露哪些操作由云端连接器的connectionSchemaMetadata决定如需精确控制可显式列出操作如{Issues: [LIST, CREATE]}。认证方式未显式传入service_account_json时Toolset 使用应用默认凭据ADC访问云端资源Scope 为cloud-platform如需在 CI/CD 等场景中显式指定身份可通过service_account_json传入服务账号 JSON见 application_integration_toolset.py。工具名长度限制IntegrationConnectorTool的 docstring 提示工具名需符合 Gemini 函数命名规范长度小于 64 字符因此tool_name_prefix不宜过长。延伸把同一模式复用到其他连接器本示例虽然以 Jira 为对象但ApplicationIntegrationToolset的机制是通用的只要你在 Google Cloud 中配置了任意受支持的 Integration Connectors 连接并把connection、entity_operations、actions换成对应的实体与操作就能让 ADK Agent 具备与该 SaaS 系统对话的能力。仓库中还提供了使用actions而非实体操作的变体示例 integration_connector_euc_agent 供对照学习其单元测试覆盖见 test_application_integration_toolset.py 与 test_connections_client.py。小结本文从官方示例 application_integration_agent 出发完整覆盖了 Jira 连接准备、环境变量配置、Agent 代码编写、Toolset 参数语义、底层工具生成原理以及adk run运行交互的全流程。核心要点可以概括为一个已配置的 Integration Connection 加上三行环境变量再用entity_operations声明暴露的实体操作即可让 LLM 通过 ADK 安全、可控地操作外部业务系统。掌握这套模式后你可以将其扩展到任意受支持的连接器快速构建企业级“自然语言操作 SaaS 系统”的 Agent 应用。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考