快速开始

第一次试用 Agently，不需要先理解所有 runtime 概念。先做一件事：让模型返回一个业务代码能检查的结构，而不是一段只能人工看的文本。

这页会跑通一段最小代码，并说明成功以后下一步读什么。

准备一个 Python 环境

Agently 当前文档线面向 Python 3.10+。

pip install -U agently

使用 uv 的项目也可以写成：

uv pip install -U agently

配置一个模型

Agently 的模型配置按协议层选择。大多数 OpenAI Chat Completions 兼容服务使用 OpenAICompatible；Responses API 形态使用 OpenAIResponsesCompatible；Claude / Anthropic Messages API 使用 AnthropicCompatible。

先用一个 OpenAI-compatible 端点举例：

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

${ENV.OPENAI_API_KEY} 表示从环境变量读取。这样 API key 不需要写进代码。

如果使用 Ollama 或其他本地 OpenAI-compatible 服务，把 base_url 指到本地服务地址，例如 http://127.0.0.1:11434/v1，model 写成本地模型名。没有鉴权时可以省略 api_key。

Claude 形态：

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

更多 provider 配置和环境变量写法见 模型设置。

跑第一次结构化请求

下面这段代码让模型输出一个定位和两个亮点。重点不在文案本身，而是输出结构：positioning 要存在，highlights 里的每个元素也要有 title 和 detail。

from agently import Agently

agent = Agently.create_agent()

result = (
    agent
    .input("用一句话写出 Agently 的定位，再写两个产品亮点。")
    .output({
        "positioning": (str, "一句话定位", True),
        "highlights": [
            {
                "title": (str, "亮点标题", True),
                "detail": (str, "一句话描述", True),
            }
        ],
    })
    .get_result()
)

data = result.get_data()
text = result.get_text()

print(data["positioning"])
print(data["highlights"][0]["title"])

第一次读取 data 时会触发模型请求，并把结果缓存下来。后面再读 text 不会重新请求一次模型。

怎么判断它跑通了

成功时，data 应该是一个 dict，并且至少包含：

{
    "positioning": "...",
    "highlights": [
        {"title": "...", "detail": "..."}
    ]
}

如果模型配置不对，通常会在请求阶段报 provider 或网络相关错误。先回到 模型设置 检查 base_url、api_key 和 model。

如果模型返回了文本，但结构化结果解析或必填字段检查失败，进入 输出控制。那里会解释格式、必填字段、retry 和自定义校验。

这段代码里有三个关键点

.input(...)

给模型的任务描述。真实项目里，input 可以来自用户、业务系统、文件或前一步流程。

.output(...)

给模型和运行时看的结果契约。叶子写成 (type, description, ensure)：

• type：字段类型，例如 str、int、float、bool。
• description：告诉模型这个字段要写什么。
• ensure：置为 True 时，该字段是必填项。

.get_result()

拿到一次响应的 result facade。它可以读取 data、text、meta，也可以消费 stream。非一次性脚本建议用这个入口，而不是为了不同读取视图重复发请求。

什么时候不用结构化输出

如果目标只是生成一篇完整文章、一封邮件或一段 Markdown，且下游代码不需要按字段读取，就可以不写 .output(...)：

result = agent.input("写一段 200 字的产品说明。").get_result()
text = await result.async_get_text()

一旦下游要检查字段、保存记录、分支处理或进入业务系统，就回到 .output(...)。

常见误用

• 在 .output(...) 之前自己提示模型“请返回 JSON”，再手写 parser。这样做很容易绕开 Agently 的校验和 retry。
• 把第三槽 True 理解成默认值。它是 ensure 必填标记。
• 为了读 text 和 data 写两次请求。用 get_result() 读同一次响应的多个视图。
• 单次请求还不稳定就开始设计 TriggerFlow。先让请求层稳定。

下一步读什么

• 模型配置更多细节：模型设置
• 输出格式、必填字段和 retry：输出控制
• 一次响应如何读取 text/data/meta/stream：模型响应
• 给模型接外部能力：Actions 概览
• 服务端和流式路径：Async First