AgnesCode AI 提供商协议分析报告

协议端点: agnesd (Rust) ↔ 外部 AI 提供商
通信方式: HTTPS REST API + WebSocket + OAuth
报告日期: 2026-07-25
分析版本: v1.0.17

1. 架构概述

┌─────────────────────────────────────────────────────────────────┐
│  agnesd (Rust Backend)                                          │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  Provider Router                                          │   │
│  │  ├── Agnes (内置, 通过 BFF 代理)                           │   │
│  │  ├── OpenAI (API Key / OAuth)                             │   │
│  │  ├── Anthropic (API Key)                                  │   │
│  │  ├── Google/Gemini/Vertex (OAuth / Cloud Credentials)     │   │
│  │  ├── DeepSeek (API Key)                                   │   │
│  │  ├── Qwen (API Key)                                       │   │
│  │  ├── Ollama (本地)                                         │   │
│  │  └── Custom (OpenAI 兼容)                                  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  MCP (Model Context Protocol) Hub                        │   │
│  │  ├── 本地工具 (FS, Terminal, Git)                        │   │
│  │  ├── HTTP MCP 服务器                                      │   │
│  │  ├── SSE MCP 服务器                                       │   │
│  │  └── 子进程 MCP 服务器                                    │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

2. 提供商配置系统

2.1 配置 Schema

typescript

interface ProviderConfig {
    providerId: string;           // 唯一标识符
    providerName: string;         // 显示名称
    description: string;          // 描述
    defaultModel: string;         // 默认模型 ID
    configured: boolean;          // 是否已配置
    providerType: 'agent' | 'model';
    category: 'agent' | 'model';
    configKeys: ConfigKey[];      // 配置键列表
    setupSteps: string[];         // 设置步骤说明
    supportsRefresh: boolean;     // 是否支持刷新
    refreshing: boolean;          // 正在刷新
    models: ModelInfo[];          // 可用模型列表
    lastUpdatedAt?: string;       // 最后更新时间
    stale: boolean;               // 是否过期
    modelSelectionHint?: string;  // 模型选择提示
}

interface ConfigKey {
    name: string;                 // 键名
    required: boolean;            // 是否必填
    secret: boolean;              // 是否密钥 (存储在密钥链)
    default?: string | number | boolean;
    oauthFlow?: boolean;          // 使用 OAuth 流程
    deviceCodeFlow?: boolean;     // 使用设备码流程
    primary?: boolean;            // 是否主键
}

interface ModelInfo {
    id: string;                   // 模型 ID
    name: string;                 // 显示名称
    family?: string;              // 模型家族
    contextLimit?: number;        // 上下文窗口大小
    reasoning?: boolean;          // 支持推理
    recommended?: boolean;        // 推荐
}

interface ModelCapabilities {
    toolCall: boolean;            // 工具调用
    reasoning: boolean;           // 推理
    attachment: boolean;          // 附件
    temperature: boolean;         // 温度参数
}

2.2 设置方式

typescript

type SetupMethod =
    | 'none'                      // 无需设置
    | 'single_api_key'            // 单个 API Key
    | 'config_fields'             // 多个配置字段
    | 'host_with_oauth_fallback'  // 主机地址 + OAuth 回退
    | 'oauth_browser'             // 浏览器 OAuth
    | 'oauth_device_code'         // 设备码 OAuth
    | 'cloud_credentials'         // 云凭证
    | 'local'                     // 本地模型
    | 'cli_auth'                  // CLI 认证

3. 提供商清单

3.1 完整列表

提供商	类型	设置方式	备注
Agnes	内置	自动	通过 BFF 代理所有模型
OpenAI	外部	`single_api_key` / `oauth_browser`	GPT-4, GPT-4o, o1, o3
Anthropic	外部	`single_api_key`	Claude 系列
Google	外部	`oauth_browser` / `cloud_credentials`	Gemini, Vertex AI
DeepSeek	外部	`single_api_key`	DeepSeek V4
Qwen (通义千问)	外部	`single_api_key`	阿里云
Mistral	外部	`single_api_key`	Mistral AI
Cohere	外部	`single_api_key`	Command R+
Ollama	本地	`local`	本地模型
Databricks	外部	`host_with_oauth_fallback`	数据平台
Azure	外部	`config_fields`	Azure OpenAI
AWS Bedrock	外部	`cloud_credentials`	AWS
OpenRouter	外部	`single_api_key`	统一 API 网关
GitHub Models	外部	`oauth_browser`	GitHub
Custom (OpenAI 兼容)	外部	`config_fields`	任意 OpenAI 兼容 API

