Add A2A agent access token auth

docs/CODING_A2A_AGENT_CREATE_AND_INVOKE.md

@@ -67,7 +67,9 @@ POST /agents
   "env": {
     "OPENAI_BASE_URL": "https://code.xinghanlab.com/v1",
     "OPENAI_API_KEY": "sk-xxxx",
-    "MODEL_NAME": "gpt-5.4"
+    "MODEL_NAME": "gpt-5.4",
+    "AGENT_ACCESS_TOKEN": "550e8400-e29b-41d4-a716-446655440000",
+    "HEICODE_AGENT_ID": "dep-b5fab27e9255"
   }
 }
 ```
@@ -77,6 +79,7 @@ POST /agents
 - `OPENAI_API_KEY` 当前建议在启动时传入
 - 当前实测可用模型示例是 `gpt-5.4`
 - 返回中会带 `namespace`、`pod_ip`、`access_info.external_ip`、`access_info.domain`
+- 如果上层已注入 `AGENT_ACCESS_TOKEN`，A2A 请求入口会要求请求头 `X-Agent-Access-Token`
 - 为兼容 HM 模板 Agent Runtime 契约，响应同时补充：
   - `runtime_id` / `agent_id` / `id` = agent 名称
   - `runtime_status` / `state` = 规范化后的生命周期状态
@@ -267,12 +270,29 @@ GET /.well-known/agent.json
   "role_name": "backend",
   "instruction_source": "env_text",
   "enabled_resources": ["git", "azure_blob"],
+  "auth_required": true,
   "timestamp": "2026-06-04T05:04:22.760314Z"
 }
 ```
 
 ## 7. A2A 调用方式
 
+### 7.0 访问鉴权
+
+当前模板 Agent 支持 HM 约定的本地访问鉴权：
+
+- 如果实例环境变量里存在 `AGENT_ACCESS_TOKEN`，则 `POST /message/send`、`POST /message/stream`、`GET /tasks/{task_id}` 必须带请求头 `X-Agent-Access-Token`
+- 服务端使用常量时间比较校验 `X-Agent-Access-Token == AGENT_ACCESS_TOKEN`
+- 缺少请求头时返回 `401`
+- 请求头不匹配时返回 `403`
+- 如果实例没有注入 `AGENT_ACCESS_TOKEN`，则继续兼容放行
+
+注意：
+
+- `X-Agent-Access-Token` 负责“谁有权访问这个 agent”
+- A2A body 里的 `api_key` 负责“本次请求用谁的模型额度”
+- 两者职责分离，不互相替代
+
 ### 7.1 同步调用
 
 ```http
@@ -281,6 +301,12 @@ POST /message/send
 
 最小调用示例：
 
+如果实例启用了访问鉴权，请附带请求头：
+
+```http
+X-Agent-Access-Token: 550e8400-e29b-41d4-a716-446655440000
+```
+
 ```json
 {
   "jsonrpc": "2.0",
@@ -316,6 +342,12 @@ POST /message/stream
 
 返回为 `text/event-stream`。
 
+如果实例开启了访问鉴权，流式调用同样需要带：
+
+```http
+X-Agent-Access-Token: 550e8400-e29b-41d4-a716-446655440000
+```
+
 ## 8. 请求级资源覆盖示例
 
 如果你不想在启动时固定资源，可以在具体任务里传：

docs/HEICODE_API_INTEGRATION.md

@@ -1250,7 +1250,9 @@ curl -L \
     "AGENT_INSTRUCTION_TEXT": "---\nname: architect\n---\n<Agent_Prompt>...</Agent_Prompt>",
     "OPENAI_BASE_URL": "https://code.xinghanlab.com/v1",
     "OPENAI_API_KEY": "sk-xxxx",
-    "MODEL_NAME": "gpt-5.4"
+    "MODEL_NAME": "gpt-5.4",
+    "AGENT_ACCESS_TOKEN": "550e8400-e29b-41d4-a716-446655440000",
+    "HEICODE_AGENT_ID": "dep-b5fab27e9255"
   }
 }
 ```
@@ -1284,6 +1286,21 @@ curl -L \
 - `subdomain` 取自 `access_info.domain`，若 DNS 尚未就绪则回退到 `access_info.external_ip`。
 - `runtime_status` / `state` 是对 Pod 生命周期的兼容投影；当前可能值为 `pending`、`running`、`stopped`、`failed`。
 
+#### 客户端直连鉴权
+
+模板 Agent 当前支持 HM 约定的本地访问鉴权：
+
+- 当实例环境变量存在 `AGENT_ACCESS_TOKEN` 时，`POST /message/send`、`POST /message/stream`、`GET /tasks/{task_id}` 必须携带请求头 `X-Agent-Access-Token`
+- 服务端使用常量时间比较校验 `X-Agent-Access-Token == AGENT_ACCESS_TOKEN`
+- 请求头缺失时返回 `401`
+- 请求头不匹配时返回 `403`
+- 若实例未注入 `AGENT_ACCESS_TOKEN`，则继续兼容放行
+
+职责边界：
+
+- `X-Agent-Access-Token` 用于“谁有权访问这个 agent”
+- A2A body 中的 `api_key` 仍用于“本次请求走谁的模型额度”
+
 #### `GET /agents/{agent_name}`
 
 用于 HM 轮询模板 Agent 生命周期。返回体与 `POST /agents` 的核心生命周期字段保持一致，便于 HM 复用同一套解析逻辑。