> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.agnes-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agnes 2.5 Flash

> Agnes 2.0 Flash 基础上的灰度升级模型，优化编码专项能力、智能体工作流、工具调用和多模态理解体验。

<Info>
  Agnes 2.5 Flash 是基于 Agnes 2.0 Flash 升级的灰度语言模型。该模型当前仅面向已进入灰度名单的用户开放，并非所有账户默认可用。它沿用 OpenAI 兼容的 Chat Completions 接入方式，同时在编码任务、智能体工作流、工具调用、多轮对话、推理和图像理解体验上进行了优化。
</Info>

<CardGroup cols={2}>
  <Card title="模型名称" icon="cube">
    `agnes-2.5-flash`
  </Card>

  <Card title="API Endpoint" icon="link">
    `POST /v1/chat/completions`
  </Card>

  <Card title="发布状态" icon="flask">
    灰度中，仅灰度用户可访问。
  </Card>

  <Card title="升级路径" icon="arrow-up">
    与 `agnes-2.0-flash` API 兼容。
  </Card>
</CardGroup>

## 概述

Agnes 2.5 Flash 面向已经接入 Agnes 2.0 Flash 的开发者设计。大多数场景下，你只需要把请求中的 `model` 值替换为 `agnes-2.5-flash`；Base URL、Endpoint、请求头、消息格式、流式响应格式、工具调用格式和图像 URL 输入格式保持不变。

该模型重点提升开发者体验、指令遵循稳定性、多轮输出一致性，以及代码生成、调试、重构、解释和智能体编码工作流等代码专项能力。

<Warning>
  Agnes 2.5 Flash 当前仅对灰度用户释放使用。如果你的用户或 API Key 暂未进入灰度名单，模型可能不会出现在模型列表中，或请求时返回模型不可用错误。此时请继续使用稳定回退模型 `agnes-2.0-flash`。
</Warning>

## 核心能力

<CardGroup cols={2}>
  <Card title="聊天补全" icon="message">
    为对话、应用和业务系统生成高质量响应。
  </Card>

  <Card title="多轮对话" icon="comments">
    在连续交互中保持上下文一致性。
  </Card>

  <Card title="图像 URL 输入" icon="link">
    支持通过公开可访问的图像 URL 输入视觉内容。
  </Card>

  <Card title="图像理解" icon="eye">
    可用于截图分析、图像描述、视觉问答和信息提取。
  </Card>

  <Card title="工具调用" icon="wrench">
    支持函数调用和外部工具编排。
  </Card>

  <Card title="智能体工作流" icon="robot">
    优化规划、执行、上下文跟踪和多步骤任务完成体验。
  </Card>

  <Card title="代码专项任务" icon="code">
    针对代码生成、调试、重构、解释和补丁式开发工作流进行优化。
  </Card>

  <Card title="流式输出" icon="bolt">
    支持实时返回响应，提升交互体验。
  </Card>
</CardGroup>

## 适用场景

<CardGroup cols={2}>
  <Card title="AI 助手" icon="robot">
    通用问答、效率助手、个人助理和应用内 Copilot。
  </Card>

  <Card title="自主智能体" icon="diagram-project">
    多步骤任务执行、规划、工具使用和工作流调度。
  </Card>

  <Card title="编码助手" icon="laptop-code">
    代码生成、Bug 排查、重构建议、代码审查、测试生成和代码解释。
  </Card>

  <Card title="客户支持" icon="headset">
    FAQ 自动回复、客服机器人和服务自动化。
  </Card>

  <Card title="搜索与问答" icon="magnifying-glass">
    基于检索的问答、摘要生成和信息提取。
  </Card>

  <Card title="图像理解" icon="image">
    截图分析、图片描述、视觉问答和结构化提取。
  </Card>
</CardGroup>

## 从 Agnes 2.0 Flash 升级

如果你已经在调用 `agnes-2.0-flash`，升级到 2.5 Flash 的改动很小。

