Gemini CLI A2A Server 解析：将 Gemini CLI 暴露为 A2A 智能体服务

Gemini CLI A2A Server 解析将 Gemini CLI 暴露为 A2A 智能体服务【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli本文围绕 Gemini CLI 仓库中packages/a2a-server包的官方说明文档GEMINI.md展开结合该包的源码实现完整讲解这个实验性 Agent-to-AgentA2A服务器包的架构组成、HTTP 路由设计、Agent Card 声明、任务事件模型、GCS 持久化机制以及并发任务间的环境隔离与安全控制。读完后你将掌握如何以gemini-cli-a2a-server二进制启动该服务、如何通过 REST 端点创建任务与执行命令、如何验证包内测试以及其底层任务状态机与工具确认tool confirmation流程的实现细节。1. 这个包是什么实验性的 A2A 服务器根据 GEMINI.md 的定义packages/a2a-server是一个实验性的 Agent-to-AgentA2A服务器其核心目标是通过 HTTP 暴露 Gemini CLI 的能力用于智能体之间的通信inter-agent communication。README.md 进一步强调All code in this package is experimental and under active development本包所有代码均为实验性质且处于积极开发中。从 package.json 可以确认该包的工程定位与关键依赖项内容说明包名google/gemini-cli-a2a-servernpm 工作区包可执行入口bin:gemini-cli-a2a-server→dist/a2a-server.mjs二进制入口核心依赖a2a-js/sdk0.3.11、express5.1.0A2A 协议 SDK 与 Web 框架持久化依赖google-cloud/storage7.19.0、tar7.5.8GCS 存储与归档日志依赖winston3.17.0日志输出运行环境node 20引擎约束需要说明一个方向性问题Gemini CLI 本身已经支持作为客户端通过 A2A 协议连接远程子智能体见 docs/core/remote-agents.md 中kind: remote的 Markdown 智能体定义。而a2a-server包提供的是反向能力——把 Gemini CLI 自身包装成 A2A 服务端的 Coder Agent供其他智能体系统通过 HTTP 调用。2. 包架构目录职责与共享类型GEMINI.md 给出的目录结构是理解全包的骨架结合源码中实际存在的文件各目录职责如下目录职责文档定义 源码印证src/agent/A2A 交互的 Agent 会话管理。核心是 task.ts 中的Task类任务状态机、工具调用调度、事件发布以及executor.ts、race-condition.test.ts等src/commands/A2A 服务器二进制使用的 CLI 命令定义。包含command-registry.ts命令注册表、init.ts、memory.ts、restore.ts等src/config/服务器配置。config.ts环境加载、按任务隔离process.env、settings.ts、extension.tssrc/http/HTTP 服务器与路由处理。server.ts入口、app.tsExpress 应用组装、requestStorage.tssrc/persistence/会话与状态持久化。gcs.ts中的GCSTaskStore与NoOpTaskStoresrc/utils/共享工具函数日志logger.ts、路径path_utils.ts等src/types.ts共享类型定义CoderAgentEvent事件枚举、AgentSettings、持久化元数据辅助函数等其中 types.ts 定义了贯穿全包的CoderAgent 事件模型——A2A 状态更新事件的metadata.coderAgent字段就使用这套类型。事件枚举CoderAgentEvent包含七类事件ToolCallConfirmationEventtool-call-confirmation请求一个或多个工具调用的确认ToolCallUpdateEventtool-call-update更新一个或多个工具调用的状态TextContentEventtext-content任务文本进度更新StateChangeEventstate-change任务执行状态变化StateAgentSettingsEventagent-settings用户发起智能体的设置事件含workspacePath、可选autoExecute、isTrustedThoughtEventthought智能体的思考内容subjectdescriptionCitationEventcitation引用内容。此外TaskMetadata类型描述了任务元数据的完整形状id、contextId、taskStateA2A SDK 的TaskState、model、各 MCP 服务器状态与其工具清单name/description/parameterSchema以及availableTools列表——这正是后文/tasks/metadata端点返回的内容。持久化状态通过METADATA_KEY__persistedState写入任务 metadata由getPersistedState/setPersistedState读写结构为{ _agentSettings, _taskState }。3. 启动流程从二进制入口到本地监听GEMINI.md 指出二进制入口为gemini-cli-a2a-server。运行链路为server.js编译自 server.ts判断自己是主模块后调用main()main()再委托给 app.ts 中的createApp()与监听逻辑L406-L434。server.ts还注册了uncaughtException处理器将未捕获异常记入日志并以退出码 1 终止进程。createApp()的启动序列app.ts值得逐步拆解因为它决定了服务器的工作目录、信任边界与任务存储确定工作区根目录setTargetDir(undefined)解析出 workspaceRoot随后process.chdir(workspaceRoot)把全局工作目录切换到该路径。文件夹信任检查先用临时设置加载调用checkPathTrust({ path: workspaceRoot, isFolderTrustEnabled, isHeadless })得到isTrusted逻辑与 CLI 自身的初始信任检查保持一致。环境变量白名单loadEnvironment()返回的.env变量中只有白名单内的键会被写回process.env防止凭证泄漏CODER_AGENT_PORT # 监听端口 CODER_AGENT_WORKSPACE_PATH # 工作区路径部分命令必需 GCS_BUCKET_NAME # 启用 GCS 任务持久化的桶名 LOG_LEVEL # 日志级别 GOOGLE_APPLICATION_CREDENTIALS GOOGLE_CLOUD_PROJECT GEMINI_CLI_USE_COMPUTE_ADC加载设置、扩展与核心配置loadSettings→loadExtensions→loadConfig(settings, new SimpleExtensionLoader(extensions), a2a-server, isTrusted, workspaceRoot)。可选 Git 检查点若config.getCheckpointingEnabled()为真则构造并初始化GitService用于文件编辑工具的回滚检查点。选择任务存储环境变量GCS_BUCKET_NAME存在时使用GCSTaskStoreexecutor 侧NoOpTaskStorehandler 侧见 GCS 分支注释否则使用InMemoryTaskStore两侧共用同一实例。组装请求处理器new DefaultRequestHandler(coderAgentCard, taskStoreForHandler, agentExecutor)其中agentExecutor是包内自实现的CoderAgentExecutor。监听逻辑main()app.tsconst port Number(process.env[CODER_AGENT_PORT] || 0); const server expressApp.listen(port, localhost, () { ... });即服务器只绑定localhost端口取自CODER_AGENT_PORT缺省为 0由 OS 分配随机端口。监听成功后调用updateCoderAgentCardUrl(actualPort)把 Agent Card 的url更新为实际端口并打印 Agent Card 地址http://localhost:port/.well-known/agent-card.json。4. Agent Card服务端自我描述A2A 协议要求智能体通过 Agent Card 自我声明。app.ts 中硬编码的coderAgentCard是理解该服务对外人格的关键{ name: Gemini SDLC Agent, description: An agent that generates code based on natural language instructions and streams file outputs., protocolVersion: 0.3.0, version: 0.0.2, capabilities: { streaming: true, pushNotifications: false, stateTransitionHistory: true }, defaultInputModes: [text], defaultOutputModes: [text], skills: [ { id: code_generation, name: Code Generation, description: Generates code snippets or complete files based on user requests, streaming the results., tags: [code, development, programming] } ] }要点声明了流式能力streaming: true与状态迁移历史stateTransitionHistory: true不支持推送通知技能只有一个code_generation示例提示词包括 Write a python function to calculate fibonacci numbers. 等。认证方案声明了bearerAuth与basicAuth两种 HTTP 方案。app.ts中的customUserBuilder实现了配套的认证解析解析Authorization头Bearer valid-token映射为bearer-userBasic解码后等于admin:password映射为basic-user否则返回UnauthenticatedUser。从源码结构看这两组凭据是示例性质的硬编码值实际部署时应替换为真实鉴权逻辑。5. 自定义 HTTP 端点任务创建与命令执行除a2a-js/sdk通过A2AExpressApp.setupRoutes()挂载的标准 A2A 路由外createApp()还额外注册了四个 Express 端点5.1POST /tasks—— 创建 A2A 任务const { agentSettings } req.body; // AgentSettings含 workspacePath 等 const contextId req.body.contextId || uuidv4(); const wrapper await agentExecutor.createTask(taskId, contextId, agentSettings); await taskStoreForExecutor.save(wrapper.toSDKTask()); res.status(201).json(wrapper.id);请求体中的agentSettings对应 types.ts 的AgentSettings接口kind: agent-settings、workspacePath必填autoExecute/isTrusted可选。新建任务会被立即写入任务存储内存或 GCS返回201与任务 id。5.2POST /executeCommand—— 执行注册命令该端点执行 commands/ 目录中的命令注册表条目处理逻辑handleExecuteCommand有明确的防御与分流校验command必须为字符串、args必须为数组否则返回 400命令若声明requiresWorkspace则要求环境变量CODER_AGENT_WORKSPACE_PATH已设置否则返回 400 并给出错误信息命令不存在返回 404流式命令command.streaming为真创建DefaultExecutionEventBus将响应头设为Content-Type: text/event-stream把每个AgentExecutionEvent包装成 JSON-RPC 风格的{ jsonrpc: 2.0, id: taskId|messageId, result: event }以data: ...行写出命令执行完毕后释放监听并结束响应非流式命令直接await commandToExecute.execute(context, args ?? [])后以 JSON 返回结果。5.3GET /listCommands—— 命令清单返回注册表中所有topLevel命令的嵌套结构name、description、arguments、subCommands。转换过程中用visited数组做环检测若某命令已被插入响应则跳过并打警告日志防止递归命令树导致死循环。5.4GET /tasks/metadata与GET /tasks/:taskId/metadata—— 任务元数据全量元数据端点仅在内存任务存储下可用若 executor 侧存储不是InMemoryTaskStore实例直接返回 501错误信息为 Listing all task metadata is only supported when using InMemoryTaskStore.否则对agentExecutor.getAllTasks()中的每个包装器并发调用wrapper.task.getMetadata()无任务时返回 204。单任务端点先查内存中的agentExecutor.getTask(taskId)未命中则回落到taskStoreForExecutor.load(taskId)并reconstruct重建任务包装器仍失败返回 404成功则返回{ metadata: await wrapper.task.getMetadata() }。Task.getMetadata()task.ts聚合了当前模型名modelInfo || config.getModel()、全部 MCP 服务器状态getAllMCPServerStatuses()源码注释特别说明这是进程级全局连接状态而非单任务作用域及其工具清单。6. 任务模型状态机、工具确认与事件发布task.ts 中的Task类是整个包的核心约 1300 行把 Gemini CLI 核心的Scheduler/GeminiClient事件流翻译为 A2A 协议事件。6.1 任务生命周期与状态构造函数将taskState初始化为submitted并配置模型回退策略A2A 服务器下主模型失败时setFallbackModelHandler会调用config.activateFallbackModel(fallbackModel, failedModel)并返回stop——即不重试当前请求而是让后续请求自动切到回退模型。scheduleToolCalls()在批量调度工具前把状态置为working并预注册所有callId保证waitForPendingTools不会漏看挂起项随后以 fire-and-forget 方式scheduler.schedule(updatedRequests, abortSignal)。checkInputRequiredState()是关键状态决策当所有挂起工具都处于awaiting_approval且无 executing/scheduled/validating、未被 YOLO 放行时发布final: true的input-required状态更新并通过toolUpdateEmitter解除waitForPendingTools的阻塞从而结束当前执行循环、释放 HTTP 响应流——源码注释明确写道IDE 客户端随后会带着确认答复打开一条新的流。isYoloMatchautoExecute || 审批模式 YOLO为真时跳过输入请求判断实现全自动执行。6.2 工具确认Confirmation协议客户端回传的确认以data类型 Part 的形式承载_handleToolConfirmationParttask.ts解析callId与outcome支持的取值完整映射到核心的ToolConfirmationOutcomeoutcome 字符串映射枚举语义proceed_onceProceedOnce本次放行cancelCancel取消该工具调用proceed_alwaysProceedAlways全局始终放行proceed_always_serverProceedAlwaysServer按 MCP 服务器放行proceed_always_toolProceedAlwaysTool按工具名放行proceed_always_and_saveProceedAlwaysAndSave放行并保存偏好modify_with_editorModifyWithEditor编辑器修改可携带newContent载荷确认后优先通过messageBus.publish({ type: TOOL_CONFIRMATION_RESPONSE, correlationId, confirmed, outcome, payload })驱动调度器继续或取消具体工具无correlationId时回落到旧式回调confirmationDetails.onConfirm(outcome, payload)。一个值得注意的安全细节确认处理期间会临时删除GOOGLE_CLOUD_PROJECT与GOOGLE_APPLICATION_CREDENTIALS防止 GCP 凭证泄漏进工具调用环境处理完再恢复。6.3 事件到 A2A 总线的映射acceptAgentMessage()将核心ServerGeminiStreamEvent逐一映射Content→ 文本状态更新text-content事件Thought→thought事件Citation→citation事件UserCancelled→ 取消全部挂起工具并发布input-required终结事件Error→ 解析 API 错误后以metadataError形式发布。工具执行中的实时输出通过_schedulerOutputUpdate封装为artifact-update事件artifactId: tool-callId-outputappend: true发布到 A2A 事件总线。此外对replace工具请求会在调度前预计算newContent先经validatePathAccess做路径穿越防护供客户端做内联编辑预览。7. 持久化InMemoryTaskStore 与 GCSTaskStoreGEMINI.md 将src/persistence/标注为会话与状态持久化。gcs.ts 中的GCSTaskStore实现如下桶初始化构造时校验GCS_BUCKET_NAME非空initializeBucket()会检查桶是否存在、不存在则创建要求账号具备 storage admin IAM 角色桶名需唯一对象布局tasks/taskId/metadata.tar.gz与tasks/taskId/workspace.tar.gz两个对象getObjectPath()先用正则^[a-zA-Z0-9_-]$校验taskId防止路径穿越攻击保存流程save()先从task.metadata中用getPersistedState提取__persistedState缺失即抛错将 metadata JSON gzip 压缩后写入 metadata 对象随后把工作目录process.cwd()即任务隔离后的任务工作区全部条目打成 tar.gz 归档经临时文件以可恢复写resumable: true流式上传到 workspace 对象。配合 3.6 节的装配逻辑GCS 模式下 handler 侧使用NoOpTaskStore(gcsTaskStore)executor 侧使用GCSTaskStore——这意味着请求处理器不重复承担 GCS I/O从源码结构看这是为降低标准 A2A 查询路径的存储开销而做的分工具体语义可结合 gcs.test.ts 验证。8. 并发隔离按任务重写的 process.env 与 cwda2a-server 的配置模块 解决了一个多租户服务器问题多个任务并发运行在同一进程如何避免环境变量与工作目录互相污染。其做法相当硬核用AsyncLocalStorageTaskEnvenvStorage保存每个异步上下文的独立环境通过一个Proxy 对象替换process.envObject.defineProperty(process, env, { value: envProxy, ... })config.ts拦截get/has/set/deleteProperty/ownKeys/getOwnPropertyDescriptor/defineProperty全部反射操作当前异步上下文存在任务环境时优先读写任务环境删除的键记入deletedKeys集合以屏蔽全局值同样以猴子补丁方式重写process.cwd()/process.chdir()使任务内的工作目录指向各自的 workspace。源码中的注释也坦承了这一方案的已知局限Node.js 原生 C API如fs.readFileSync与child_process.spawn解析相对路径时用的是 OS 级进程工作目录而非 JS 层process.cwd()。因此核心包要求所有文件路径先基于config.getTargetDir()/config.getCwd()解析为绝对路径再传给原生 API——这是理解 A2A 服务器并发安全边界的重要前提。9. 安全细节与测试体系安全控制分散在多个位置均可在源码中确认认证customUserBuilder的 Bearer/Basic 解析见第 4 节路径校验task.ts 中getProposedContent与scheduleToolCalls都先path.resolve(this.config.getTargetDir(), file_path)再调用config.validatePathAccess(resolvedPath, read)对file_path这类用户可控输入做路径穿越防护凭证隔离启动时仅白名单环境变量进入process.env第 3 节确认处理期间临时摘除 GCP 凭证变量第 6.2 节GCS 任务 id 白名单校验第 7 节。测试方面GEMINI.md 给出的运行方式是通过 npm 工作区执行npm test -w google/gemini-cli-a2a-server包内测试覆盖面反映了其关注点src/http/app.test.ts与endpoints.test.ts验证 HTTP 端点行为src/agent/race-condition.test.ts专门针对任务/工具的竞态条件src/agent/task-event-driven.test.ts验证事件驱动调度src/config/rce_vulnerability.test.ts针对配置加载的远程代码执行风险做回归防护另有command-registry.test.ts、memory.test.ts、restore.test.ts、gcs.test.ts等。10. 小结packages/a2a-server以约十个源文件实现了一个可用的实验性 A2A 服务端http/层负责 Express 装配、Agent Card 与四类自定义端点agent/层把 Gemini CLI 核心的调度器与模型流事件翻译成 A2A 的status-update/artifact-update事件并用input-required终结状态 新流的方式支撑工具确认往返persistence/层提供内存与 GCS 两种任务存储config/层用AsyncLocalStorageprocess.envProxy 实现按任务的并发隔离。由于包内 README 明确标注全部代码为实验性质接入生产系统前应重点评估认证硬编码值、localhost绑定与回退模型策略这三处的行为是否符合预期。相关源码入口app.ts、task.ts、config.ts、gcs.ts作为客户端一侧的配套文档可参考 docs/core/remote-agents.md。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考