# Agnes-2.0-Flash API 完整接口文档

Agnes-2.0-Flash 由 Sapiens AI 开发，是一款快速、高效的语言模型，面向智能体工作流、工具调用、编程任务、推理、多轮对话、图片理解以及高频生产环境应用场景设计。

在 Claw-Eval 基准测试中排名 General Leaderboard 第 9，Pass³ 分数 60.9%。

模型名称: agnes-2.0-flash 上下文: 1M | 最大输出: 65.5K Base URL: https://apihub.agnes-ai.com/v1

## 📋 模型概述

Agnes-2.0-Flash 针对快速、可靠、低成本的语言生成、智能体任务执行和图片理解进行了优化。兼容 OpenAI Chat Completions API 结构。

能力 | 说明
--- | ---
Chat Completion | 为对话和应用生成高质量回复
多轮对话 | 在多轮交互中保持上下文连续性
图片 URL 输入 | 支持通过公网图片 URL 传入图片内容
图片理解 | 支持基于图片的内容理解、截图分析和信息提取
工具调用 | 调用外部工具和函数，支持智能体工作流
智能体工作流 | 支持规划、执行和多步骤任务完成
编程任务 | 辅助代码生成、调试、解释和重构
推理 | 处理结构化推理、任务拆解和决策
流式输出 | 实时返回响应，提升用户体验
OpenAI 兼容 API | 使用兼容 OpenAI Chat Completions API 的结构

## ⚙️ 适用场景

Agnes-2.0-Flash 适用于多种生产级场景：

场景 | 示例用例
--- | ---
AI 助手 | 通用问答、日常助手、效率支持
自主智能体 | 多步骤任务执行、规划和工具使用
编程助手 | 代码生成、调试、重构和解释
工作流自动化 | 任务拆解、流程自动化和执行规划
客户支持 | FAQ 问答、客服聊天机器人、服务自动化
搜索与问答 | 基于搜索的回答、摘要生成、信息提取
内容生成 | 营销文案、文章、产品描述、脚本
开发者工具 | API 助手、文档助手、编程 Copilot
AI 原生应用 | 消费级应用、效率工具、智能体应用
图片理解 | 图片描述、截图分析、视觉问答、信息提取

## POST /chat/completions

Agnes-2.0-Flash 核心对话接口。支持多轮对话、Thinking 模式、工具调用、图片理解、流式响应等全部功能。

POST https://apihub.agnes-ai.com/v1/chat/completions

项目 | 说明
--- | ---
API Endpoint | https://apihub.agnes-ai.com/v1/chat/completions
Request Method | POST
Content-Type | application/json
Authentication | Bearer Token
Authentication Header | `Authorization: Bearer YOUR_API_KEY`

## 📥 请求参数

📥 请求参数

参数名 | 类型 | 必填 | 说明
--- | --- | --- | ---
model | string | 必填 | 模型名称，固定为 "agnes-2.0-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 模式

💡 提示：`messages[].content` 可使用纯文本字符串，也可使用包含 `text` 和 `image_url` 的内容数组来传入图片。

## 💬 示例 1：基础 Chat Completion 请求

用于生成普通的聊天补全响应。

    curl https://apihub.agnes-ai.com/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "agnes-2.0-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
      }'

    from openai import OpenAI

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://apihub.agnes-ai.com/v1"
    )

    response = client.chat.completions.create(
        model="agnes-2.0-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
    )

    print(response.choices[0].message.content)

## ⚡ 示例 2：流式输出请求

启用流式输出，实时接收模型生成的 token。

    curl https://apihub.agnes-ai.com/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "agnes-2.0-flash",
        "messages": [
          {"role": "user", "content": "Write a short product introduction for an AI assistant app."}
        ],
        "stream": true
      }'

    from openai import OpenAI

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://apihub.agnes-ai.com/v1"
    )

    stream = client.chat.completions.create(
        model="agnes-2.0-flash",
        messages=[
            {"role": "user", "content": "Write a short product introduction for an AI assistant app."}
        ],
        stream=True
    )

    for chunk in stream:
        content = chunk.choices[0].delta.content
        if content:
            print(content, end="", flush=True)

    const response = await fetch('https://apihub.agnes-ai.com/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        model: 'agnes-2.0-flash',
        messages: [{ role: 'user', content: 'Write a short product introduction for an AI assistant app.' }],
        stream: true
      })
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    let buffer = '';

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });
      const lines = buffer.split('\n');
      buffer = lines.pop();
      for (const line of lines) {
        if (!line.startsWith('data: ') || line === 'data: [DONE]') continue;
        const chunk = JSON.parse(line.slice(6));
        const content = chunk.choices[0]?.delta?.content;
        if (content) process.stdout.write(content);
      }
    }

## 🔧 示例 3：工具调用请求