| 项目        | Agnes 2.0 Flash                  | Agnes 2.5 Flash                  |
| --------- | -------------------------------- | -------------------------------- |
| Endpoint  | `POST /v1/chat/completions`      | `POST /v1/chat/completions`      |
| Base URL  | `https://apihub.agnes-ai.com/v1` | `https://apihub.agnes-ai.com/v1` |
| 模型名称      | `agnes-2.0-flash`                | `agnes-2.5-flash`                |
| 消息格式      | OpenAI 兼容 `messages`             | 相同                               |
| 流式响应      | `stream: true`                   | 相同                               |
| 工具调用      | `tools` 和 `tool_choice`          | 相同                               |
| 图像 URL 输入 | `messages[].content[].image_url` | 相同                               |

<Tip>
  灰度发布期间，建议在应用配置中保留回退模型。如果当前用户或 API Key 暂未开通 `agnes-2.5-flash`，可以用同一请求回退到 `agnes-2.0-flash`。
</Tip>

## API Reference

### Endpoint

```text theme={null}
POST https://apihub.agnes-ai.com/v1/chat/completions
```

### 请求头

```bash theme={null}
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
```

### 请求参数

| 参数                     | 类型              | 必填 | 说明                                          |
| ---------------------- | --------------- | -- | ------------------------------------------- |
| `model`                | string          | 是  | 模型名称，使用 `agnes-2.5-flash`。                  |
| `messages`             | array           | 是  | 对话消息数组，包含 `system`、`user` 和 `assistant` 消息。 |
| `messages[].content`   | string / array  | 是  | 可为纯文本，也可为包含 `text` 和 `image_url` 的内容块数组。    |
| `temperature`          | number          | 否  | 控制输出随机性。值越低，结果越确定。                          |
| `top_p`                | number          | 否  | 控制核采样。值越低，输出越聚焦。                            |
| `max_tokens`           | number          | 否  | 响应中生成的最大 token 数量。                          |
| `stream`               | boolean         | 否  | 是否启用流式输出。                                   |
| `tools`                | array           | 否  | 工具调用工作流的工具定义。                               |
| `tool_choice`          | string / object | 否  | 控制模型是否使用工具以及如何使用工具。                         |
| `chat_template_kwargs` | object          | 否  | OpenAI 兼容请求中启用 Thinking 等扩展能力。              |
| `thinking`             | object          | 否  | Anthropic 兼容请求中启用 Thinking 模式。              |

## 图像 URL 输入

Agnes 2.5 Flash 支持在同一个 `messages` 请求中同时传入文本和图像 URL。

| 输入类型   | 格式          | 说明                     |
| ------ | ----------- | ---------------------- |
| 文本     | `text`      | 纯文本指令或问题。              |
| 图像 URL | `image_url` | 通过公开可访问的图像 URL 传递图像内容。 |

```json theme={null}
{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Describe the content of this image."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.jpg"
      }
    }
  ]
}
```

## 请求示例

<Tabs>
  <Tab title="基础聊天">
    ```bash theme={null}
    curl https://apihub.agnes-ai.com/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "agnes-2.5-flash",
        "messages": [
          {
            "role": "system",
            "content": "You are a helpful AI assistant."
          },
          {
            "role": "user",
            "content": "Explain how autonomous agents use tools to complete tasks."
          }
        ],
        "temperature": 0.7,
        "max_tokens": 1024
      }'
    ```
  </Tab>

  <Tab title="流式输出">
    ```bash theme={null}
    curl https://apihub.agnes-ai.com/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "agnes-2.5-flash",
        "messages": [
          {
            "role": "user",
            "content": "Write a short product introduction for an AI assistant app."
          }
        ],
        "stream": true
      }'
    ```
  </Tab>

  <Tab title="工具调用">
    ```bash theme={null}
    curl https://apihub.agnes-ai.com/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "agnes-2.5-flash",
        "messages": [
          {
            "role": "user",
            "content": "What is the weather like in Singapore today?"
          }
        ],
        "tools": [
          {
            "type": "function",
            "function": {
              "name": "get_weather",
              "description": "Get the current weather for a location",
              "parameters": {
                "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "The city and country"
                  }
                },
                "required": ["location"]
              }
            }
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="图像理解">
    ```bash theme={null}
    curl https://apihub.agnes-ai.com/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "agnes-2.5-flash",
        "messages": [
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "Describe the content of this image."
              },
              {
                "type": "image_url",
                "image_url": {
                  "url": "https://example.com/image.jpg"
                }
              }
            ]
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

## 响应格式

