Developer Docs

开发者文档

神农 API 提供 OpenAI 兼容的 HTTP 接口。使用 API Key 即可在任意语言或框架中调用农业 Agent 大模型与内置工具。

短信登录 / 注册创建 API Key 在线体验快速开始 ↓

概述

对外开放的程序化接口以 POST /api/v1/chat/completions 为主，请求与响应格式与 OpenAI Chat Completions API 兼容，并扩展了 tool_results 字段用于调试工具调用。

注册并获取额度

在控制台创建账户，使用兑换码获取额度后即可按量调用（¥1 ≈ 5 万 tokens，小模型每次调用 ¥0.1）。

创建 API Key

在「API Keys」页面生成 sk-nong-... 密钥，仅创建时完整展示。

发起请求

使用 Bearer 鉴权调用 Chat Completions，可直接对接 OpenAI SDK。

项目	说明
Base URL	生产环境请使用你的部署域名，例如 `https://api.agent-tech.cc`。本地开发为 `http://localhost:3000`。
协议	HTTPS（生产）/ HTTP（本地）
Content-Type	`application/json`
默认模型	`sn`

获取 API Key

短信登录 / 注册神农控制台。
进入 API Keys，点击「创建密钥」并命名（如「生产环境」）。
复制完整密钥（格式 sk-nong-xxxxxxxx），关闭弹窗后无法再次查看。
将密钥存入环境变量，勿提交到代码仓库。

密钥支持启用/停用与删除。停用或删除后，使用该密钥的请求将返回 401。可在控制台查看各密钥的调用次数与最近使用时间。

鉴权

服务端集成请使用 API Key。在控制台「API Keys」页面创建密钥后，在请求头中携带：

HTTP Header

Authorization: Bearer sk-nong-xxxxxxxx

API Key 仅在创建时完整展示一次，请妥善保存。禁用或删除密钥后，对应请求将返回 401。 Playground 页面使用浏览器 Session Cookie 鉴权，不适合服务端调用。

快速开始

最简文本对话（非流式）：

cURL

curl -X POST "https://api.agent-tech.cc/api/v1/chat/completions" \
  -H "Authorization: Bearer sk-nong-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sn",
    "stream": false,
    "messages": [
      { "role": "user", "content": "介绍一下水稻常见病虫害" }
    ]
  }'

SDK 接入

神农 API 与 OpenAI SDK 兼容。将 base_url 指向你的部署地址 + /api/v1 即可，无需修改业务代码。

Python（openai）

pip install openai

pip install openai

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-nong-YOUR_KEY",
    base_url="https://api.agent-tech.cc/api/v1",
)

resp = client.chat.completions.create(
    model="sn",
    messages=[{"role": "user", "content": "玉米叶片发黄可能是什么原因？"}],
)
print(resp.choices[0].message.content)

Node.js / TypeScript（openai）

npm install openai

npm install openai

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SHENNONG_API_KEY,
  baseURL: "https://api.agent-tech.cc/api/v1",
});

const resp = await client.chat.completions.create({
  model: "sn",
  messages: [{ role: "user", content: "介绍一下水稻常见病虫害" }],
});

console.log(resp.choices[0]?.message?.content);

流式（OpenAI SDK）

Python 流式

stream = client.chat.completions.create(
    model="sn",
    stream=True,
    messages=[{"role": "user", "content": "写一首关于春耕的短诗"}],
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

原生 fetch

JavaScript

const res = await fetch("https://api.agent-tech.cc/api/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-nong-YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "sn",
    stream: false,
    messages: [{ role: "user", content: "你好" }],
  }),
});
const data = await res.json();
console.log(data.choices[0].message.content);

Chat Completions

POST/api/v1/chat/completions

创建一次对话补全，支持流式与非流式，可按需启用平台工具。

请求体

字段	类型	说明
`messages`二选一	array	OpenAI 风格消息数组，支持多模态 `image_url`。
`ui_messages`二选一	array	AI SDK UI 消息格式，供 Playground 等前端场景使用。
`model`可选	string	模型 ID，固定为 `sn`。
`stream`可选	boolean	`true` 返回 SSE 流（`chat.completion.chunk`）；`false` 或省略返回单个 JSON 对象。默认非流式。
`temperature`可选	number	采样温度，传给上游模型。
`enabled_tools`可选	string[]	启用的工具 ID 列表，例如 `["vet_list_species", "vet_classify_disease"]`。这些平台工具由服务端执行。未传 `tools` 时，省略本字段会启用全部可用平台工具；显式传空数组可禁用平台工具。
`tools`可选	array	标准 OpenAI function 工具声明。工具 schema 会传给模型，生成的 `tool_calls` 返回客户端执行，服务端不会执行这些客户端工具。
`tool_choice`可选	string / object	支持 `auto`、`none`、`required` 或指定 function 名称。
`parallel_tool_calls`可选	boolean	是否允许模型在一轮中生成多个客户端工具调用。

