zhanggangyong/agent_management

Fork 1

Files

T

elipitc f6851c9680 Add A2A agent access token auth

2026-06-04 23:06:45 +08:00

9.0 KiB

Raw Blame History

Coding A2A Agent 创建与调用文档

本文档说明如何通过 agent-manager 创建 coding_a2a_agent，以及如何通过 A2A 协议调用它执行编程任务。

适用对象：

需要一个类似 Claude Code 的编程 agent
需要在启动时注入角色设定或团队约定
需要按需挂接 Git / MySQL / PostgreSQL / Azure Blob 资源

1. 模板定位

coding_a2a_agent 是一个：

以 Pydantic AI 为核心的编程 agent
对外暴露 A2A 协议
支持工作区代码工具
支持动态资源工具

主要能力：

read_file
list_files
write_file
edit_file
run_command
git_*
list_database_tables
run_database_query
list_blob_objects
read_blob_text

注意：

资源工具是否调用，由 agent 自己判断
某项资源没配置，不会阻止 agent 启动
未配置的资源工具被调用时会返回 resource not configured

2. 创建入口

通过 agent-manager 的旧版统一入口创建：

POST /agents

请求体核心字段：

name
template = "coding_a2a_agent"
framework = "A2A"
config.user_id
env

3. 最小创建示例

这是当前最小可工作的创建请求。

{
  "name": "coding-a2a-backend",
  "template": "coding_a2a_agent",
  "framework": "A2A",
  "config": {
    "user_id": "demo-user"
  },
  "env": {
    "OPENAI_BASE_URL": "https://code.xinghanlab.com/v1",
    "OPENAI_API_KEY": "sk-xxxx",
    "MODEL_NAME": "gpt-5.4",
    "AGENT_ACCESS_TOKEN": "550e8400-e29b-41d4-a716-446655440000",
    "HEICODE_AGENT_ID": "dep-b5fab27e9255"
  }
}

说明：

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 = 规范化后的生命周期状态
- subdomain = access_info.domain 或 access_info.external_ip

3.1 生命周期接口

为对齐 HM 的模板 Agent 运行时联调，/agents 入口现在同时提供以下生命周期接口：

GET    /agents/{agent_name}
POST   /agents/{agent_name}/stop
DELETE /agents/{agent_name}
GET    /agents/{agent_name}/status

说明：

GET /agents/{agent_name} 返回平铺的生命周期信息，便于 HM 直接解析 status / runtime_status / state
POST /agents/{agent_name}/stop 为幂等停止，不删除数据库记录
DELETE /agents/{agent_name} 删除 Agent 运行资源与数据库记录
GET /agents/{agent_name}/status 仍保留详细 Pod 诊断信息，适合排障

GET /agents/{agent_name} 示例响应：

{
  "runtime_id": "coding-a2a-backend",
  "agent_id": "coding-a2a-backend",
  "id": "coding-a2a-backend",
  "name": "coding-a2a-backend",
  "namespace": "agent-coding-a2a-backend",
  "status": "running",
  "runtime_status": "running",
  "state": "running",
  "subdomain": "coding-a2a-backend.taijiagnet.com",
  "access_token": null,
  "access_info": {
    "domain": "coding-a2a-backend.taijiagnet.com"
  }
}

4. 启动角色与团队约定

启动时可以通过环境变量注入角色和约束。

支持：

AGENT_ROLE_NAME
AGENT_INSTRUCTION_TEXT
AGENT_INSTRUCTION_FILE

优先级：

AGENT_INSTRUCTION_TEXT
AGENT_INSTRUCTION_FILE
默认通用系统提示词

示例：

{
  "name": "coding-a2a-backend",
  "template": "coding_a2a_agent",
  "framework": "A2A",
  "config": {
    "user_id": "demo-user"
  },
  "env": {
    "OPENAI_BASE_URL": "https://code.xinghanlab.com/v1",
    "OPENAI_API_KEY": "sk-xxxx",
    "MODEL_NAME": "gpt-5.4",
    "AGENT_ROLE_NAME": "backend",
    "AGENT_INSTRUCTION_TEXT": "# Role\n你是 backend engineer\n\n# Constraints\n- 优先写 Python 代码\n- 不改 frontend\n- 修改后要自己做最小验证"
  }
}

启动成功后可通过：

GET /health
GET /.well-known/agent.json

确认实例已经生效。

/health 会返回：

role_name
instruction_source
enabled_resources

5. 动态资源工具

资源可以在启动时通过环境变量动态挂载，也可以在 A2A 请求中通过 configuration.resources 传入。

请求级配置会覆盖启动时环境变量配置。

5.1 Git

可选环境变量：

