# Heicode Agent Manager API 对接文档

## 📋 目录

- [1. 概述](#1-概述)
- [2. 认证方式](#2-认证方式)
- [3. API 端点](#3-api-端点)
- [4. 数据模型](#4-数据模型)
- [5. 使用示例](#5-使用示例)
- [6. 错误处理](#6-错误处理)
- [7. 最佳实践](#7-最佳实践)

---

## 1. 概述

### 1.1 服务信息

- **服务名称**: Agent Manager - Heicode Integration API
- **版本**: v2.0.0 (heicode-v2)
- **Base URL**: `http://agent-manager.taijiagnet.com`
- **API 前缀**: `/api/agnet`

### 1.2 核心功能

- ✅ 多 Agent 编排部署
- ✅ 预算控制和计费管理
- ✅ 风险等级评估（low/medium/high）
- ✅ Vault 密钥集成
- ✅ 实时日志和事件追踪
- ✅ 资源监控和指标统计
- ✅ 幂等性保证

### 1.3 架构说明

```
┌─────────────┐
│   Heicode   │
│   Platform  │
└──────┬──────┘
       │ HTTPS + Token Auth
       ▼
┌─────────────────────────────┐
│  Agent Manager API          │
│  /api/agnet/*               │
└──────┬──────────────────────┘
       │
       ▼
┌─────────────────────────────┐
│  Kubernetes Cluster (AKS)   │
│  - Namespace 隔离           │
│  - Pod 管理                 │
│  - ConfigMap/Secret         │
└─────────────────────────────┘
```

---

## 2. 认证方式

### 2.1 Service Token 认证

所有 API 请求必须在 HTTP Header 中携带服务令牌：

```http
Authorization: Bearer <HEICODE_SERVICE_TOKEN>
```

### 2.2 必需的 HTTP Headers

| Header | 必需 | 说明 | 示例 |
|--------|------|------|------|
| `Authorization` | ✅ | 服务令牌 | `Bearer sk_xxx` |
| `X-User-ID` | ✅ | 用户标识 | `user_12345` |
| `X-Binding-Scope` | ✅ | 绑定范围 | `workspace_abc` |
| `X-Correlation-ID` | ✅ | 请求追踪 ID | `req_xyz789` |
| `X-Idempotency-Key` | ⚪ | 幂等性键（推荐） | `idem_abc123` |
| `Content-Type` | ✅ | 内容类型 | `application/json` |

### 2.3 获取 Service Token

请联系系统管理员获取 `HEICODE_SERVICE_TOKEN`。

---

## 3. API 端点

### 3.1 健康检查

#### `GET /api/agnet/health`

检查服务状态。

**请求示例**:
```bash
curl -X GET "http://agent-manager.taijiagnet.com/api/agnet/health" \
  -H "Authorization: Bearer sk_xxx"
```

**响应示例**:
```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "service": "agent-manager-agnet",
    "version": "1.0.0",
    "phase": "2-deployments"
  }
}
```

---

### 3.2 创建部署

#### `POST /api/agnet/deployments`

创建一个新的 Agent 部署。

**请求体**:
```json
{
  "orchestration_plan": "multi-agent-workflow",
  "risk_level": "medium",
  "approval_token": "optional_for_high_risk",
  "budget": {
    "max_usd": 100.0,
    "alert_threshold_pct": 80
  },
  "billing_context": {
    "provider": "newapi",
    "default_model_id": "gpt-4",
    "allowed_model_ids": ["gpt-4", "gpt-3.5-turbo"],
    "secret_ref": "vault:heicode/model-gateway-key"
  },
  "agents": [
    {
      "role": "researcher",
      "image": "agnettaiji.azurecr.io/ai-agents/search-agent:latest"
    },
    {
      "role": "writer",
      "image": "agnettaiji.azurecr.io/ai-agents/doc-creator:latest"
    }
  ],
  "resource_grants": [
    {
      "type": "database",
      "ref": "vault:heicode/db-credentials"
    }
  ]
}
```

**响应示例**:
```json
{
  "deployment_id": "dep_a1b2c3d4e5f6",
  "status": "pending",
  "agent_instances": [
    {
      "agent_instance_id": "agi_123abc",
      "role": "researcher",
      "status": "pending",
      "phase": null
    },
    {
      "agent_instance_id": "agi_456def",
      "role": "writer",
      "status": "pending",
      "phase": null
    }
  ],
  "created_at": "2026-05-12T10:30:00Z",
  "estimated_ready_at": "2026-05-12T10:32:00Z"
}
```

---

### 3.3 列出部署

#### `GET /api/agnet/deployments`

获取部署列表，支持过滤和分页。

**查询参数**:
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `user_id` | string | ⚪ | 按用户过滤 |
| `binding_scope` | string | ⚪ | 按绑定范围过滤 |
| `status` | string | ⚪ | 按状态过滤 (pending/running/stopped/failed) |
| `limit` | integer | ⚪ | 每页数量 (默认 50, 最大 200) |
| `cursor` | string | ⚪ | 分页游标 |

**请求示例**:
```bash
curl -X GET "http://agent-manager.taijiagnet.com/api/agnet/deployments?user_id=user_123&status=running&limit=10" \
  -H "Authorization: Bearer sk_xxx" \
  -H "X-User-ID: user_123" \
  -H "X-Binding-Scope: workspace_abc" \
  -H "X-Correlation-ID: req_list_001"
```

**响应示例**:
```json
{
  "deployments": [
    {
      "deployment_id": "dep_a1b2c3d4e5f6",
      "status": "running",
      "risk_level": "medium",
      "budget": {
        "max_usd": 100.0,
        "consumed_usd": 23.5,
        "remaining_usd": 76.5
      },
      "created_at": "2026-05-12T10:30:00Z",
      "agent_instances_count": 2
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}
```

---

### 3.4 获取部署详情

#### `GET /api/agnet/deployments/{deployment_id}`

获取指定部署的详细信息。

**路径参数**:
- `deployment_id`: 部署 ID

**请求示例**:
```bash
curl -X GET "http://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6" \
  -H "Authorization: Bearer sk_xxx" \
  -H "X-User-ID: user_123" \
  -H "X-Binding-Scope: workspace_abc" \
  -H "X-Correlation-ID: req_get_001"
```

**响应示例**:
```json
{
  "deployment_id": "dep_a1b2c3d4e5f6",
  "user_id": "user_123",
  "binding_scope": "workspace_abc",
  "status": "running",
  "phase": "executing",
  "orchestration_plan": "multi-agent-workflow",
  "risk_level": "medium",
  "budget": {
    "max_usd": 100.0,
    "consumed_usd": 23.5,
    "remaining_usd": 76.5
  },
  "billing_context": {
    "provider": "newapi",
    "default_model_id": "gpt-4",
    "allowed_model_ids": ["gpt-4", "gpt-3.5-turbo"]
  },
  "agent_instances": [
    {
      "agent_instance_id": "agi_123abc",
      "role": "researcher",
      "status": "running",
      "phase": "searching"
    },
    {
      "agent_instance_id": "agi_456def",
      "role": "writer",
      "status": "running",
      "phase": "writing"
    }
  ],
  "resource_grants": [
    {
      "type": "database",
      "ref": "vault:heicode/db-credentials"
    }
  ],
  "created_at": "2026-05-12T10:30:00Z",
  "updated_at": "2026-05-12T10:35:00Z"
}
```

---

### 3.5 停止部署

#### `POST /api/agnet/deployments/{deployment_id}/stop`

停止一个正在运行的部署。

**路径参数**:
- `deployment_id`: 部署 ID

**请求体**:
```json
{
  "reason": "User requested stop",
  "approval_token": "optional_for_high_risk"
}
```

**请求示例**:
```bash
curl -X POST "http://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/stop" \
  -H "Authorization: Bearer sk_xxx" \
  -H "X-User-ID: user_123" \
  -H "X-Binding-Scope: workspace_abc" \
  -H "X-Correlation-ID: req_stop_001" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Task completed"
  }'
```

**响应示例**:
```json
{
  "deployment_id": "dep_a1b2c3d4e5f6",
  "status": "stopped",
  "stopped_at": "2026-05-12T11:00:00Z"
}
```

---

### 3.6 获取部署日志

#### `GET /api/agnet/deployments/{deployment_id}/logs`

获取部署的实时日志。

**路径参数**:
- `deployment_id`: 部署 ID

**查询参数**:
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `agent_instance_id` | string | ⚪ | 按 Agent 实例过滤 |
| `since` | datetime | ⚪ | 起始时间 (ISO 8601) |
| `limit` | integer | ⚪ | 日志条数 (默认 100) |

**请求示例**:
```bash
curl -X GET "http://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/logs?limit=50" \
  -H "Authorization: Bearer sk_xxx" \
  -H "X-User-ID: user_123" \
  -H "X-Binding-Scope: workspace_abc" \
  -H "X-Correlation-ID: req_logs_001"
```

**响应示例**:
```json
{
  "deployment_id": "dep_a1b2c3d4e5f6",
  "logs": [
    {
      "timestamp": "2026-05-12T10:31:00Z",
      "agent_instance_id": "agi_123abc",
      "level": "info",
      "message": "Starting search task...",
      "source": "stdout"
    },
    {
      "timestamp": "2026-05-12T10:31:05Z",
      "agent_instance_id": "agi_123abc",
      "level": "info",
      "message": "Found 10 relevant documents",
      "source": "stdout"
    }
  ],
  "pagination": {
    "has_more": false
  }
}
```

---

### 3.7 获取部署事件

#### `GET /api/agnet/deployments/{deployment_id}/events`

获取部署的事件历史。

**路径参数**:
- `deployment_id`: 部署 ID

**查询参数**:
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `event_type` | string | ⚪ | 事件类型过滤 |
| `since` | datetime | ⚪ | 起始时间 (ISO 8601) |
| `limit` | integer | ⚪ | 事件条数 (默认 100) |

**事件类型**:
- `deployment.accepted` - 部署已接受
- `deployment.started` - 部署已启动
- `deployment.stopped` - 部署已停止
- `deployment.failed` - 部署失败
- `agent.started` - Agent 启动
- `agent.completed` - Agent 完成
- `budget.alert` - 预算告警

**请求示例**:
```bash
curl -X GET "http://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/events" \
  -H "Authorization: Bearer sk_xxx" \
  -H "X-User-ID: user_123" \
  -H "X-Binding-Scope: workspace_abc" \
  -H "X-Correlation-ID: req_events_001"
```

**响应示例**:
```json
{
  "deployment_id": "dep_a1b2c3d4e5f6",
  "events": [
    {
      "event_id": "evt_abc123",
      "event_type": "deployment.accepted",
      "agent_instance_id": null,
      "occurred_at": "2026-05-12T10:30:00Z",
      "payload": {
        "risk_level": "medium"
      }
    },
    {
      "event_id": "evt_def456",
      "event_type": "agent.started",
      "agent_instance_id": "agi_123abc",
      "occurred_at": "2026-05-12T10:31:00Z",
      "payload": {
        "role": "researcher"
      }
    }
  ],
  "pagination": {
    "has_more": false
  }
}
```

---

### 3.8 获取资源指标

#### `GET /api/agnet/deployments/{deployment_id}/metrics`

获取部署的资源使用指标。

**路径参数**:
- `deployment_id`: 部署 ID

**请求示例**:
```bash
curl -X GET "http://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/metrics" \
  -H "Authorization: Bearer sk_xxx" \
  -H "X-User-ID: user_123" \
  -H "X-Binding-Scope: workspace_abc" \
  -H "X-Correlation-ID: req_metrics_001"
```

**响应示例**:
```json
{
  "deployment_id": "dep_a1b2c3d4e5f6",
  "timestamp": "2026-05-12T10:35:00Z",
  "agent_metrics": [
    {
      "agent_instance_id": "agi_123abc",
      "role": "researcher",
      "status": "running",
      "resources": {
        "cpu_usage_cores": 0.25,
        "memory_usage_mb": 256.0,
        "network_rx_bytes": 1048576,
        "network_tx_bytes": 524288
      },
      "uptime_seconds": 300
    },
    {
      "agent_instance_id": "agi_456def",
      "role": "writer",
      "status": "running",
      "resources": {
        "cpu_usage_cores": 0.15,
        "memory_usage_mb": 128.0,
        "network_rx_bytes": 524288,
        "network_tx_bytes": 262144
      },
      "uptime_seconds": 300
    }
  ],
  "total_resources": {
    "cpu_usage_cores": 0.40,
    "memory_usage_mb": 384.0,
    "network_rx_bytes": 1572864,
    "network_tx_bytes": 786432
  }
}
```

---

## 4. 数据模型

### 4.1 部署状态 (DeploymentStatus)

| 状态 | 说明 |
|------|------|
| `pending` | 等待启动 |
| `running` | 运行中 |
| `stopped` | 已停止 |
| `failed` | 失败 |

### 4.2 风险等级 (RiskLevel)

| 等级 | 说明 | 审批要求 |
|------|------|----------|
| `low` | 低风险 | 无需审批 |
| `medium` | 中风险 | 无需审批 |
| `high` | 高风险 | 需要 approval_token |

### 4.3 计费提供商 (BillingProvider)

| 提供商 | 说明 |
|--------|------|
| `newapi` | Heicode NewAPI Gateway |
| `litellm` | LiteLLM Proxy |

### 4.4 资源授权类型 (ResourceGrantType)

| 类型 | 说明 |
|------|------|
| `database` | 数据库访问 |
| `storage` | 存储访问 |
| `api` | API 访问 |
| `custom` | 自定义资源 |

---

## 5. 使用示例

### 5.1 完整工作流示例

```python
import requests
import time

# 配置
BASE_URL = "http://agent-manager.taijiagnet.com"
TOKEN = "sk_your_service_token"
USER_ID = "user_123"
BINDING_SCOPE = "workspace_abc"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "X-User-ID": USER_ID,
    "X-Binding-Scope": BINDING_SCOPE,
    "X-Correlation-ID": f"req_{int(time.time())}",
    "Content-Type": "application/json"
}

# 1. 创建部署
create_payload = {
    "orchestration_plan": "research-and-write",
    "risk_level": "medium",
    "budget": {
        "max_usd": 50.0,
        "alert_threshold_pct": 80
    },
    "billing_context": {
        "provider": "newapi",
        "default_model_id": "gpt-4",
        "allowed_model_ids": ["gpt-4", "gpt-3.5-turbo"],
        "secret_ref": "vault:heicode/model-gateway-key"
    },
    "agents": [
        {
            "role": "researcher",
            "image": "agnettaiji.azurecr.io/ai-agents/search-agent:latest"
        },
        {
            "role": "writer",
            "image": "agnettaiji.azurecr.io/ai-agents/doc-creator:latest"
        }
    ],
    "resource_grants": []
}

response = requests.post(
    f"{BASE_URL}/api/agnet/deployments",
    headers=headers,
    json=create_payload
)
deployment = response.json()
deployment_id = deployment["deployment_id"]
print(f"✅ 部署创建成功: {deployment_id}")

# 2. 等待部署就绪
time.sleep(120)  # 等待 2 分钟

# 3. 获取部署详情
response = requests.get(
    f"{BASE_URL}/api/agnet/deployments/{deployment_id}",
    headers=headers
)
details = response.json()
print(f"📊 部署状态: {details['status']}")

# 4. 获取实时日志
response = requests.get(
    f"{BASE_URL}/api/agnet/deployments/{deployment_id}/logs?limit=20",
    headers=headers
)
logs = response.json()
print(f"📝 最新日志: {len(logs['logs'])} 条")

# 5. 获取资源指标
response = requests.get(
    f"{BASE_URL}/api/agnet/deployments/{deployment_id}/metrics",
    headers=headers
)
metrics = response.json()
print(f"💻 CPU 使用: {metrics['total_resources']['cpu_usage_cores']} cores")
print(f"💾 内存使用: {metrics['total_resources']['memory_usage_mb']} MB")

# 6. 停止部署
stop_payload = {
    "reason": "Task completed successfully"
}
response = requests.post(
    f"{BASE_URL}/api/agnet/deployments/{deployment_id}/stop",
    headers=headers,
    json=stop_payload
)
result = response.json()
print(f"🛑 部署已停止: {result['stopped_at']}")
```

### 5.2 幂等性示例

使用 `X-Idempotency-Key` 确保请求幂等性：

```python
import uuid

idempotency_key = f"idem_{uuid.uuid4().hex}"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "X-User-ID": USER_ID,
    "X-Binding-Scope": BINDING_SCOPE,
    "X-Correlation-ID": f"req_{int(time.time())}",
    "X-Idempotency-Key": idempotency_key,  # 幂等性键
    "Content-Type": "application/json"
}

# 第一次请求
response1 = requests.post(
    f"{BASE_URL}/api/agnet/deployments",
    headers=headers,
    json=create_payload
)

# 重复请求（使用相同的 idempotency_key）
response2 = requests.post(
    f"{BASE_URL}/api/agnet/deployments",
    headers=headers,
    json=create_payload
)

# response1 和 response2 返回相同的结果
assert response1.json()["deployment_id"] == response2.json()["deployment_id"]
```

---

## 6. 错误处理

### 6.1 错误响应格式

所有错误响应遵循统一格式：

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "request_id": "req_xyz789"
  }
}
```

### 6.2 错误码列表

| HTTP 状态码 | 错误码 | 说明 |
|------------|--------|------|
| 401 | `UNAUTHORIZED` | 认证失败，Token 无效 |
| 403 | `FORBIDDEN` | 权限不足 |
| 404 | `DEPLOYMENT_NOT_FOUND` | 部署不存在 |
| 409 | `DEPLOYMENT_CONFLICT` | 部署状态冲突 |
| 422 | `MODEL_NOT_ALLOWED` | 模型不在允许列表中 |
| 422 | `POLICY_REJECTED` | 策略拒绝（如高风险需审批） |
| 422 | `VALIDATION_ERROR` | 请求参数验证失败 |
| 500 | `INTERNAL_ERROR` | 服务器内部错误 |

### 6.3 错误处理示例

```python
try:
    response = requests.post(
        f"{BASE_URL}/api/agnet/deployments",
        headers=headers,
        json=create_payload
    )
    response.raise_for_status()
    deployment = response.json()
    
except requests.exceptions.HTTPError as e:
    error_data = e.response.json()
    error_code = error_data["error"]["code"]
    error_message = error_data["error"]["message"]
    
    if error_code == "MODEL_NOT_ALLOWED":
        print(f"❌ 模型配置错误: {error_message}")
    elif error_code == "POLICY_REJECTED":
        print(f"❌ 需要审批: {error_message}")
    else:
        print(f"❌ 请求失败: {error_message}")
```

---

## 7. 最佳实践

### 7.1 认证和安全

✅ **推荐做法**:
- 将 Service Token 存储在环境变量或密钥管理系统中
- 使用 HTTPS 进行所有 API 调用
- 定期轮换 Service Token
- 使用 Vault 存储敏感配置（如 API Key）

❌ **避免**:
- 在代码中硬编码 Token
- 在日志中打印 Token
- 在 URL 参数中传递敏感信息

### 7.2 幂等性

✅ **推荐做法**:
- 对所有创建操作使用 `X-Idempotency-Key`
- 使用 UUID 或时间戳生成唯一的幂等性键
- 在网络不稳定时重试请求

### 7.3 预算控制

✅ **推荐做法**:
- 设置合理的 `max_usd` 预算上限
- 设置 `alert_threshold_pct` 为 80-90%
- 定期检查 `consumed_usd` 和 `remaining_usd`
- 在预算告警时及时停止部署

### 7.4 日志和监控

✅ **推荐做法**:
- 使用 `X-Correlation-ID` 追踪请求链路
- 定期轮询 `/logs` 和 `/events` 端点
- 监控 `/metrics` 端点的资源使用情况
- 保存审计日志用于问题排查

### 7.5 错误处理

✅ **推荐做法**:
- 实现指数退避重试机制
- 区分可重试错误（5xx）和不可重试错误（4xx）
- 记录完整的错误上下文（request_id, correlation_id）
- 为高风险操作准备回滚方案

### 7.6 性能优化

✅ **推荐做法**:
- 使用分页参数避免一次性获取大量数据
- 缓存不常变化的数据（如模板列表）
- 使用 `since` 参数增量获取日志和事件
- 并发调用独立的 API 端点

---

## 8. 附录

### 8.1 支持的 Agent 镜像

| Agent 类型 | 镜像地址 | 说明 |
|-----------|---------|------|
| Search Agent | `agnettaiji.azurecr.io/ai-agents/search-agent:latest` | 搜索和信息检索 |
| Doc Creator | `agnettaiji.azurecr.io/ai-agents/doc-creator:latest` | 文档生成 |
| Code AI Agent | `agnettaiji.azurecr.io/ai-agents/code-ai-agent:latest` | 代码生成和 CI/CD |
| Ad Creator | `agnettaiji.azurecr.io/ai-agents/ad-creator:latest` | 广告创意生成 |
| Video Generator | `agnettaiji.azurecr.io/ai-agents/video-generator:latest` | 视频生成 |

### 8.2 联系方式

- **技术支持**: support@taijiagnet.com
- **API 文档**: http://agent-manager.taijiagnet.com/docs
- **问题反馈**: https://github.com/your-org/agent-manager/issues

### 8.3 更新日志

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| v2.0.0 | 2026-05-12 | 初始版本，支持 Heicode 集成 |

---

**文档版本**: v2.0.0  
**最后更新**: 2026-05-12  
**维护者**: Agent Manager Team