Agently 文档

中文

EN

中文

EN

Appearance

OpenAI 接口格式与请求规范 ​

这页不是给第一次接触 Agently 的人读的。它解决的是更细的问题：当你已经在用 OpenAICompatible，却发现参数覆盖、tools 或 stream 行为和预期不一致时，应该怎么判断。

适合什么时候读 ​

  • 你已经能完成基础模型配置
  • 你想搞清 request_options、agent.options()、model、stream 的覆盖顺序
  • 你在处理 OpenAI 原生 tools 和 Agently 自己的工具机制时出现混淆

你会学到什么 ​

  • OpenAICompatible 的参数合并逻辑
  • model / stream 和普通请求参数的边界
  • Agently 工具体系和 OpenAI 原生 tools 字段的区别

参数优先级图 ​

这张图直接嵌在正文里，是为了说明一个关键边界：request_options 可以被请求层覆盖，但 model / stream 最终由 requester 层定稿。

参数到底在哪里设置 ​

层级写法典型参数作用范围
全局/Agent 设置层Agently.set_settings("OpenAICompatible", {...})base_url model request_options stream默认影响后续请求
单次请求层agent.options({...})temperature top_p max_tokens tools仅当前请求

最关键的覆盖规则 ​

  1. model：由插件设置最终决定
  2. stream：由插件设置和 model_type 决定
  3. 其他请求参数：agent.options({...}) 可以覆盖 request_options

推荐写法 ​

全局默认参数 ​

python
from agently import Agently

Agently.set_settings(
    "OpenAICompatible",
    {
        "base_url": "https://api.openai.com/v1",
        "api_key": "YOUR_API_KEY",
        "model": "gpt-4o-mini",
        "request_options": {
            "temperature": 0.2,
            "top_p": 0.9,
            "max_tokens": 800,
        },
    },
)

单次请求临时覆盖 ​

python
result = (
    agent
    .input("解释一下 RAG")
    .options({"temperature": 0.7, "max_tokens": 300})
    .start()
)

tools 为什么容易混淆 ​

Agently 工具体系 ​

适合业务编排和日志观测：

  • @agent.tool_func
  • agent.use_tools(...)

OpenAI 原生 tools 字段 ​

适合直接透传供应商 API 字段：

python
agent.options(
    {
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "Get current weather",
                    "parameters": {
                        "type": "object",
                        "properties": {"city": {"type": "string"}},
                        "required": ["city"],
                    },
                },
            }
        ],
        "tool_choice": "auto",
    }
)

快速排错清单 ​

  1. temperature 不生效：确认写在 request_options 或 agent.options()
  2. stream 不生效：检查插件层 stream
  3. model 不生效：agent.options({"model": ...}) 不会成为最终定稿
  4. tools 不生效：先分清你走的是 Agently Tools 还是 OpenAI 原生 tools
  5. 路径报错：优先试 full_url

下一步去哪 ​

  • agently-model-setup
  • agently-agent-extensions