Agently Agent Docs

本页面向 Claude Code、Codex 与其他 Coding Agent，提供 Agently 的核心能力、推荐模式、可复制的代码模板，用于快速实现可靠的 AI 应用。

目标与边界

• 目标：构建稳定、可维护、可编排的 AI 应用代码。
• 边界：Agently 是框架层，运维与评估可接入外部平台。

核心对象

• Agent：高层入口，支持 prompt、输出控制与工具调用。
• Request：一次请求的配置与调用。
• ModelResponse：一次请求快照，支持多次读取结果。
• Output Format：结构化输出约束。
• TriggerFlow：事件驱动编排。

标准工作流

1. 配置模型（OpenAICompatible）。
2. 设计分层 prompt（agent/request）。
3. 用 Output Format 定义稳定结构。
4. get_response() 固定一次请求，再读取结果。
5. 复杂流程用 TriggerFlow。

关键模式与模板

1. 结构化输出（稳定结果）

from agently import Agently

agent = Agently.create_agent()

result = (
  agent
  .input("写一个发布计划，包含目标与里程碑")
  .output({
    "goal": ("str", "目标"),
    "milestones": [
      {"title": ("str", "里程碑"), "date": ("str", "日期")}
    ]
  })
  .start()
)

print(result)

2. 单次请求，多次读取（避免重复请求）

from agently import Agently

agent = Agently.create_agent()

response = (
  agent
  .input("用一句话介绍 Agently")
  .output({"intro": ("str", "一句话")})
  .get_response()
)

print(response.get_text())
print(response.get_data())
print(response.get_meta())

3. 即时流式结构化输出（Instant）

from agently import Agently

agent = Agently.create_agent()

response = (
  agent
  .input("用一句话解释递归，并给出 2 个提示")
  .output({
    "definition": ("str", "Short definition"),
    "tips": [("str", "Short tip")]
  })
  .get_response()
)

for msg in response.get_generator(type="instant"):
  if msg.path == "definition" and msg.delta:
    print(msg.delta, end="", flush=True)
  if msg.wildcard_path == "tips[*]" and msg.delta:
    print(msg.delta, end="", flush=True)
print()

4. 分层 Prompt（上下文治理）

from agently import Agently

agent = Agently.create_agent()

agent.set_agent_prompt("system", "你是企业知识助手")
agent.set_agent_prompt("instruct", ["回答简短、可执行"])

print(
  agent
  .set_request_prompt("input", "给出一条部署建议")
  .output({"advice": ("str", "一句话")})
  .start()
)

5. TriggerFlow 编排（事件驱动）

from agently import TriggerFlow, TriggerFlowEventData

flow = TriggerFlow()

@flow.chunk
async def normalize(data: TriggerFlowEventData):
  return str(data.value).strip().lower()

@flow.chunk
async def greet(data: TriggerFlowEventData):
  return f"hi {data.value}"

flow.to(normalize).to(greet).end()

print(flow.start(" Agently "))

反模式（避免）

• 在链式调用中反复 get_text() / get_data()，会触发多次请求。
• 长流程不用 TriggerFlow，导致分支与并发难以维护。
• 将所有上下文塞进 request，忽略 agent 级别复用。

Agent 自检清单

• 模型配置已设置（OpenAICompatible）。
• 输出已结构化，关键字段可 ensure_keys。
• 已使用 get_response() 固定一次请求。
• 多步流程使用 TriggerFlow。
• 需要流式时使用 get_generator(...) / get_async_generator(...)。