在 MCP Toolbox 中使用 looker-delete-agent：删除 Looker Conversation Analytics Agent 的完整指南

在 MCP Toolbox 中使用 looker-delete-agent：删除 Looker Conversation Analytics Agent 的完整指南

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

本指南聚焦 MCP Toolbox 项目中looker-delete-agent工具，讲解如何让 LLM（大语言模型）通过 Looker Go SDK 删除 Looker Conversation Analytics Agent，涵盖工具调用格式、server.yaml配置方式、与 Looker source 的配合要点，并结合仓库源码剖析其参数校验、SDK 调用链与安全性设计。读完本文，你将能够在自己的 MCP Toolbox 配置中安全地接入并调用删除 Agent 的能力。

工具概述：为 LLM 提供的 Agent 删除能力

looker-delete-agent是 MCP Toolbox 为 Looker 集成提供的一组 Conversation Analytics（对话式分析）Agent 管理工具之一，其功能定义见 looker-delete-agent.md：

Thelooker-delete-agenttool allows LLMs to delete a Looker Agent using the Looker Go SDK.

在 MCP（Model Context Protocol）架构中，工具是暴露给 LLM 的可调用能力。LLM 通过 JSON-RPC 请求调用工具，MCP Toolbox 作为服务端接收请求、完成鉴权，并最终通过 Looker 官方 Go SDK（github.com/looker-open-source/sdk-codegen/go/sdk/v4）将操作落到 Looker 实例上。looker-delete-agent承担的就是其中"删除 Agent"这一破坏性操作。

从仓库中同目录的工具文档可以看出，该工具属于一个完整的 Agent 生命周期管理工具族，全部位于 docs/en/integrations/looker/tools/ 下，配套工具包括：

• looker-create-agent：创建 Agent；
• looker-get-agent：获取单个 Agent 详情；
• looker-list-agents：列出全部 Agent；
• looker-update-agent：更新 Agent；
• looker-delete-agent：删除 Agent（本文主题）。

在实际使用中，典型的生命周期通常是：先用looker-list-agents获取 Agent ID，再用looker-delete-agent按 ID 删除，或者在looker-get-agent确认目标后执行删除。

LLM 调用格式：工具参数与 JSON 请求

looker-delete-agent向 LLM 暴露的唯一参数是agent_id。原文档给出的调用示例为：

{ "name": "looker-delete-agent", "parameters": { "agent_id": "123" } }

字段含义如下：

• name：MCP 请求中调用的工具名，固定为looker-delete-agent；
• parameters.agent_id：要删除的 Looker Agent 的 ID，类型为字符串。该 ID 通常来自looker-list-agents或looker-get-agent的返回结果。

从源码看，agent_id参数在工具初始化时被定义为一个字符串参数，并带空字符串默认值：

agentIdParameter := parameters.NewStringParameter("agent_id", "The ID of the agent.", parameters.WithStringDefault(""))

也就是说，LLM 在决定删除哪个 Agent 之前，应当先通过列表类工具拿到目标agent_id，再发起删除调用。

配置方式：在 server.yaml 中声明工具

要在 MCP Toolbox 中使用该工具，必须在server.yaml中把它声明为一个kind: tool的配置项。原文档给出的示例配置如下：

kind: tool name: delete_agent type: looker-delete-agent source: my-looker-instance description: | Delete a Looker agent. - `agent_id` (string): The ID of the agent.

配置字段说明（即原文档的 Reference 表格）：

几点实践要点：

• name是工具在 MCP 会话中注册的别名，可以自行命名（如delete_agent），但type必须严格等于looker-delete-agent，否则不会被注册为该工具；
• source必须指向一个已定义的 Looker source（type: looker），工具运行时才会拿到可用的 Looker SDK 与连接配置；
• description会作为工具描述原样传给 LLM（见下方源码分析），因此应当写清楚用途与参数含义，帮助 LLM 正确调用。

字段校验的源码佐证

从 lookerdeleteagent.go 的源码结构看，配置解析与校验包含以下关键点：

