Agently 文档

中文

English

中文

English

Appearance

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 跑一次最小请求。

另见 ​