用于需要外部工具调用的智能体工作流。模型会返回工具调用请求，开发者执行后需将结果传回。

    curl https://apihub.agnes-ai.com/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "agnes-2.0-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"]
            }
          }
        }]
      }'

    from openai import OpenAI

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://apihub.agnes-ai.com/v1"
    )

    response = client.chat.completions.create(
        model="agnes-2.0-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"]
                }
            }
        }]
    )

    msg = response.choices[0].message
    if msg.tool_calls:
        for tc in msg.tool_calls:
            print(f"Tool: {tc.function.name}, Args: {tc.function.arguments}")

## 🖼️ 示例 4：图片 URL 输入请求

通过图片链接传入图片，让模型理解或分析图片内容。`messages[].content` 使用数组结构，可同时包含文本和图片。

图片内容结构

输入类型 | 支持方式 | 说明
--- | --- | ---
text | text | 普通文本指令或问题
image_url | image_url | 通过公网可访问的图片链接传入图片

    curl https://apihub.agnes-ai.com/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "agnes-2.0-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"}}
          ]
        }]
      }'

    from openai import OpenAI

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://apihub.agnes-ai.com/v1"
    )

    response = client.chat.completions.create(
        model="agnes-2.0-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"}}
            ]
        }]
    )

    print(response.choices[0].message.content)

## 📤 响应格式

📤 响应示例

    {
      "id": "chatcmpl_xxx",
      "object": "chat.completion",
      "created": 1774432125,
      "model": "agnes-2.0-flash",
      "choices": [{
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Autonomous agents use tools by understanding the user's goal..."
        },
        "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[].index | integer | 响应结果的索引
choices[].message | object | Assistant 消息对象
choices[].message.role | string | 消息发送者角色
choices[].message.content | string | 模型生成的响应内容
choices[].finish_reason | string | 生成停止原因
usage | object | Token 使用信息
usage.prompt_tokens | integer | 输入 token 数量
usage.completion_tokens | integer | 输出 token 数量
usage.total_tokens | integer | 使用的 token 总数

## 🧠 Thinking 模式

对于代码编写、调试、推理和 Agent 工作流，建议开启 Thinking 模式，以提升代码质量、任务拆解能力和问题解决效果。

OpenAI 兼容请求

在请求体中添加 `chat_template_kwargs.enable_thinking`：

    {
      "model": "agnes-2.0-flash",
      "messages": [
        { "role": "user", "content": "Help me write a Python script to process a CSV file." }
      ],
      "chat_template_kwargs": {
        "enable_thinking": true
      }
    }

Anthropic 兼容请求

使用 `thinking` 字段，支持 `budget_tokens` 控制最大 Token 预算：

    {
      "model": "agnes-2.0-flash",
      "messages": [
        { "role": "user", "content": "Help me refactor this TypeScript function and explain the changes." }
      ],
      "thinking": {
        "type": "enabled",
        "budget_tokens": 2048
      }
    }

💡 建议：常见编码任务建议从 `budget_tokens: 2048` 开始。更复杂的调试、重构或多步骤 Agent 任务可适当提高该值。

## 🖼️ 图片 URL 使用建议

- 图片 URL 必须可公网访问。
- 如果图片 URL 需要登录、鉴权或存在防盗链，模型可能无法读取。
- 建议使用标准图片格式：`JPG`、`JPEG`、`PNG` 或 `WebP`。
- 对于截图、报错图、产品界面图，建议在文本中补充你希望模型重点关注的问题。
- 图片 URL 输入可以与工具调用、流式输出和 Agent 工作流结合使用。

## 📐 最佳实践

推荐 Prompt 结构：[角色] + [任务] + [上下文] + [要求] + [输出格式]

示例：产品文案生成

    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.

示例：编程任务

    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.

示例：智能体工作流

    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.

示例：图片理解任务

    Analyze this screenshot. Identify the main UI elements, explain the possible issue, and provide suggestions to improve the user experience.

## 📏 模型限制

项目 | 数值
--- | ---
Context | 1M
Max Output | 65.5K

## 💰 价格

Agnes-2.0-Flash 当前提供免费使用。

类型 | 原价 | 现价
--- | --- | ---
Input Tokens | $0.03 / 1M tokens | $0 / 1M tokens
Output Tokens | $0.15 / 1M tokens | $0 / 1M tokens

## 📝 使用说明

- 使用 `agnes-2.0-flash` 作为模型名称。
- 基础 Chat Completion 请求必须包含 `model` 和 `messages`。
- `messages[].content` 可使用纯文本字符串，也可使用包含文本和图片 URL 的内容数组。
- 如需输入图片，请使用 `image_url` 并提供公网可访问的图片 URL。
- 如需启用流式响应，请将 `stream` 设置为 `true`。
- 对于工具调用工作流，请提供 `tools`，并可按需提供 `tool_choice`。
- `temperature` 用于控制随机性。较低值更适合确定性任务，较高值更适合创意生成。
- Agnes-2.0-Flash 适合需要快速响应、强任务完成能力、图片理解能力和可靠智能体表现的生产级应用。

📄 本文档基于 Agnes-2.0-Flash 官方 API 文档整理

模型: agnes-2.0-flash · 开发商: Sapiens AI · 文档日期: 2025-06-25

API Endpoint: https://apihub.agnes-ai.com/v1 · 兼容: OpenAI Chat Completions API