获取当前时间（Current Time）

获取当前时间是蜀农 API 提供的当前时间查询工具，能返回指定时区的日期、时间与二十四节气信息，常用于农事提醒、节气计算、任务调度等场景。

核心能力

能力	说明
时区支持	支持任意 IANA 时区标识，默认 `Asia/Shanghai`
格式灵活	可按需指定输出格式（Java `DateTimeFormatter` 模式），如 `yyyy-MM-dd HH:mm:ss`
二十四节气	返回当前节气、下一节气及其日期与剩余天数，可按需返回整年 24 节气列表
结构化结果	同时返回 `datetime`、`date`、`time`、`weekday`、`unix` 等字段，供模型直接引用
农事场景	为节气计算、农事提醒等场景提供准确的当前时间基准
多工具混合调用	可与天气搜索、知识库检索等工具协同使用，模型自动判断调用优先级与必要性
响应模式灵活	支持流式和非流式响应，两种方式都会返回当前时间与总结内容

前提条件

确保账号已开通当前时间查询服务。
准备 API Key，参考获取 API Key 与鉴权。
查询产生的费用按计费说明执行。

API 示例

Python 示例（OpenAI SDK）

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SHUNONG_API_KEY"],
    base_url="https://ai.agriwis.com/api/v1",
)

completion = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "user", "content": "现在几点？今天是什么日子？"}
    ],
    tools=[
        {
            "type": "agriwis_get_current_time",
            "format": "yyyy-MM-dd HH:mm:ss",
            "timezone": "Asia/Shanghai",
        }
    ],
    tool_choice="auto",
)

print(completion.model_dump_json())

curl 示例

curl https://ai.agriwis.com/api/v1/chat/completions \
  -H "Authorization: Bearer $SHUNONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "user", "content": "现在几点？"}
    ],
    "tools": [
      {
        "type": "agriwis_get_current_time",
        "format": "yyyy-MM-dd HH:mm:ss",
        "timezone": "Asia/Shanghai"
      }
    ],
    "tool_choice": "auto"
  }'

curl 示例（查询全年节气）

with_solar_terms 传 true 返回当年 24 节气完整列表，传四位年份（如 2027）返回指定年份列表：

curl https://ai.agriwis.com/api/v1/chat/completions \
  -H "Authorization: Bearer $SHUNONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "user", "content": "今年清明是哪天？距离处暑还有几天？"}
    ],
    "tools": [
      {
        "type": "agriwis_get_current_time",
        "timezone": "Asia/Shanghai",
        "with_solar_terms": true
      }
    ],
    "tool_choice": "auto"
  }'

请求参数

agriwis_get_current_time 工具参数

参数	类型	说明
`type`	string	固定为 `"agriwis_get_current_time"`
`format`	string	可选。输出格式，Java `DateTimeFormatter` 模式，如 `yyyy-MM-dd HH:mm:ss`（默认）、`yyyy-MM-dd`、`HH:mm:ss`
`timezone`	string	可选。IANA 时区标识，如 `Asia/Shanghai`、`Asia/Tokyo`、`UTC`，默认为 `Asia/Shanghai`
`with_solar_terms`	boolean / integer	可选。`true`（或 `yes`）返回当年 24 节气完整列表；传四位年份（如 `2027`）返回该年份列表；不传时只返回当前节气与下一节气

未传 format、timezone 时使用默认值，默认值可由平台侧工具配置覆盖，接口调用方以实际返回为准。
节气固定按北京时间（UTC+8）口径计算，与 timezone 参数无关；timezone 只影响 datetime、time 等时间字段。

tools、tool_choice 等通用参数说明参见 Chat Completions 与工具调用。

参数校验

参数非法时工具执行失败，模型会收到错误提示而不会返回时间结果：

场景	说明
`timezone` 非法	必须为 IANA 时区标识，如 `Asia/Shanghai`、`UTC`；`GMT+8`、`Beijing` 等写法不被接受
`format` 非法	必须为合法的 Java `DateTimeFormatter` 模式，如 `yyyy-MM-dd HH:mm:ss`

工具返回内容

工具执行后返回如下结构化结果，由服务端注入模型上下文供回答引用，接口响应中只体现模型总结后的内容：

{
  "timezone": "Asia/Shanghai",
  "datetime": "2026-08-19 14:30:25",
  "date": "2026-08-19",
  "time": "14:30:25",
  "weekday": "星期三",
  "unix": 1787121025,
  "solar_term": "立秋",
  "solar_term_date": "2026-08-07",
  "next_solar_term": "处暑",
  "next_solar_term_date": "2026-08-23",
  "days_to_next_solar_term": 4
}

传入 with_solar_terms 时额外返回整年列表：

{
  "solar_term_year": 2026,
  "solar_terms": [
    {"name": "小寒", "date": "2026-01-05"},
    {"name": "大寒", "date": "2026-01-20"}
  ]
}

工具返回字段说明

字段	说明
`timezone`	实际生效的时区标识
`datetime`	按 `format` 格式化后的当前日期时间
`date`	当前日期，`yyyy-MM-dd`
`time`	当前时间，`HH:mm:ss`（秒级，不含毫秒）
`weekday`	星期几，如 `星期三`
`unix`	Unix 时间戳（秒）
`solar_term` / `solar_term_date`	当前所处节气名称及其交节日期（北京时间）
`next_solar_term` / `next_solar_term_date`	下一节气名称及其交节日期
`days_to_next_solar_term`	距离下一节气的天数
`solar_term_year` / `solar_terms`	整年 24 节气列表，仅 `with_solar_terms` 开启时返回，按小寒到冬至的公历顺序排列

响应格式

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "auto",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "当前时间为 2026 年 8 月 19 日（星期三）14:30:25（北京时间），目前处于立秋，距离处暑（8 月 23 日）还有 4 天。",
        "tool_calls": null
      }
    }
  ],
  "usage": {
    "prompt_tokens": 620,
    "completion_tokens": 40,
    "total_tokens": 660,
    "agriwis_get_current_time_usage": {
      "tool_usage": 1
    }
  }
}

响应字段说明

字段	说明
`choices[].message.content`	模型基于工具返回的时间与节气数据的总结回答
`choices[].message.tool_calls`	工具调用信息，纯时间查询场景下通常为 `null`
`usage.agriwis_get_current_time_usage.tool_usage`	当前时间查询工具使用次数
`finish_reason`	生成结束原因，如 `stop`

计费说明

当前时间查询的费用由两部分组成：

查询服务使用次数：按每次查询调用计费。
模型 Token 消耗：查询结果会拼接到提示词中，增加输入 Token，按模型标准价格计费。

具体价格与可用额度以控制台展示为准，参见计费说明。

常见问题

返回的时间与本地时间不一致？

可能的原因：

时区设置：timezone 未传或传错时使用默认时区 Asia/Shanghai，跨时区场景请显式指定 IANA 时区标识。
本地设备偏差：服务端时间已校准，若与本地设备存在细微差异，请以服务端返回为准。

可以用于农事提醒吗？

可以。可将当前时间查询与天气搜索、知识库检索等工具结合使用，例如在特定节气或时间点触发灌溉、施肥、打药等农事提醒。

支持哪些输出格式？

默认格式为 yyyy-MM-dd HH:mm:ss，format 支持 Java DateTimeFormatter 模式，如 yyyy-MM-dd、HH:mm:ss、yyyy年MM月dd日 等。格式串非法时工具执行失败，模型不会返回时间结果。