Agently Docs

English

中文

English

中文

Appearance

English mirror

This English page is generated from the current Chinese documentation so every route, anchor, code sample, and language switch stays available on agently.tech. Human-edited English copy can replace this generated body page by page.

Read the Chinese source page

OpenAICompatible ​

OpenAICompatible 是 Agently 中使用最广的模型 requester 插件。只要 provider 暴露的是 OpenAI Chat Completions 兼容协议，通常就用它。DeepSeek、Qwen 兼容模式、Kimi、GLM、SiliconFlow、Groq、Ollama、本地 vLLM / LM Studio 这类路径，都属于这个范围。

最小配置 ​

python
from agently import Agently

Agently.set_settings("OpenAICompatible", {
    "base_url": "https://api.openai.com/v1",
    "api_key": "${ENV.OPENAI_API_KEY}",
    "model": "${ENV.OPENAI_MODEL}",
})

常用字段：

Key含义
base_urlAPI 根地址，如 https://api.deepseek.com/v1
api_keybearer token；本地无鉴权服务可省略
modelprovider 模型名
model_type"chat" 默认；"completion" 仅给旧 completion 端点
request_retry临时传输错误重试策略；默认 {"max_attempts": 2}
request_options传给底层 HTTP client 的额外配置，如 timeout、headers

配置后，Agent 正常使用结构化输出：

python
agent = Agently.create_agent()
result = (
    agent
    .input("把这条工单分到合适团队。")
    .output({
        "team": (str, "处理团队", True),
        "reason": (str, "分流理由", True),
    })
    .get_result()
)
route = await result.async_get_data(ensure_keys=["team", "reason"])

怎么判断端点是否兼容 ​

通常看 provider 文档是否满足这些条件：

  • 请求体使用 messages，每条消息有 role 和 content。
  • 主要参数是 model、temperature、max_tokens、tools 这类 OpenAI 风格字段。
  • 普通响应和 SSE 流式响应接近 Chat Completions。

满足这些条件，就先从 OpenAICompatible 开始。如果 provider 明确要求 Anthropic Messages API，读 AnthropicCompatible。如果端点是 Responses API，用对应的兄弟插件。

Responses API 不是 Chat Completions ​

OpenAI 自身和部分网关会暴露 Responses API。Agently 为它提供独立插件：

python
Agently.set_settings("OpenAIResponsesCompatible", {
    "base_url": "https://api.openai.com/v1",
    "api_key": "${ENV.OPENAI_API_KEY}",
    "model": "${ENV.OPENAI_RESPONSES_MODEL}",
})

OpenAIResponsesCompatible 和 OpenAICompatible 是兄弟插件，不是继承关系。按端点实际协议选，不要只看 provider 名字。

流式响应 ​

OpenAICompatible 支持 result generator：

python
result = agent.input("写一个简短回复。").output({
    "reply": (str, "回复正文", True),
}).get_result()

async for item in result.get_async_generator(type="instant"):
    render_delta(item.path, item.delta)

final = await result.async_get_data(ensure_keys=["reply"])

type="instant" 面向结构化字段增量。普通文本 delta 也可以通过 result 的流式 reader 消费。Provider 如果流式格式不完全标准，插件会尽量容忍；遇到具体不兼容，应该用最小复现反馈。

Tools 和 Actions ​

Action Runtime 会把注册的 Actions 映射到 provider 支持的 tool calling 协议。只要端点真实支持 OpenAI 风格 tools，OpenAICompatible 就能承接。

python
@agent.action_func
def get_order_status(order_id: str) -> dict:
    return {"order_id": order_id, "status": "shipped"}

模型是否愿意调用工具，仍取决于 prompt、工具描述、模型能力和输出控制。插件只负责协议映射。

传输错误重试 ​

连接重置、provider 断开这类临时传输错误，如果还没有任何输出发出，OpenAICompatible 默认会用同一个请求重试一次。这样可以抹平少量网络抖动。

关闭或调整：

python
Agently.set_settings("OpenAICompatible", {
    "request_retry": {"max_attempts": 1},
})

一旦输出已经开始，Agently 不会自动重放 stream，避免重复 partial content。

Provider recipe ​

常见 provider 的 base URL 和环境变量占位见 Provider 配置。模型名变化很快，recipe 只提供配置形状；上线前应在团队环境里用真实 key 跑一次最小请求。

另见 ​