非流式响应

200 OK

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1718000000,
  "model": "sn",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 128,
    "total_tokens": 170
  },
  "tool_results": [
    {
      "tool_call_id": "...",
      "name": "vet_classify_disease",
      "input": { "species_id": "cow", "file_id": "..." },
      "output": { "success": true, "predicted_chinese": "..." }
    }
  ]
}

tool_results 为平台扩展字段，汇总本次请求中工具执行的输入与输出，便于调试与审计。

消息格式

messages 遵循 OpenAI Chat Completions 约定。每条消息包含 role（system / user / assistant / tool）与 content。assistant.tool_calls 和 tool.tool_call_id 可用于外部 Agent 的多轮工具调用。平台会自动注入系统提示；客户端传入的 system 消息会作为补充提示与平台提示合并，冲突时以平台规则为准。

messages 示例

{
  "messages": [
    { "role": "system", "content": "请用简洁、易懂的语言回答" },
    { "role": "user", "content": "玉米叶片发黄可能是什么原因？" },
    { "role": "assistant", "content": "可能原因包括缺氮、涝害……" },
    { "role": "user", "content": "如果近期降雨偏多呢？" }
  ]
}

多模态图片

用户消息可使用 OpenAI 多模态格式。服务端会自动将图片 ingest 到平台对象存储，供兽医推理等工具使用。

公网 URL：image_url.url 为可访问的 http/https 图片地址（单张最大 20 MB）。
Base64 Data URL：data:image/jpeg;base64,... 同样支持。

多模态 messages

{
  "enabled_tools": ["vet_classify_disease"],
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请分析这张牛的照片可能是什么病" },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/cattle.jpg"
          }
        }
      ]
    }
  ]
}

图片 ingest 后会在服务端生成 file_id。调用 vet_classify_disease 时，若用户消息中仅有一张图片，模型可省略file_id 参数；多张图片时需显式传入对应 file_id。

技能说明

默认允许模型使用当前环境中全部可用技能，也可通过 enabled_tools 限定本次请求允许调用的技能。模型会在对话中自主决定是否触发技能；技能执行结果会计入用量并出现在 tool_results 中。

序号	技能标识	技能说明
兽医疾病推理
1	`vet_list_species`	畜禽种类查询 — 查询兽医疾病推理支持的畜禽种类（牛、猪、羊、鸡）
2	`vet_classify_disease`	兽医疾病推理 — 根据用户上传的畜禽照片推理可能的疾病（支持：牛、猪、羊、鸡）
病虫害识别
3	`pest_classify_grain_crop`	粮食作物病虫害识别 — 根据用户上传的图片识别粮食作物相关病虫害（支持：小麦病虫害、水稻病虫害、玉米病虫害、高粱及其他旱梁作物病虫害、薯类病虫害、大豆病虫害、储粮病虫害）
4	`pest_classify_cash_crop`	经济作物病虫害识别 — 根据用户上传的图片识别经济作物相关病虫害（支持：棉花病虫害、油菜病虫害、花生及其他油料作物病虫害、麻类作物病虫害、糖料作物病虫害、烟草病虫害、茶树病虫害、牧草病虫害、桑树、柞树病虫害、热带作物病虫害）
5	`pest_classify_fruit_vegetable`	果蔬病虫害识别 — 根据用户上传的图片识别果蔬相关病虫害（支持：果树病虫害、西瓜、甜瓜病虫害）
6	`pest_classify_other`	其他病虫害识别 — 根据用户上传的图片识别其他相关病虫害（支持：农田杂草、地下害虫、杂食性昆虫、农牧区鼠害）
县域天气
7	`weather_get_forecast`	天气预报 — 查询中国县区或指定坐标未来 1–15 天逐小时/逐日天气预报（Open-Meteo）
8	`weather_get_history`	历史天气 — 查询中国县区或指定坐标最近两年的历史再分析天气；逐小时单次最多 31 天
植被干旱
9	`drought_get_county_level`	县域干旱等级 — 查询中国大陆县级行政区指定月份的综合植被干旱等级（月尺度 VCI）
10	`drought_get_point_level`	单点干旱等级 — 查询指定 WGS84 坐标所在原始栅格像元的月尺度植被干旱等级
11	`drought_get_metadata`	干旱数据元数据 — 获取干旱数据覆盖范围、时间范围、坐标系和版本
12	`drought_list_region`	干旱行政区查询 — 分页查找省、市、县及六位行政区划代码
13	`drought_get_definition`	干旱等级定义 — 获取植被干旱等级阈值、空值语义和方法约束
CauGen DNA 生成
14	`caugen_list_models`	CauGen 模型查询 — 查询 CauGen 当前可用于 DNA 生成的模型列表
15	`caugen_generate_cds`	CauGen CDS 生成 — 根据输入 DNA 序列生成 CDS 延伸序列
16	`caugen_start_promoter_generation`	CauGen 启动子生成 — 启动异步启动子延伸任务，返回 job_id 供后续查询
17	`caugen_get_promoter_job`	CauGen 启动子任务查询 — 查询启动子生成任务状态或结果（queued/running/finished/failed）
18	`caugen_generate_intron`	CauGen 内含子生成 — 生成 GT-AG 内含子并插入到指定 DNA 序列

