Agently 文档

中文

EN

中文

EN

Appearance

常见使用场景 ​

适用版本：4.0.8+

场景 1：多用户聊天（最常见） ​

目标：每个用户历史隔离，并自动复用。

python
def handle_chat(user_id: str, text: str):
    agent.activate_session(session_id=user_id)
    try:
        return agent.input(text).get_text()
    finally:
        # 业务需要可选择保持激活或关闭
        agent.deactivate_session()

建议：

  • session_id 使用稳定主键
  • 若是多租户，使用 tenant:user 组合键

场景 2：HTTP 无状态接口 + 外部持久化 ​

目标：服务无状态，但每次请求都能恢复上下文。

python
from agently.core import Session


def request_once(user_id: str, text: str, load_snapshot: str | None):
    if load_snapshot:
        s = Session(settings=agent.settings)
        s.load_json_session(load_snapshot)
        agent.sessions[s.id] = s
        agent.activate_session(session_id=s.id)
    else:
        agent.activate_session(session_id=user_id)

    reply = agent.input(text).get_text()
    snapshot = agent.activated_session.get_json_session()
    return reply, snapshot

场景 3：隐私合规的最小记录 ​

目标：只记录必要字段，避免写入敏感原文。

python
agent.activate_session(session_id="compliance_demo")
agent.set_settings("session.input_keys", ["input.ticket_id", "input.intent"])
agent.set_settings("session.reply_keys", ["resolution", "risk_level"])

result = (
    agent
    .input({"ticket_id": "T-1001", "intent": "refund", "raw_text": "...PII..."})
    .output({"resolution": (str,), "risk_level": (str,)})
    .get_data()
)

场景 4：长对话 + 自定义 memo ​

目标：控制窗口长度，同时沉淀稳定事实。

python
agent.activate_session(session_id="long_chat")
session = agent.activated_session
agent.set_settings("session.max_length", 12000)


def analysis_handler(full_context, context_window, memo, session_settings):
    if len(context_window) > 10:
        return "compress"
    return None


async def compress(full_context, context_window, memo, session_settings):
    kept = list(context_window[-6:])
    # 这里可以接 LLM 做摘要
    new_memo = memo or {}
    new_memo["compressed_rounds"] = new_memo.get("compressed_rounds", 0) + 1
    return None, kept, new_memo


session.register_analysis_handler(analysis_handler)
session.register_execution_handlers("compress", compress)

场景 5：跨端恢复（Web -> Worker） ​

目标：前端会话迁移到异步任务进程继续处理。

  • Web 层导出 session_json
  • 投递到队列
  • Worker 层 load_json_session 后继续 activate_session

适合：长任务、异步编排、人工审核接力。