Agently 文档

中文

English

中文

English

Appearance

AnthropicCompatible ​

Claude 的原生 API 不是 OpenAI Chat Completions 换一个 URL。Anthropic Messages API 有自己的请求体、header、stream 事件和 tool-use 形态。Agently 因此提供独立的 AnthropicCompatible requester 插件。

指向 https://api.anthropic.com 或 Claude 兼容代理时，用这一页的配置。

最小配置 ​

python
from agently import Agently

Agently.set_settings("AnthropicCompatible", {
    "base_url": "https://api.anthropic.com",
    "api_key": "${ENV.ANTHROPIC_API_KEY}",
    "model": "${ENV.ANTHROPIC_MODEL}",
    "max_tokens": 4096,
})

常用字段：

Key含义
base_urlhttps://api.anthropic.com 或团队代理
api_keybearer token
modelClaude 模型 id
max_tokensAnthropic API 路径上需要特别关注的输出上限
anthropic_versionAnthropic API version header
anthropic_beta可选 beta-feature header，字符串或字符串列表
request_options传给底层 HTTP client 的额外配置

模型 id 会随 Anthropic 发布节奏变化。官网示例使用 ${ENV.ANTHROPIC_MODEL}，让具体模型名由部署环境决定。

为什么不能用 OpenAICompatible ​

Claude 和 OpenAI Chat Completions 至少有这些差异：

  • system prompt 是顶层 system 字段，不是普通 message。
  • max_tokens 是 Anthropic 请求里的关键字段。
  • header 使用 anthropic-version 和可选 anthropic-beta。
  • stream 事件有 message_start、content_block_delta、message_delta 等形态。
  • tool use 的请求 / 响应结构和 OpenAI tools 不同。

AnthropicCompatible 直接实现 ModelRequester。它负责按 Anthropic 协议构造请求、解析响应和适配 Agently result。

结构化输出 ​

Agent 使用方式保持一致：

python
agent = Agently.create_agent()
agent.set_settings("AnthropicCompatible", {
    "model": "${ENV.ANTHROPIC_MODEL_FAST}",
    "max_tokens": 2048,
})

result = (
    agent
    .input("评审这段回复是否清楚。")
    .output({
        "passed": (bool, "是否通过", True),
        "reason": (str, "原因", True),
    })
    .get_result()
)
review = await result.async_get_data(ensure_keys=["passed", "reason"])

协议插件不同，不改变 Agent 的 request / result 消费方式。

Tool use ​

通过 @agent.action_func / agent.use_actions(...) 注册的 Action，会以 Claude 期望的 tool-use 协议暴露给模型。tool 调用结果也会按 Anthropic Messages API 往返。

python
@agent.action_func
def lookup_policy(policy_id: str) -> dict:
    return {"policy_id": policy_id, "status": "active"}

不同 Claude 模型的 tool use 能力、限制和 beta 要求可能不同。生产前用目标模型跑一次真实 Action smoke。

流式 ​

get_async_generator(type="delta") 产出文本增量；type="instant" 产出结构化字段增量。上游 Anthropic stream 事件由插件解析，应用侧仍然通过 Agently result 消费。

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

Beta header ​

需要 Anthropic beta 特性时，设置 anthropic_beta：

python
Agently.set_settings("AnthropicCompatible", {
    "base_url": "https://api.anthropic.com",
    "api_key": "${ENV.ANTHROPIC_API_KEY}",
    "model": "${ENV.ANTHROPIC_MODEL}",
    "max_tokens": 4096,
    "anthropic_beta": "tools-2024-04-04",
})

也可以传列表。有效值以 Anthropic 当前文档和团队验证为准。

另见 ​