GIT_REPO_URL
GIT_PROVIDER
GIT_USERNAME
GIT_PASSWORD
GIT_TOKEN
GIT_DEFAULT_BRANCH
GIT_LOCAL_PATH
GIT_ALLOWED_PATHS
GIT_WRITE_MODE

5.2 MySQL

至少需要：

MYSQL_HOST
MYSQL_USER
MYSQL_PASSWORD
MYSQL_DATABASE

可选：

MYSQL_PORT
MYSQL_SSL_MODE

5.3 PostgreSQL

至少需要：

POSTGRES_HOST
POSTGRES_USER
POSTGRES_PASSWORD
POSTGRES_DATABASE

可选：

POSTGRES_PORT
POSTGRES_SSL_MODE

兼容：

POSTGRESQL_HOST
POSTGRESQL_USER
POSTGRESQL_PASSWORD
POSTGRESQL_DATABASE

5.4 Azure Blob

至少需要：

AZURE_BLOB_CONTAINER

再配下面任意一套：

AZURE_BLOB_CONNECTION_STRING
AZURE_BLOB_ACCOUNT_URL + AZURE_BLOB_SAS_TOKEN
AZURE_BLOB_ACCOUNT_URL + AZURE_BLOB_ACCOUNT_KEY
AZURE_BLOB_ACCOUNT_NAME + AZURE_BLOB_ACCOUNT_KEY

可选：

AZURE_BLOB_PREFIX

兼容：

AZURE_STORAGE_CONNECTION_STRING
AZURE_STORAGE_CONTAINER
AZURE_STORAGE_ACCOUNT_NAME
AZURE_STORAGE_ACCOUNT_KEY
AZURE_STORAGE_PREFIX

6. 健康检查与发现

实例创建完成后，推荐先检查：

GET /health
GET /.well-known/agent.json

/health 示例响应：

{
  "status": "healthy",
  "template_type": "coding_a2a_agent",
  "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 同步调用

POST /message/send

最小调用示例：

如果实例启用了访问鉴权，请附带请求头：

X-Agent-Access-Token: 550e8400-e29b-41d4-a716-446655440000

{
  "jsonrpc": "2.0",
  "id": "task-1",
  "method": "message/send",
  "params": {
    "api_key": "sk-xxxx",
    "model": "gpt-5.4",
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "请在 /workspace 下创建 math_tools.py，包含 factorial 和 is_prime，并自行做最小验证。"
        }
      ]
    },
    "configuration": {
      "workspace": {
        "root_dir": "/workspace",
        "allowed_paths": ["math_tools.py"]
      }
    }
  }
}

7.2 流式调用

POST /message/stream

返回为 text/event-stream。

如果实例开启了访问鉴权，流式调用同样需要带：

X-Agent-Access-Token: 550e8400-e29b-41d4-a716-446655440000

8. 请求级资源覆盖示例

如果你不想在启动时固定资源，可以在具体任务里传：

{
  "jsonrpc": "2.0",
  "id": "task-2",
  "method": "message/send",
  "params": {
    "api_key": "sk-xxxx",
    "model": "gpt-5.4",
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "读取 blob 中的文档摘要，并根据内容生成一个 Python 数据结构。"
        }
      ]
    },
    "configuration": {
      "workspace": {
        "root_dir": "/workspace"
      },
      "resources": {
        "azure_blob": {
          "container_name": "artifacts",
          "connection_string": "UseDevelopmentStorage=true"
        }
      }
    }
  }
}

9. 已验证行为

当前已做过真实线上验证：

启动时 AGENT_ROLE_NAME 生效
启动时 AGENT_INSTRUCTION_TEXT 生效
/health 正确返回 role_name 和 instruction_source
message/send 可真实调用模型
agent 能在 /workspace 中：
- 新建 Python 文件
- 修改已有文件
- 创建子目录下的代码文件
- 执行最小验证命令

10. 当前注意事项

当前实例启动阶段建议提供 OPENAI_API_KEY
当前网关下不同 key 可用模型可能不同，示例里使用 gpt-5.4
如果 workspace 不是 git 仓库，agent 可能会尝试执行 git status，但这不会阻止大多数代码任务完成
如果某项资源没配置，agent 仍会启动，只是在调用对应资源工具时返回未配置提示

9.0 KiB Raw Blame History Unescape Escape

Coding A2A Agent 创建与调用文档

1. 模板定位

2. 创建入口

3. 最小创建示例

3.1 生命周期接口

4. 启动角色与团队约定

5. 动态资源工具

5.1 Git

5.2 MySQL

5.3 PostgreSQL

5.4 Azure Blob

6. 健康检查与发现

7. A2A 调用方式

7.0 访问鉴权

7.1 同步调用

7.2 流式调用

8. 请求级资源覆盖示例

9. 已验证行为

10. 当前注意事项

9.0 KiB

Raw Blame History