```json theme={null}
{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "created": 1774432125,
  "model": "agnes-2.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Autonomous agents use tools by understanding the user's goal, breaking it into steps, selecting the right tools, executing actions, and using the results to complete the task."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 35,
    "completion_tokens": 58,
    "total_tokens": 93
  }
}
```

### 响应字段

| 字段                          | 类型      | 说明                          |
| --------------------------- | ------- | --------------------------- |
| `id`                        | string  | 补全请求的唯一 ID。                 |
| `object`                    | string  | 对象类型，通常为 `chat.completion`。 |
| `created`                   | integer | 请求时间戳。                      |
| `model`                     | string  | 请求使用的模型。                    |
| `choices`                   | array   | 生成结果列表。                     |
| `choices[].message.role`    | string  | 消息发送者角色。                    |
| `choices[].message.content` | string  | 模型生成内容。                     |
| `choices[].finish_reason`   | string  | 生成停止原因。                     |
| `usage`                     | object  | Token 使用信息。                 |

## Thinking 模式

对于编码、调试、推理和智能体工作流，可以启用 Thinking 模式以提升任务分解和问题解决能力。

<Tabs>
  <Tab title="OpenAI 兼容格式">
    ```json theme={null}
    {
      "model": "agnes-2.5-flash",
      "messages": [
        {
          "role": "user",
          "content": "Help me write a Python script to process a CSV file."
        }
      ],
      "chat_template_kwargs": {
        "enable_thinking": true
      }
    }
    ```
  </Tab>

  <Tab title="Anthropic 兼容格式">
    ```json theme={null}
    {
      "model": "agnes-2.5-flash",
      "messages": [
        {
          "role": "user",
          "content": "Help me refactor this TypeScript function and explain the changes."
        }
      ],
      "thinking": {
        "type": "enabled",
        "budget_tokens": 2048
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  常规编码任务建议从 `budget_tokens: 2048` 开始；复杂调试、重构或多步骤智能体任务可适当提高预算。
</Tip>

## 最佳实践

<AccordionGroup>
  <Accordion title="提示词结构">
    ```text theme={null}
    [角色] + [任务] + [上下文] + [要求] + [输出格式]
    ```
  </Accordion>

  <Accordion title="产品文案生成">
    ```text theme={null}
    You are a product marketing expert. Write a concise App Store description for an AI assistant app. The tone should be clear, professional, and user-friendly.
    ```
  </Accordion>

  <Accordion title="编码任务">
    ```text theme={null}
    Help me debug this React component. The issue is that the button state does not update after clicking. Explain the cause and provide the corrected code.
    ```
  </Accordion>

  <Accordion title="智能体工作流">
    ```text theme={null}
    You are an autonomous research agent. Search for relevant information, summarize the key findings, and return the result in a structured format with source links.
    ```
  </Accordion>

  <Accordion title="图像理解任务">
    ```text theme={null}
    Analyze this screenshot. Identify the main UI elements, explain the possible issue, and provide suggestions to improve the user experience.
    ```
  </Accordion>
</AccordionGroup>

## 限制与价格

Agnes 2.5 Flash 当前处于灰度状态，仅面向已进入灰度名单的用户开放。可用性、速率限制和计费规则以你的 Agnes AI 账户和 API Key 权限为准。如果该模型暂未对你的 Key 开放，请使用 `agnes-2.0-flash` 作为稳定回退模型。

| 项目    | 数值      |
| ----- | ------- |
| 上下文窗口 | `512K`  |
| 最大输出  | `65.5K` |

| 类型       | 标准价格                | 当前价格             |
| -------- | ------------------- | ---------------- |
| 输入 Token | `$0.03 / 1M tokens` | `$0 / 1M tokens` |
| 输出 Token | `$0.15 / 1M tokens` | `$0 / 1M tokens` |

## 接入检查清单

<Check>
  使用 `agnes-2.5-flash` 作为模型名称。
</Check>

<Check>
  确认当前用户或 API Key 已进入 Agnes 2.5 Flash 灰度名单。
</Check>

<Check>
  基础聊天补全请求必须包含 `model` 和 `messages`。
</Check>

<Check>
  图像输入需要使用公开可访问的 `image_url`。
</Check>

<Check>
  流式响应请将 `stream` 设置为 `true`。
</Check>