Agent-engine-sdk-langgraph

安装

pip install agent-engine-sdk-langgraph

或者在 uv项目中：

uv add agent-engine-sdk-langgraph

最小代理

from agent_engine_sdk_langgraph import App
from langgraph.graph import StateGraph, MessagesState
from langgraph.prebuilt import ToolNode
app = App(app_name="my-agent", app_version="1.0.0")
@app.tool()
def lookup(query: str) -> str:
    """Search the knowledge base."""
    return "result for " + query
@app.entrypoint
def build_agent():
    from langchain_openai import ChatOpenAI
    llm = app.llm(ChatOpenAI(model="gpt-5.4"))
    tools = app.get_tools()
    def call_model(state: MessagesState):
        response = llm.invoke(state["messages"])
        return {"messages": [response]}
    graph = StateGraph(MessagesState)
    graph.add_node("agent", call_model)
    graph.add_node("tools", ToolNode(tools))
    graph.set_entry_point("agent")
    graph.add_edge("tools", "agent")
    return graph.compile(checkpointer=app.checkpointer())
app.run()

使用内存

app.memory 是统一的 `agent-engine-sdk-memory <../agent-engine-sdk-memory/README.md>`__ Memory 门面（在平台运行时上受应用程序限制）。每次来自参数、绑定上下文或环境执行上下文的调用时，都会解析身份。

app = App(app_name="my-agent")
# Save a semantic fact — returns CreateSemanticResult
result = app.memory.save_semantic(
    text="User prefers dark mode",
    label="pref-theme",
    user_id="u1",
    metadata={"channel": "web", "priority": "high"},  # optional caller-supplied metadata
)
if result.acknowledged:
    ...
# Search — returns list[MemoryChunk]
chunks = app.memory.search_semantic(query="user preferences", user_id="u1")
for chunk in chunks:
    print(chunk.content)
# Build prompt context — returns ContextResponse
# Default sources are LTM (episodic + semantic); pass
# enabled_sources={"stm", ...} to include recent turns.
context = app.memory.build_context(query="help me", user_id="u1")
prompt_block = context.formatted_context  # str (or structured list, depending on format)

build_context_from_sources （按源检索模式、筛选器和 top_k）在环境 app.memory 运行时上可用。它返回完整的 ContextResponse，因此每个源的元数据(ranking_strategy、source_outcomes) 会保留下来；平台会对租户进行标记，并通过持久性执行将响应传回。仅当请求 stm 源时才需要 session_id。

from agent_engine_sdk_langgraph import Memory 重新导出与 agent_engine_sdk_memory.Memory 相同的类。自行构建 Memory(api_key=...) / Memory(base_url=...) 是HTTP/direct 路径 — 不受环境应用限制。

当这个问题发生时

这是一个难题：app.memory 上没有双API ，也没有兼容性填充程序。客户数代理仅在重建代理映像时中断，该映像拾取包含此 SDK 的基于 Runner 的轮子。仅进行平台合并或重新部署旧代理映像不会更改已嵌入该映像中的 SDK 代码。不存在存储内存数据迁移— 只有客户端返回形状和调用约定发生变化。

从 pre-facade 表面迁移

• 返回类型/真实性/元数据/``build_context``：使用 acknowledged 写入返回类型化结果（CreateSemanticResult、CreateEpisodicResult 等），而不是裸露的 bool/字典。首选 if result.acknowledged:（而非 if result: — Pydantic 模型始终为 true）。相似性搜索返回 list[MemoryChunk]（chunk.content，可选 chunk.similarity_score）。曾经是顶级字典键的松散字段（title，summary，tags，term，definition，related_terms，...）位于 chunk.metadata 下（例如 ep.metadata.get("title") 而不是ep.get("title")）。 build_context 返回 ContextResponse；使用 context.formatted_context，而不是字符串形式的返回值。

• 写入助手只能使用关键字 (save_semantic(text=..., label=..., …))。位置调用引发 TypeError。

• 使用“visibility="private"”进行读取会保留环境用户过滤（之前传递任何 visibility 参数都会删除该筛选器）：私有可见性搜索现在仅返回当前用户的记忆，除非传递了显式 user_id。

• ``top_k``：每个源的 search_semantic/search_episodes/search_taxonomic默认为 top_k=50（通常为 10）。 discover_procedures 仍默认为 10。统一 Memory.search() 仍默认为 top_k=10。公共 build_context 没有 top_k 参数。使用 max_tokens 作为上下文构建总预算（而不是获取费用）。在检索和排名后，服务器减去 500-令牌格式保留，然后贪心地选择适合余数的整个内存块。等于或低于 500 的正值不会留下内存预算。当没有适合的数据块时，高于 500 的值仍可能产生空上下文。如果需要旧限制，请在搜索助手上传递显式 top_k。

