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

Requests 概览

Agently 里最小的工程单位不是“智能体”，而是一次 request。一次 request 做稳以后，才值得继续接 Actions、Session、Workspace、Dynamic Task 或 TriggerFlow。

这页先把一次 request 拆开看：模型看到什么、应该返回什么、怎么检查、结果怎么读。

一次 request 由四件事组成

部分	解决什么问题	继续读
Prompt	怎么把角色、背景、指令、输入分层给模型	Prompt 管理
Output schema	期望模型返回什么结构	Schema as Prompt
Validation	返回以后怎么解析、检查、retry	输出控制
Result	同一次响应怎么读 text、data、meta、stream	模型响应

下面这段代码同时用到了四件事：

result = (
    agent
    .input("用三条要点总结这篇文章。")
    .output({
        "title": (str, "标题", True),
        "bullets": [(str, "要点", True)],
    })
    .get_result()
)

data = result.get_data()

input() 填入本次 payload。output() 定义结构和必填字段。get_data() 触发模型请求、解析、校验和必要 retry。result 还能继续读取 text、meta 或 stream，不会重发请求。

先把这层做稳

很多项目一开始就去设计 workflow，结果每个节点里还是一段不稳定的模型文本。更好的顺序是：

1. 用 Quickstart 跑通一次结构化请求。
2. 用 输出控制 固定字段、格式、校验和 retry。
3. 用 模型响应 统一读取同一次响应的多个视图。
4. 再根据场景接入 Actions、Session、Workspace 或 TriggerFlow。

Request 层不稳，上层越多越难查。

图片输入

VLM 请求如果是“一个问题 + 一张或多张图片”，使用 .image(...)：

result = (
    agent
    .image(
        question="对比这两张截图，列出可见差异。",
        files=["./before.png", "./after.png"],
    )
    .get_result()
)

单图用 file="..." 或 url="..."，多图用 files=[...] 或 urls=[...]。本地文件会先转成 data:<mime>;base64,... image URL，再走 rich-content prompt 通道。当前本地图片支持 PNG、JPEG、WebP、GIF 和 BMP。

.attachment([...]) 仍作为底层输入方案，适合调用方已经准备好 provider 风格 rich content block，或需要精确控制混合内容顺序。

Sync 和 async 怎么选

脚本和 notebook 可以直接用同步 reader。服务、流式 UI、TriggerFlow、SSE、WebSocket 优先 async：

execution = agent.input("...").output({...})
result = execution.get_result()
data = await result.async_get_data()

继续读：Async First

这层和上层能力的关系

需求	从 request 升级到
多轮对话，需要历史窗口	会话记忆
背景信息来自知识库、检索或固定资料	Context Engineering
多轮任务证据、artifact、checkpoint 要持久保存	Workspace
模型需要调用函数、MCP 或沙箱能力	Actions
流程有分支、并发、暂停恢复	TriggerFlow

上层能力不是 request 的替代品。它们最终还是依赖 request 层的 prompt、output、validation 和 result。

常见误用

• 只在 prompt 里写“请返回 JSON”，不写 .output(...)。
• 为了读文本和结构化数据重复请求同一个 prompt。
• 把所有背景都塞进 input，不分 info、instruct、session 或 KB。
• 单次请求不稳定就上 workflow。
• 服务端沿用同步 demo。

下一步

• Prompt 分层：Prompt 管理
• 结构化输出写法：Schema as Prompt
• 解析、校验和 retry：输出控制
• Result 读取：模型响应