3.2 提供商配置管理

typescript

// 通过 ACP 扩展方法管理
interface ProviderConfigAPI {
    // 读取配置
    providersConfigRead: (params: { providerId: string }) => Promise<ProviderConfig>;

    // 保存配置
    providersConfigSave: (params: {
        providerId: string;
        config: Record<string, string>;
    }) => Promise<void>;

    // 删除配置
    providersConfigDelete: (params: { providerId: string }) => Promise<void>;

    // 认证
    providersConfigAuthenticate: (params: {
        providerId: string;
        config: Record<string, string>;
    }) => Promise<void>;

    // 查询状态
    providersConfigStatus: (params: { providerId: string }) => Promise<{
        providerId: string;
        isConfigured: boolean;
    }>;
}

4. 模型路由

4.1 路由策略

typescript

interface ModelPreferences {
    hints?: { name?: string }[];
    costPriority?: number;        // 0-1, 成本优先级
    speedPriority?: number;       // 0-1, 速度优先级
    intelligencePriority?: number;// 0-1, 智能优先级
}

interface ModelSelection {
    mode: 'auto' | 'required' | 'none';  // 工具选择模式
}

4.2 默认配置

javascript

// 环境变量
AGNES_DEFAULT_PROVIDER=agnes   // 默认提供商
AGNES_DEFAULT_MODEL=auto       // 默认模型 (自动选择)

4.3 预定义模型

从 .env 文件提取:

json

[
    {"name":"agnes-2.5-flash","provider":"agnes","alias":"Agnes 2.5 Flash","subtext":"Agnes 最新一代旗舰模型，速度与智能的完美平衡。"},
    {"name":"agnes-2.0-flash-test","provider":"agnes","alias":"Agnes 2.0 Flash","subtext":"Agnes 最新旗舰模型，综合能力最强。"},
    {"name":"openai/gpt-5.5","provider":"agnes","alias":"GPT-5.5","subtext":"OpenAI 最新一代旗舰模型，多模态与超强智能巅峰。"},
    {"name":"anthropic/claude-fable-5","provider":"agnes","alias":"Claude Fable 5","subtext":"Anthropic 最新神级模型，极智推理，行业顶尖的长文本理解力。"},
    {"name":"google/gemini-3.5-flash","provider":"agnes","alias":"Gemini 3.5 flash","subtext":"Google 顶尖旗舰，超大上下文窗口与原生全模态分析专家。"},
    {"name":"deepseek/deepseek-v4-pro","provider":"agnes","alias":"DeepSeek V4 Pro","subtext":"深度求索最新万亿级MoE旗舰，原生百万上下文。"},
    {"name":"z-ai/glm-5.2","provider":"agnes","alias":"GLM 5.2","subtext":"智谱 AI 最新国货旗舰，百万无损长上下文。"}
]

注意: 所有模型都通过 provider: "agnes" 统一路由, 实际由 agnesd 后端代理到对应 AI 服务。

5. OAuth 集成

从 agnesd 二进制提取的 OAuth 端点:

5.1 OAuth 端点

/oauth/authorize              - OAuth 授权页面
/oauth/token                  - OAuth Token 交换
/oauth_callback               - OAuth 回调
/login/device/code            - 设备码登录
/login/oauth/access_token     - OAuth 访问令牌

5.2 OAuth 作用域

openid          - OpenID Connect
profile         - 用户基本信息
email           - 电子邮件
offline_access  - 离线访问 (刷新令牌)

5.3 已连接应用

GitHub:   /config/connected-apps/github
Gmail:    /config/connected-apps/gmail
Outlook:  /config/connected-apps/outlook

6. MCP 集成

6.1 MCP 标准方法

typescript

// 工具
interface ToolsListRequest {}  // 列出工具
interface ToolsCallRequest {   // 调用工具
    name: string;
    arguments?: any;
}

// 资源
interface ResourcesListRequest {}  // 列出资源
interface ResourcesReadRequest {   // 读取资源
    uri: string;
}
interface ResourcesSubscribeRequest {  // 订阅资源
    uri: string;
}

// 提示词
interface PromptsListRequest {}  // 列出提示词
interface PromptsGetRequest {    // 获取提示词
    name: string;
}

