AgnesCode 认证 + AI 通信 — 完整工程化参考手册

报告日期: 2026-07-25
验证状态: ✅ 全部端到端验证通过

1. 完整认证流程

1.1 总览

整个认证链路分为三个阶段:

Phase 1: JWT Token (从 platform 获取)
    ↓
Phase 2: 签发授权码 → 交换 OAuth Token
    ↓
Phase 3: 用 OAuth Token 调用 AI

1.2 Phase 1: 获取 JWT Token

JWT Token 从 platform.agnes-ai.com 平台获取。用户在浏览器登录 platform 后, 会获得一个 JWT Token。

获取方式: 用户登录 https://platform.agnes-ai.com 后, 浏览器中可以通过以下方式获取:

在 Chrome DevTools → Application → Local Storage → 查找 token
或通过 POST /api/user/login 接口获取

JWT Token 格式:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjY2U0NDFiZC01...

1.3 Phase 2: 签发授权码 → 交换 OAuth Token

步骤 2a: 签发授权码

请求:

POST https://api.agnes-ai.com/api/v1/user/issue-authorization-code
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
Origin: https://app.agnes-ai.com
x-platform: 1
x-user-language: en

请求体:

json

{
    "redirect_uri": "agnes://auth/callback",
    "state": "32_byte_hex_state",
    "client_id": "agnes-code",
    "ttl_seconds": 60
}

成功响应:

json

{
    "code": "000000",
    "message": "success",
    "data": {
        "code": "uxvLSipjtX8lo-wG6Adn4cXAzMQ_rh6DY8REOoj0yn0",
        "expires_at": 1785003621
    }
}

步骤 2b: 交换 OAuth Token

请求:

POST https://api-agnes-code.agnes-ai.com/api/v1/code/auth/exchange-code
Content-Type: application/json

请求体:

json

{
    "code": "上一步获取的授权码",
    "redirect_uri": "agnes://auth/callback",
    "state": "之前使用的 state",
    "client_id": "agnes-code"
}

成功响应:

json

{
    "code": "000000",
    "message": "success",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIs...",
        "user_info": {
            "id": "00000000-0000-0000-0000-000000000000",
            "username": "testuser",
            "email": "user@example.com",
            "auth_provider": "email",
            "is_active": true
        },
        "newapi_ready": true,
        "newapi_initialized": true
    }
}

1.4 Phase 3: 用 OAuth Token 调用 AI

请求:

POST https://api-agnes-code.agnes-ai.com/v1/chat/completions
Authorization: Bearer {OAUTH_TOKEN}
Content-Type: application/json

请求体 (OpenAI 兼容格式):

json

{
    "model": "agnes-2.0-flash",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 1024,
    "temperature": 0.7,
    "stream": false
}

成功响应:

json

{
    "id": "d09d5a73120e48bdb693ee31312f1334",
    "created": 1785003650,
    "model": "agnes-2.5-flash",
    "object": "chat.completion",
    "choices": [{
        "finish_reason": "stop",
        "index": 0,
        "message": {
            "content": "我是 Agnes-2.5-Flash，由 Sapiens AI 开发的语言模型。",
            "role": "assistant"
        }
    }],
    "usage": {
        "completion_tokens": 21,
        "prompt_tokens": 258,
        "total_tokens": 279
    }
}

2. AI 通信能力

2.1 后端架构

Agnes 的 AI 后端使用 LiteLLM (开源 LLM 代理) 作为统一网关:

请求 → api-agnes-code.agnes-ai.com → LiteLLM (v1.92.0) → 各 AI 提供商

从响应头中可以看到:

x-litellm-version: 1.92.0
x-litellm-model-group: agnes-2.0-flash
x-litellm-model-api-base: https://kw.dykjbj.com:9443/infer/vip-agnes-2-0-flash-sglang-router/v1

2.2 支持的 endpoint 类型

所有模型均支持 openai 格式 (即 OpenAI 兼容的 REST API)。

2.3 流式响应 (SSE)

支持 stream: true 参数, 返回 SSE (Server-Sent Events) 格式:

data: {"id":"...","object":"chat.completion.chunk","created":...,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"...","object":"chat.completion.chunk","created":...,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"content":"1"}}]}

data: {"id":"...","object":"chat.completion.chunk","created":...,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"content":","}}]}

data: [DONE]

3. 模型清单与定价

3.1 完整模型列表 (从 API 获取)

通过 GET /v1/models 动态获取, 当前共 7 个模型:

模型 ID	提供商	免费/会员	灰度	输入上限	输出上限	描述
`agnes-2.0-flash`	agnes	✅ 免费	-	512K	65K	日常任务和编码, 快速可靠
`agnes-2.5-flash`	agnes	✅ 免费	🧪 灰度	512K	65K	复杂任务, 速度与能力平衡
`glm-5.2`	zhipu	🔒 会员	-	1M	131K	中文、推理、编码强
`deepseek-v4-pro`	deepseek	🔒 会员	-	1M	393K	编码、数学、深度推理
`gemini-3.5-flash`	google	🔒 会员	-	1M	65K	多模态和长上下文
`gpt-5.5`	openai	🔒 会员	-	10M	131K	推理和高质量输出
`claude-opus-4-8`	anthropic	🔒 会员	-	1M	131K	长文分析和写作

3.2 模型获取方式

不要硬编码模型列表! 使用以下 API 动态获取:

GET https://api-agnes-code.agnes-ai.com/v1/models
Authorization: Bearer {OAUTH_TOKEN}
X-App-Id: 1
X-Platform: 1

响应格式:

json

{
    "data": [
        {
            "id": "agnes-2.0-flash",
            "object": "model",
            "created": 1784206241,
            "owned_by": "agnes",
            "provider": "agrouter",
            "description": "Fast and reliable for everyday tasks and coding.",
            "max_input_tokens": 512000,
            "max_output_tokens": 65536,
            "is_member_only": false,
            "is_gray": false,
            "gray_available": true,
            "model_type": "text",
            "supported_endpoint_types": ["openai"]
        }
    ]
}

3.3 关键字段说明

字段	类型	说明
`id`	string	模型 ID, 用于聊天补全请求
`is_member_only`	boolean	`true`=会员专属, `false`=免费可用
`is_gray`	boolean	`true`=灰度中, 可能不稳定
`gray_available`	boolean	灰度用户是否可用
`max_input_tokens`	int	最大输入 token 数
`max_output_tokens`	int	最大输出 token 数
`model_type`	string	`text` 或 `multimodal`
`supported_endpoint_types`	string[]	均为 `["openai"]`

4. 额度与速率限制

4.1 当前账号额度

余额: 1200 积分 (免费赠送)

GET https://api-agnes-code.agnes-ai.com/api/v2/subscription/credits-balance
Authorization: Bearer {OAUTH_TOKEN}
X-User-Language: zh-Hans

响应:

json

{
    "code": "000000",
    "data": {
        "level": 0,
        "level_name": "",
        "total_balance": 1200,
        "time_sensitive_balance": 1200,
        "permanent_balance": 0,
        "daily_free_credits": 0,
        "subscription_credits": 0,
        "effect_quota_balance": 0,
        "daily_effect_quota": 0
    }
}

4.2 交易记录

POST https://api-agnes-code.agnes-ai.com/api/v1/subscription/credits-transactions
Authorization: Bearer {OAUTH_TOKEN}
X-User-Language: zh-Hans

请求体:

json

{"page": 1, "page_size": 20, "filter": 0}

当前记录: 仅有 1 条 "每日免费赠送" 1200 积分。

4.3 已知信息

项目	值
免费额度	1200 积分 (一次性赠送)
会员模型	需要订阅才能使用
每日免费额度	`daily_free_credits: 0` (当前没有)
订阅	`current_subscription: null` (当前没有订阅)
速率限制	未明确发现, 但 LiteLLM 后端可能有限制

注意: 免费模型 (agnes-2.0-flash, agnes-2.5-flash) 即使没有会员也可以使用, 消耗积分。会员模型需要订阅。