1. 类型注册：包级init()中调用tools.Register("looker-delete-agent", newConfig)，若类型重复注册会直接 panic，确保工具类型全局唯一；
2. 必填字段：Config结构体为Type和Source两个字段打上了validate:"required"标签，YAML 解析时缺少任一字段都会报错；
3. description 非空校验：在Initialize中，如果cfg.Description == ""会返回错误description is required for tool ...，这正是上面表格中description标为必填的原因；
4. 未知字段拒绝：lookerdeleteagent_test.go 中的TestFailParseFromYaml用例验证了在配置中写入未知字段（如method）时，解析会报unknown field "method"错误，说明配置解析是严格的白名单模式。

对应的 YAML 解析测试用例（TestParseFromYaml）也验证了type: looker-delete-agent与source: my-instance会被正确解析为对应的Config结构，说明上述配置写法与源码实现完全一致。

配合 Looker Source：前置条件与配置示例

looker-delete-agent本身不关心连接细节，它依赖一个type: looker的 source 来获得 SDK 实例。Looker source 的完整说明见 source.md，其基本配置形如：

kind: source name: my-looker-source type: looker base_url: ${LOOKER_BASE_URL} client_id: ${LOOKER_CLIENT_ID:} client_secret: ${LOOKER_CLIENT_SECRET:} verify_ssl: ${LOOKER_VERIFY_SSL:true} timeout: 600s use_client_oauth: ${LOOKER_USE_CLIENT_OAUTH:false} show_hidden_models: ${LOOKER_SHOW_HIDDEN_MODELS:true} show_hidden_explores: ${LOOKER_SHOW_HIDDEN_EXPLORES:true} show_hidden_fields: ${LOOKER_SHOW_HIDDEN_FIELDS:true}

使用前提

• API 用户：Looker source 仅使用 API 鉴权，需要先在 Looker 中创建 API 用户（API3 key）获得client_id/client_secret；
• Conversational Analytics API：要使用 Agent 相关能力，需要在 Google Cloud 项目中启用geminidataanalytics.googleapis.com与cloudaicompanion.googleapis.com两个 API，并为 IAM 身份授予roles/looker.instanceUser、roles/cloudaicompanion.user、roles/geminidataanalytics.dataAgentStatelessUser角色，同时通过gcloud auth login --update-adc初始化 ADC 凭证；
• base_url 规范：格式如https://looker.example.com，不要带结尾/；本地部署的 Looker 可能需要附带 API 端口，例如https://looker.example.com:19999；
• 敏感信息：官方推荐用${ENV_NAME}环境变量替换方式注入client_id、client_secret等密钥，而不是硬编码进配置文件。

一个可运行的完整示例

将 source 与 tool 组合后，server.yaml的完整片段大致如下：

kind: source name: my-looker-instance type: looker base_url: ${LOOKER_BASE_URL} client_id: ${LOOKER_CLIENT_ID:} client_secret: ${LOOKER_CLIENT_SECRET:} verify_ssl: ${LOOKER_VERIFY_SSL:true} timeout: 600s use_client_oauth: ${LOOKER_USE_CLIENT_OAUTH:false} show_hidden_models: ${LOOKER_SHOW_HIDDEN_MODELS:true} show_hidden_explores: ${LOOKER_SHOW_HIDDEN_EXPLORES:true} show_hidden_fields: ${LOOKER_SHOW_HIDDEN_FIELDS:true} --- kind: tool name: delete_agent type: looker-delete-agent source: my-looker-instance description: | Delete a Looker agent. - `agent_id` (string): The ID of the agent.

源码级原理：一次删除操作如何被真正执行

理解配置之后，我们再从 lookerdeleteagent.go 出发，梳理一次调用在 MCP Toolbox 内部的处理链路。

1. 兼容 source 检查

工具定义了一个compatibleSource接口，要求 source 必须提供：