// 采样
interface SamplingCreateMessageRequest {  // 创建消息采样
    messages: Message[];
    maxTokens: number;
    temperature?: number;
    stopSequences?: string[];
    systemPrompt?: string;
    modelPreferences?: ModelPreferences;
    tools?: Tool[];
    toolChoice?: ToolChoice;
}

6.2 MCP 扩展类型

typescript

type ExtensionType =
    | { type: "http", name: string, url: string, headers?: Header[] }
    | { type: "sse", name: string, url: string, headers?: Header[] }
    | { type: "terminal", name: string, command: string, args?: string[], env?: EnvVar[] };

6.3 本地工具

工具	描述
`fs/read_text_file`	读取文本文件
`fs/write_text_file`	写入文本文件
`terminal/create`	创建终端
`terminal/kill`	终止终端
`terminal/output`	终端输出
`terminal/release`	释放终端
`terminal/wait_for_exit`	等待终端退出

7. 外部 API 端点

从 agnesd 二进制提取的已知外部 API 地址:

提供商	端点	备注
Agnes	`https://api-agnes-code.agnes-ai.com/v1`	BFF
GitHub	`https://api.github.com/repos/`	API
OpenAI	`https://auth.openai.com`	OAuth
AWS Bedrock	`https://bedrock-mantle.{region}.amazonaws.com`	Bedrock
Google Vertex	`https://aiplatform.googleapis.com`	Vertex AI
Anthropic	`https://api.anthropic.com`	(通过 crate 引用)
DeepSeek	`https://api.deepseek.com`	(通过 crate 引用)
Databricks	`https://{workspace}.databricks.com`	Databricks
Atlassian MCP	`https://mcp.atlassian.com/v1/mcp/authv2`	MCP
GitHub Copilot	`https://api.githubcopilot.com/mcp/`	MCP

8. 提供商 API 调用

8.1 通用调用流程

1. 用户发送 prompt
2. agnesd 根据 session 配置确定 provider + model
3. agnesd 将 ACP session/prompt 转换为提供商 API 格式
4. 调用提供商 API (HTTP/HTTPS)
5. 接收响应, 转换为 ACP 格式
6. 返回给 Renderer

8.2 提供商 API 端点 (从 agnesd 二进制提取)

/v1/chat/completions      - OpenAI 兼容聊天补全 (OpenAI, DeepSeek, Qwen, Mistral, Custom)
/v1/messages              - Messages API (Anthropic Claude)
/v1/models                - 模型列表

8.3 密钥存储

所有提供商密钥通过 AGNES_KEYRING_SERVICE 指定的密钥链管理。密钥通过 _agnes/unstable/providers/secrets/ 系列 ACP 方法进行 CRUD 操作。

AgnesCode AI 提供商协议分析报告 ​

1. 架构概述 ​

2. 提供商配置系统 ​

2.1 配置 Schema ​

2.2 设置方式 ​

3. 提供商清单 ​

3.1 完整列表 ​

3.2 提供商配置管理 ​

4. 模型路由 ​

4.1 路由策略 ​

4.2 默认配置 ​

4.3 预定义模型 ​

5. OAuth 集成 ​

5.1 OAuth 端点 ​

5.2 OAuth 作用域 ​

5.3 已连接应用 ​

6. MCP 集成 ​

6.1 MCP 标准方法 ​

6.2 MCP 扩展类型 ​

6.3 本地工具 ​

7. 外部 API 端点 ​

8. 提供商 API 调用 ​

8.1 通用调用流程 ​

8.2 提供商 API 端点 (从 agnesd 二进制提取) ​

8.3 密钥存储 ​

AgnesCode AI 提供商协议分析报告

1. 架构概述

2. 提供商配置系统

2.1 配置 Schema

2.2 设置方式

3. 提供商清单

3.1 完整列表

3.2 提供商配置管理

4. 模型路由

4.1 路由策略

4.2 默认配置

4.3 预定义模型

5. OAuth 集成

5.1 OAuth 端点

5.2 OAuth 作用域

5.3 已连接应用

6. MCP 集成

6.1 MCP 标准方法

6.2 MCP 扩展类型

6.3 本地工具

7. 外部 API 端点

8. 提供商 API 调用

8.1 通用调用流程

8.2 提供商 API 端点 (从 agnesd 二进制提取)

8.3 密钥存储