4.4 消耗估算

从 x-litellm-key-spend: 1144.0353 可以看出, 每次调用会消耗积分。免费额度 1200 积分大概可以调用约 1000 次简单对话 (取决于 token 数)。

5. 流式响应

5.1 请求

json

{
    "model": "agnes-2.0-flash",
    "messages": [{"role": "user", "content": "Count 1 to 5"}],
    "max_tokens": 50,
    "stream": true
}

5.2 响应格式 (SSE)

data: {"id":"fa5da678...","object":"chat.completion.chunk","created":1785004491,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"fa5da678...","object":"chat.completion.chunk","created":1785004491,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"content":"1"}}]}

data: {"id":"fa5da678...","object":"chat.completion.chunk","created":1785004491,"model":"agnes-2.0-flash","choices":[{"index":0,"delta":{"content":","}}]}

data: [DONE]

5.3 响应头关键信息

x-litellm-version: 1.92.0
x-litellm-model-group: agnes-2.0-flash
x-litellm-model-api-base: https://kw.dykjbj.com:9443/infer/vip-agnes-2-0-flash-sglang-router/v1
x-litellm-key-spend: 1144.0353
x-litellm-response-duration-ms: 463.767

6. API 端点速查表

6.1 认证

操作	方法	URL	认证
签发授权码	POST	`https://api.agnes-ai.com/api/v1/user/issue-authorization-code`	JWT Token
交换 OAuth Token	POST	`https://api-agnes-code.agnes-ai.com/api/v1/code/auth/exchange-code`	授权码

6.2 AI 调用

操作	方法	URL	认证
聊天补全 (非流式)	POST	`https://api-agnes-code.agnes-ai.com/v1/chat/completions`	Bearer Token
聊天补全 (流式)	POST	`https://api-agnes-code.agnes-ai.com/v1/chat/completions?stream=true`	Bearer Token
模型列表	GET	`https://api-agnes-code.agnes-ai.com/v1/models`	Bearer Token

6.3 用户与订阅

操作	方法	URL	认证
用户信息	GET	`https://api-agnes-code.agnes-ai.com/api/v1/user/profile`	Bearer Token
信用余额	GET	`https://api-agnes-code.agnes-ai.com/api/v2/subscription/credits-balance`	Bearer Token
交易记录	POST	`https://api-agnes-code.agnes-ai.com/api/v1/subscription/credits-transactions`	Bearer Token
订阅套餐	GET	`https://api-agnes-code.agnes-ai.com/api/v1/subscription/plans`	Bearer Token

6.4 域名

域名	用途
`api.agnes-ai.com`	通用 API (签发授权码等)
`api-agnes-code.agnes-ai.com`	BFF API (AI 调用、模型列表、订阅)
`app.agnes-ai.com`	登录页面
`platform.agnes-ai.com`	用户平台
`platform-backend.agnes-ai.com`	平台后端

7. 反向代理设计蓝图

7.1 架构

┌──────────────┐     ┌──────────────────────┐     ┌──────────────────────┐
│  客户端工具    │     │                      │     │                      │
│  (Codex/      │────►│  反向代理 (中转站)     │────►│  Agnes BFF API       │
│  Claude Code  │     │                      │     │  api-agnes-code.     │
│  等)          │     │  1. 接收 OpenAI 格式   │     │  agnes-ai.com        │
│              │     │  2. 注入 Bearer Token  │     │                      │
│              │     │  3. 转发到 Agnes       │     │                      │
│              │     │  4. 返回响应/流式       │     │                      │
└──────────────┘     └──────────────────────┘     └──────────────────────┘

7.2 关键设计要点

要点	说明
协议	输入输出均为 OpenAI 兼容格式
认证	代理需要维护一个有效的 OAuth Token
模型列表	通过 `/v1/models` 动态获取, 不硬编码
流式	透传 SSE 流
Token 刷新	JWT Token 过期后需要重新签发

7.3 Token 生命周期管理

