Agently 文档

中文

EN

中文

EN

Appearance

OAIClient（OpenAICompatible）参数设置指南（v4） ​

如果你在找「openai 格式」「openai 接口格式」「temperature 怎么设」「tools 怎么配」，这页按 v4 源码把设置优先级和常见坑讲清楚。

说明：OpenAICompatible、OpenAI、OAIClient 在 v4 中是同一个模型请求插件别名。

1. 参数到底在哪里设置 ​

在 v4 里，模型请求参数主要来自两层：

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

request_options 与 agent.options() 最终都会进入 OpenAI 请求体。

2. 源码里的优先级（最关键） ​

根据 OpenAICompatible.generate_request_data() 的合并逻辑，最终优先级如下：

  1. model：固定由插件设置生成
    plugins.ModelRequester.OpenAICompatible.model > default_model[model_type]
    （即使你在 agent.options() 里传了 model，也会被覆盖）
  2. stream：由插件设置最终写回
    plugins...stream 明确值优先；若未设置则 chat/completions=true、embeddings=false
    （即使你在 agent.options() 里传了 stream，也会被覆盖）
  3. 其他请求参数：
    agent.options({...}) 覆盖 request_options

3. 推荐写法（temperature 等） ​

3.1 全局默认参数 ​

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
  }
})

3.2 单次请求临时覆盖 ​

python
agent = Agently.create_agent()

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

4. tools 有两套机制（常见混淆点） ​

4.1 Agently 工具机制（推荐业务编排） ​

使用 @agent.tool_func + agent.use_tools(...)。
这是 Agently 自己的工具编排流程：先判断是否用工具，再把工具结果写入 action_results 继续回答。

python
from agently import Agently

agent = Agently.create_agent()

@agent.tool_func
def add(a: int, b: int) -> int:
  return a + b

agent.use_tools(add)
print(agent.input("用工具算 12+34").start())

4.2 OpenAI 原生 function calling（透传） ​

如果你要走供应商原生 tools/tool_choice，请放到 request_options 或 agent.options() 里。

python
agent = Agently.create_agent()

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"
})

两者可以并存，但语义不同：
agent.use_tools() 是 Agently 侧流程；options.tools 是供应商 API 字段。

5. URL、模型类型与消息构造 ​

  • full_url 有值时，优先于 base_url + path_mapping[model_type]
  • model_type=chat：请求体主字段是 messages
  • model_type=completions：请求体主字段是 prompt
  • model_type=embeddings：请求体主字段是 input，默认非流式
  • strict_role_orders 控制消息 role 顺序整理
  • 有附件时会自动开启 rich_content

6. 鉴权参数怎么选 ​

可选方式：

  • 直接 api_key
  • auth（支持 api_key / headers / body）

示例：

python
Agently.set_settings("OpenAICompatible", {
  "base_url": "https://api.example.com/v1",
  "auth": {
    "headers": {
      "Authorization": "Bearer xxx",
      "X-Project": "demo"
    }
  }
})

7. 快速排错清单 ​

  1. temperature 不生效：确认是写在 request_options 或 agent.options()，不是插件根级 options。
  2. stream 不生效：检查 plugins...stream，它会覆盖请求里的 stream。
  3. model 不生效：model 由插件层最终写入，agent.options({"model": ...}) 不生效。
  4. tools 不生效：先确认你要的是 Agently 工具编排还是 OpenAI 原生 tools 字段。
  5. 路径报错：优先尝试 full_url，避免供应商路径差异。

8. 调试建议 ​

python
from agently import Agently

Agently.set_settings("debug", True)
# 或者：
# Agently.set_settings("runtime.show_model_logs", True)

开启后可看到请求阶段的 request_url、request_options、stream，便于定位参数覆盖问题。

9. 源码依据 ​

  • agently/builtins/plugins/ModelRequester/OpenAICompatible.py
  • agently/builtins/plugins/PromptGenerator/AgentlyPromptGenerator.py
  • agently/builtins/agent_extensions/ToolExtension.py
  • agently/core/Agent.py

相关文档 ​