• 身份：无法解析的必填字段引发 MemoryIdentityError（不再有软 None/静默跳过）。 save_episode 需要可解析的 session_id（环境调用上下文即可；否则会显式传递或绑定 MemoryRequestContext）。空白值不算作设立。

• 应用程序绑定的创建保真度：创建结果 id 可能是 ""，has_embedding 通常是 False — 在 .acknowledged（而不是 id）上启动成功。每个操作的详细信息位于内存包功能矩阵中。

• 获取与搜索： get_semantic /get_taxonomic_term / list_episodes 在应用绑定时仍会返回松散类型的字典。只有 search* 方法会返回 list[MemoryChunk]。

• 重命名：如果有人调用了外观前名称，请使用外观公共API — create_taxonomic → save_taxonomic； list_taxonomic_domains → list_domains。

之前/之后

# save_semantic: bool → .acknowledged; positional → keyword-only
# before
ok = app.memory.save_semantic("User prefers dark mode", "pref-theme", user_id="u1")
if ok:
    ...
# after
result = app.memory.save_semantic(
    text="User prefers dark mode",
    label="pref-theme",
    user_id="u1",
)
if result.acknowledged:
    ...

# save_episode: str|None → CreateEpisodicResult (.acknowledged / .id)
# before
doc_id = app.memory.save_episode(title="Quote chat", content=summary, user_id="u1")
if doc_id:
    ...
# after
episode = app.memory.save_episode(
    title="Quote chat",
    content=summary,
    user_id="u1",
    metadata={"channel": "web", "priority": "high"},  # optional caller-supplied metadata
    # session_id from ambient context, or pass explicitly
)
if episode.acknowledged:
    print(episode.id)  # may be "" on app-bound

# search_episodes: dict.get → MemoryChunk metadata + content; pin top_k if needed
# before
episodes = app.memory.search_episodes(query="policy quote", top_k=10)
for ep in episodes:
    print(ep.get("title"), ep.get("content"))
# after
episodes = app.memory.search_episodes(query="policy quote", top_k=10)
for ep in episodes:
    print(ep.metadata.get("title"), ep.content)

# build_context: str → ContextResponse.formatted_context
# before
prompt = app.memory.build_context(query="help me", user_id="u1")
# after
context = app.memory.build_context(query="help me", user_id="u1")
prompt = context.formatted_context

引用迁移（在助手引擎示例存储库中）：

• agents/insurance-agent/src/insurance_agent/main.py

每个后端的功能差异和应用程序限制的差距记录在内存包功能矩阵中。 Memory 外观的方法级文档位于agent-engine-sdk-memory 中。

使用 agent.yaml 中的 features.memory: true 启用内存，或者当省略该功能标志时使用旧版 ENABLE_MEMORY=true 环境变量启用内存。现有应用仍可将 enable_memory=... 或 enable_tracing=... 传递给 App(...)，但这些构造函数标志已弃用：将内存移至 agent.yaml，并完全删除enable_tracing，因为跟踪始终开启。

目录布局

my_agent/
  skills/
    security-checklist/
      SKILL.md
    style-guide/
      SKILL.md

将 skills/ 父目录传递给 skills=[...]。在运行时，deepagents 通过配置的后端列出该目录，并发现每个包含 SKILL.md 作为一项技能的直接目录。发现深一层，而不是递归的。

SKIL.md frontmatter

---
name: security-checklist
description: Security review rules for Python code, focusing on injection and auth
---
# Security Checklist
## REVIEW-RULE-ID-SEC-1: SQL injection
Never concatenate user input into SQL...
## REVIEW-RULE-ID-SEC-2: Command / path injection
Calls to `subprocess.run`, `os.system`, `shell=True`, and `open()` must not
interpolate untrusted input...

Deepagents 在运行时验证技能frontmatter。它会跳过不可读或无法解析的 frontmatter 以及缺少 name 或 description 的技能；客服技能命名或目录名称违规会产生警告，但仍可能加载。 SDK 会转发已声明的路径，而不对其进行检查或筛选。

将技能融入代理中

features:
  deep_agent: true

from langchain_openai import ChatOpenAI
from agent_engine_sdk_langgraph import App
app = App(app_name="My Reviewer")
@app.entrypoint
def build_agent():
    return app.deep_agent(
        llm=ChatOpenAI(model="gpt-5.4"),
        system_prompt="You are a code reviewer.",
        skills=["skills"],
    )