兽医疾病推理参数

vet_classify_disease 必须指定 species_id（见下表），并接受可选的 file_id。可先调用 vet_list_species 查询当前环境已加载的畜禽种类。

species_id	动物种类
`cow`	牛
`pig`	猪
`sheep`	羊
`chicken`	鸡

启用工具

{
  "model": "sn",
  "stream": false,
  "enabled_tools": ["vet_list_species", "vet_classify_disease"],
  "messages": [
    { "role": "user", "content": "帮我查一下支持哪些畜禽，并分析我上传的猪照片" }
  ]
}

客户端工具与外部 Agent

通过标准 tools 声明的第三方工具只会提供给模型，平台不会执行。模型返回tool_calls 后，客户端执行对应工具，再把 assistant 工具调用消息和 role=tool 结果一并传入下一轮。传入客户端 tools 时，平台工具默认不启用；需要两类工具同时可用时，请另外传 enabled_tools。

客户端工具请求

{
  "model": "sn",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "Skill",
        "description": "查询指定 skill 是否可用",
        "parameters": {
          "type": "object",
          "properties": { "name": { "type": "string" } },
          "required": ["name"]
        }
      }
    }
  ],
  "messages": [
    { "role": "user", "content": "确认 pdf skill 是否存在" }
  ]
}

tool_calls 响应

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_123",
            "type": "function",
            "function": {
              "name": "Skill",
              "arguments": "{\"name\":\"pdf\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

回传工具结果

{
  "model": "sn",
  "tools": [/* 与上一轮相同的工具声明 */],
  "messages": [
    { "role": "user", "content": "确认 pdf skill 是否存在" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_123",
          "type": "function",
          "function": { "name": "Skill", "arguments": "{\"name\":\"pdf\"}" }
        }
      ]
    },
    { "role": "tool", "tool_call_id": "call_123", "content": "pdf skill 已安装" }
  ]
}

流式响应

设置 "stream": true 后，响应为 Server-Sent Events（SSE），Content-Type 为 text/event-stream。每个事件行为 data: {...}，流结束时发送 data: [DONE]。

流式请求

curl -N -X POST "https://api.agent-tech.cc/api/v1/chat/completions" \
  -H "Authorization: Bearer sk-nong-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sn",
    "stream": true,
    "messages": [{ "role": "user", "content": "写一首关于春耕的短诗" }]
  }'

SSE 帧示例

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1718000000,"model":"sn","choices":[{"index":0,"delta":{"content":"春"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1718000000,"model":"sn","choices":[{"index":0,"delta":{"content":"风"},"finish_reason":null}]}

data: [DONE]

流式模式下，token 用量在流结束后按实际生成内容计费。

错误码

错误响应体通常为 { "error": { "message", "type", "code"? } }。

HTTP	type / code	说明
401	`authentication_error`	未登录或 API Key 无效。
402	`insufficient_balance`	账户余额不足，请先在控制台使用兑换码补充额度。
400	`invalid_request_error`	请求体无效、缺少 messages、图片格式错误等。
502	`upstream_error`	上游模型服务异常（仅非流式）。

计费说明

按 token 计费：¥1 = 5 万 tokens（输入 + 输出合计）。
小模型（如 sn）每次调用另收 ¥0.1（与 token 用量叠加）。
每次调用前会校验账户余额；余额 ≤ 0 时返回 402。
在控制台可查看用量明细、使用兑换码与管理 API Key。

对象存储上传（控制台「文件」页）目前仅支持 Session 登录，暂无独立 HTTP API Key 接口。多模态接入推荐在messages 中直接传入公网图片 URL 或 Base64。