• UseClientAuthorization() bool：是否使用客户端授权；
• GetAuthTokenHeaderName() string：授权 token 所在 header 名称；
• LookerApiSettings() *rtl.ApiSettings：Looker SDK 运行所需的 API 设置；
• GetLookerSDK(context.Context, string) (*v4.LookerSDK, error)：基于访问 token 创建 Looker v4 SDK 实例。

在ValidateSource与Invoke中都会做类型断言，若配置的 source 不兼容，会返回类似invalid source for "looker-delete-agent" tool: source ... is not a compatible type的错误。这保证了工具只能与type: looker的 source 组合使用。

2. 参数提取与必填校验

Invoke中从params.AsMap()提取agent_id，并做显式校验：

if agentId == "" { return nil, util.NewClientServerError( fmt.Sprintf("%s operation: agent_id must be specified", t.Cfg.Type), http.StatusBadRequest, nil) }

对应测试 lookerdeleteagent_test.go 中TestInvokeValidation验证了：缺少agent_id时调用会失败并报错agent_id must be specified。也就是说，即使agent_id参数声明了空字符串默认值，真正执行删除前仍会强制要求非空值。

3. 底层 SDK 调用

校验通过后，工具调用 Looker v4 SDK 的DeleteAgent方法：

resp, err := sdk.DeleteAgent(agentId, "", source.LookerApiSettings())

其中第二个参数为 API 版本（此处传空字符串，使用默认版本）。返回的resp会原样作为工具结果返回给 LLM。

4. 错误处理与状态码映射

• 若 SDK 错误信息中包含status=401，则映射为 HTTP 401（未授权）；
• 其他错误走util.ProcessGeneralError统一处理。

5. 注解与 MCP Manifest

工具在Initialize阶段会强制注入两个 MCP 注解：

readOnlyHint := false destructiveHint := true annotations.ReadOnlyHint = &readOnlyHint annotations.DestructiveHint = &destructiveHint

即ReadOnlyHint恒为false、DestructiveHint恒为true。这些注解会通过 MCP Manifest（tools.Manifest{Description: cfg.Description, ...}）暴露给客户端，明确告知 LLM："这是一个具有破坏性的操作"。TestAnnotations用例对这两个注解的默认值做了断言（ReadOnlyHint == false、DestructiveHint == true），并从TestManifest用例可见，Manifest 中注册的参数正是agent_id。这提醒调用方：删除操作不可回滚，LLM 应在删除前再次确认agent_id的正确性。

实战使用流程与最佳实践

综合以上内容，推荐的使用流程如下：

1. 确认前置条件：按 source.md 完成 Looker API 用户创建、GCP API 启用与 IAM 授权，并设置好LOOKER_BASE_URL等环境变量；
2. 配置 source 与 tool：在server.yaml中声明type: looker的 source，以及type: looker-delete-agent的 tool（source字段指向该 source），description中写清agent_id参数说明；
3. 列出并确认目标：优先调用looker-list-agents获取 Agent ID 列表，结合looker-get-agent确认要删除的 Agent，避免误删；
4. 发起删除：调用looker-delete-agent，传入确认过的agent_id；
5. 处理结果：删除成功后返回 SDK 响应；若收到 401，需检查 Looker API 凭证与 IAM 权限是否有效。

需要注意的限制与风险：

• 该工具是破坏性操作（DestructiveHint为true），删除后无法恢复，配置时可利用description明确约束 LLM 的使用方式；
• agent_id必须非空，否则请求会被拒绝；
• 工具依赖 Looker 的 Conversation Analytics API，需要对应的 GCP API 与 IAM 角色（详见 source.md 的 Requirements 部分）；
• 若你的 Looker 使用自签名 SSL 证书，可将verify_ssl设为非true的值（例如false），否则建议保持true。

通过上述配置与调用链路的配合，你可以让 LLM 安全、受控地完成 Looker Conversation Analytics Agent 的删除操作，并借助looker-create-agent、looker-update-agent、looker-list-agents等配套工具，构建完整的 Agent 生命周期管理能力。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox