Agently 文档

中文

EN

中文

EN

Appearance

快捷语法与 always 参数 ​

快捷语法的价值不是少写几个字符，而是让“输入、约束、输出”在代码里一眼能看懂。

适合什么时候读 ​

  • 你已经理解 Agent / Request 分层，想把代码写得更清晰
  • 你在链式请求里频繁使用 input()、instruct()、output()
  • 你不确定 always=True 到底会把内容写到哪里

你会学到什么 ​

  • 常见快捷语法分别对应哪个 Prompt 槽位
  • always=True 为什么会改变内容归属层级
  • 什么时候该用快捷语法，什么时候该回到底层 set_*_prompt

快捷语法怎么映射到底层槽位 ​

快捷方法底层槽位常见用途
input()input当前任务输入
info()info背景信息、补充事实
instruct()instruct当前任务约束
examples()examplesfew-shot 示例
output()output输出契约
attachment()attachment附件内容
options()options模型请求参数

规则类快捷语法:

快捷方法典型作用备注
rule()注入规则模板常用于稳定行为约束
role()注入角色模板常用于角色定位
user_info()注入用户信息模板常用于用户画像

always=True 的真实含义 ​

always=True 不是“更强的指令”，而是“写入长期层”。这意味着它会影响后续请求，而不只是当前一次。

最小示例 ​

python
from agently import Agently

agent = Agently.create_agent()

# 长期规则
agent.instruct("输出必须简洁。", always=True)
agent.role("企业知识助手", always=True)

response = (
    agent
    .info({"背景": "面向内部开发团队"})
    .input("写一段 Agently 的一句话介绍")
    .instruct("先给定位，再给两个亮点")
    .output(
        {
            "定位": (str, "一句话定位"),
            "亮点": [(str, "一句话亮点")],
        }
    )
    .get_response()
)

print(response.result.get_data())

什么情况下不该用 always=True ​

  • 当前用户输入只对这一次请求有效
  • 当前任务的输出结构只服务当前场景
  • 临时调试规则不应该污染后续请求

如果一个约束只属于这一次调用，就不要把它升到 Agent 层。

什么时候该回到底层 API ​

快捷语法适合可读性优先的请求表达。以下情况更适合用 set_agent_prompt() 或 set_request_prompt():

  • 你要显式写入某个 slot
  • 你要批量处理结构化 Prompt 数据
  • 你在做配置化 Prompt 或导出

常见误区 ​

  • 把 always=True 当成“更高优先级”的意思来用。
  • 为了省事，把所有约束都写进 instruct(..., always=True)。
  • 用快捷语法写得很顺，但已经看不出哪些内容是长期规则，哪些是当前任务。

下一步去哪 ​

  • agently-prompt-management
  • agently-input-composition