app.run()

每个 skills=[...] 条目都是父源目录，而不是叶技能目录或 SKILL.md文件。路径是相对于包含 agent.yaml 的目录的，因此 skills=["skills"] 适用于单代理映像 (/app/skills) 和单一存储库映像 (/app/<agent-subdirectory>/skills)。如果您的技能位于代理源代码树内的其他位置，请将 AGENTIC_SKILLS_DIR设立为该相对目录，并使 skills=[...] 相对于该目录。在运行时，deepagents 从每个发现的技能中读取 frontmatter，并将其元数据（名称、描述和解析路径）作为系统提示符中的技能系统区块传递给 LLM。

渐进式披露

在第 1 回合，LLM 只能看到技能元数据，而看不到技能体。当用户询问安全性时，LLM 决定 read_file("<agent-dir>/skills/security-checklist/SKILL.md")，并且全文作为 ToolMessage 到达上下文中，轮流 2。

这样可以保持基本提示的简洁性（元数据大约是每个技能的50 个词元），同时允许按需加载深入的专业知识。

捆绑技能文件和沙盒

ToolPod 的可写文件系统和Shell处理程序仍使用 WORKSPACE_DIR，即默认为 /tmp/agent-workspace。将其保留为暂存空间。

捆绑的技能将被视为只读资源。 ToolPod 从 AGENTIC_AGENT_CONFIG_PATH 或 AGENTIC_AGENT_WORKDIR 派生出默认技能根：如果运行时配置为 /app/agent.yaml，则技能根为 /app/skills；如果运行时配置为 /app/agents/reviewer/agent.yaml，则技能根为 /app/agents/reviewer/skills。 AGENTIC_SKILLS_DIR 会覆盖该根，并且必须相对于代理源根。只读文件系统工具可以加载该根目录下的文件，而无需将 WORKSPACE_DIR 设置为技能目录。写入、编辑和Shell操作仍保留在可写工作区中。技能根在 Tool Pod初创企业解析，而不是在 SDK 导入时解析，因此普通的静态 SDK 导入可以正常工作 — 不需要导入顺序解决方法。

子代理非继承

技能仅对声明技能的代理可见。如果您的代理生成了子代理（通过 task 工具），这些子代理不会继承父代理的技能。在每个需要技能文件的子代理规范上传递 skills=[...]。

保留的工具名称

深度代理运行时为内置工具保留 9 工具名称。请勿使用以下任何名称注册 @app.tool() — 它会默默地隐藏内置函数并破坏技能/沙盒行为：

• read_file、write_file、edit_file、ls、glob、grep（文件系统）

• execute (Shell)

• write_todos （规划中）

• task (subagent dispatch)

选择发生冲突的名称会默默地影响内置— 不会出现导入时错误。

尺寸指导

目标 <每个 SKILL.md 正文 200 行。更大的技能：

• 加载时使用更多上下文（每个 read_file 都是一个全文转储）

• 在复杂回合中遇到 LLM 的单消息上下文限制的风险

• 建议将技能分割为多个有针对性的文件

提示：编辑 SKILL.md 后重置线程

运行时在线程的生命周期内以代理状态缓存 skills_metadata。如果编辑 SKILL.md文件，现有线程将继续使用过时的元元数据，直到重置。在开发中：删除线程或启动新会话。在生产中：技能更改应与新模型/提示版本的发布同时进行。

完整的最小示例

有关参考实施，请参阅代理引擎示例存储库中的 Code Reviewer 代理：

• 助手引擎示例存储库agents/code-reviewer-agent/src/code_reviewer_agent/main.py — 连线

• 助手引擎示例存储库agents/code-reviewer-agent/skills/*/SKILL.md —示例技能

持久性原生中断

持久工作流程重放 LangGraph 的原生interrupt() 调用，并将其新生成的原生ID 转换为之前记录的 OE 活动位置。有关完整的暂停、重放和 Command(resume=...) 流程及其代码调用站点，请参阅持久性 LangGraph 中断和恢复。

要求

• Python >= 3.11

• uv

开发设置

uv sync --extra dev

测试

对于 CI 运行的相同检查（lint + format + Pyright + 测试），请使用存储库根目录中的统一运行器：./scripts/test.sh agent-engine-sdk-langgraph。

uv run pytest

类型检查

uv run pyright

重新生成APIDocs

make docs

Linting &格式化

# Check for lint errors
uv run ruff check src
# Auto-fix lint errors
uv run ruff check --fix src
# Format code
uv run ruff format src