JWT Token (长期) → 签发授权码 (60秒有效) → OAuth Token (短期)
                                                      ↓
                                              AI 调用 (消耗 OAuth Token)
                                                      ↓
                                              OAuth Token 过期 → 重新签发

8. 附录: 原始数据

8.1 测试账号信息

字段	值
用户 ID	`00000000-0000-0000-0000-000000000000`
用户名	`testuser`
邮箱	`user@example.com`
认证方式	email
注册时间	2026-07-25
免费额度	1200 积分
订阅	无

8.2 已验证的响应头

x-litellm-version: 1.92.0
x-litellm-model-group: agnes-2.0-flash
x-litellm-model-api-base: https://kw.dykjbj.com:9443/infer/vip-agnes-2-0-flash-sglang-router/v1
x-litellm-key-spend: 1144.0353
x-litellm-response-duration-ms: 463.767

8.3 验证结果

测试项	结果
签发授权码	✅ 成功
交换 OAuth Token	✅ 成功
免费模型 AI 调用	✅ 成功 (agnes-2.0-flash, agnes-2.5-flash)
会员模型 AI 调用	✅ 成功 (gpt-5.5, 返回空内容可能是额度不足)
流式响应	✅ 成功 (SSE 格式)
模型列表	✅ 成功
信用额度	✅ 成功
交易记录	✅ 成功
用户信息	✅ 成功

AgnesCode 认证 + AI 通信 — 完整工程化参考手册 ​

1. 完整认证流程 ​

1.1 总览 ​

1.2 Phase 1: 获取 JWT Token ​

1.3 Phase 2: 签发授权码 → 交换 OAuth Token ​

步骤 2a: 签发授权码 ​

步骤 2b: 交换 OAuth Token ​

1.4 Phase 3: 用 OAuth Token 调用 AI ​

2. AI 通信能力 ​

2.1 后端架构 ​

2.2 支持的 endpoint 类型 ​

2.3 流式响应 (SSE) ​

3. 模型清单与定价 ​

3.1 完整模型列表 (从 API 获取) ​

3.2 模型获取方式 ​

3.3 关键字段说明 ​

4. 额度与速率限制 ​

4.1 当前账号额度 ​

4.2 交易记录 ​

4.3 已知信息 ​

4.4 消耗估算 ​

5. 流式响应 ​

5.1 请求 ​

5.2 响应格式 (SSE) ​

5.3 响应头关键信息 ​

6. API 端点速查表 ​

6.1 认证 ​

6.2 AI 调用 ​

6.3 用户与订阅 ​

6.4 域名 ​

7. 反向代理设计蓝图 ​

7.1 架构 ​

7.2 关键设计要点 ​

7.3 Token 生命周期管理 ​

8. 附录: 原始数据 ​

8.1 测试账号信息 ​

8.2 已验证的响应头 ​

8.3 验证结果 ​

AgnesCode 认证 + AI 通信 — 完整工程化参考手册

1. 完整认证流程

1.1 总览

1.2 Phase 1: 获取 JWT Token

1.3 Phase 2: 签发授权码 → 交换 OAuth Token

步骤 2a: 签发授权码

步骤 2b: 交换 OAuth Token

1.4 Phase 3: 用 OAuth Token 调用 AI

2. AI 通信能力

2.1 后端架构

2.2 支持的 endpoint 类型

2.3 流式响应 (SSE)

3. 模型清单与定价

3.1 完整模型列表 (从 API 获取)

3.2 模型获取方式

3.3 关键字段说明

4. 额度与速率限制

4.1 当前账号额度

4.2 交易记录

4.3 已知信息

4.4 消耗估算

5. 流式响应

5.1 请求

5.2 响应格式 (SSE)

5.3 响应头关键信息

6. API 端点速查表

6.1 认证

6.2 AI 调用

6.3 用户与订阅

6.4 域名

7. 反向代理设计蓝图

7.1 架构

7.2 关键设计要点

7.3 Token 生命周期管理

8. 附录: 原始数据

8.1 测试账号信息

8.2 已验证的响应头

8.3 验证结果