Agent- engine-sdk-langgraph

インストール

pip install agent-engine-sdk-langgraph

または ucプロジェクトの場合は次のようになります。

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 ファサード（プラットフォーム ランタイムを超えるアプリバウンド）です。 ID は、 引数、バインドされたコンテキスト、または環境実行コンテキストからの呼び出しごとに解決されます。

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）は残ります。プラットフォームはテナンシーをスタンプし、永続的な実行を通じて応答を返します。 session_id は、stm ソースが要求された場合にのみ必要です。

from agent_engine_sdk_langgraph import Memory は agent_engine_sdk_memory.Memory と同じクラスを再エクスポートします。 Memory(api_key=...) / Memory(base_url=...) を自分で構築するのはHTTP/ Direct パスであり、アプリバウンドではありません。

これが壊れたとき

app.memoryこれはハードウェアです。 にはデュアルAPIと互換性シティーはありません。カスタマー エージェントは、この SDK を含むドライバーベースのファイルを選択するエージェントイメージを再構築した場合にのみ中断されます。プラットフォームマージのみを使用しても、古いエージェントイメージを再配置しても、そのイメージにすでに埋め込まれている SDK コードは変更されません。保存済みメモリ データの移行はありません。クライアントは戻り値の形状と呼び出し規則の変更のみを返します。

変更前と照合

• 型 / 真実/メタデータ/``Build_context`` CreateSemanticResultCreateEpisodicResultacknowledgedboolif result.acknowledged:if result:list[MemoryChunk]を返します:chunk.content chunk.similarity_score書込み (write)title では、 とともに型指定された結果（ 、 など）が返されます （ /decimals は必須ではありません）。 を優先します（summary tagstermdefinitionではありません -related_terms Private モデルは常に true です）。類似性検索では （ 、任意の ）が返されます。最上位の辞書キー（ 、 、 、 、 、 、...）で使用されていたフィールドは、chunk.metadata の下に存在します（例:ep.metadata.get("title") ep.get("title")）。build_context は を返します。戻り値をContextResponse context.formatted_contextstring としてではなく、 を使用します。

• 書込みヘルパーはキーワード専用（save_semantic(text=..., label=..., …) ）です。位置呼び出しではTypeError が発生します。

• ``visibility=================================================================================visibilityuser_id

• ``top_k``: search_semanticsearch_episodessearch_taxonomictop_k=5010discover_procedures10Memory.search()top_k=10build_contexttop_kmax_tokens500ソースごとの / / のデフォルトは （多くの場合 ）でした。 のデフォルトは引き続き です。 と統合してもデフォルトは に設定されています。パブリック には パラメータはありません。グローバル コンテキスト構築予算（取得コストではない）には を使用します。検索とランキングの後、サーバーは トークンのフォーマット予約を減算し、残りに収まるメモリ500 チャンク全体を必要に応じて選択します。 以下の正の値では、メモリの予算はありません。500 を超える値では、チャンクが収まらない場合でも空のコンテキストが生成されることがあります。古い制限が必要な場合は、検索ヘルパーに明示的なtop_k を渡します。

• ID: MemoryIdentityErrorNonesave_episodesession_idMemoryRequestContext解決できない必須フィールドでは、 が発生します（ソフト / サイレント スキップはなくなりました）。 には解決可能な が必要です（あいまいな呼び出しコンテキストは正常に行われます。それ以外の場合は、明示的に渡すか、 をバインドします）。空白値は設定されたものとしてカウントされません。

• アプリバウンド作成の忠実度: id""has_embeddingFalse作成結果 は.acknowledged になる可能性があり、 は通常 （ ではなくid で成功するようにします。操作ごとの詳細は、 メモリパッケージ機能マトリックス を参照してください。

• で検索を取得します。 get_semantic / get_taxonomic_term / list_episodes は引き続き、アプリバウンドで緩やかに型指定された命令を返します。 search* メソッドのみが list[MemoryChunk] を返します。

• 名前を変更します。以前のファケイド名が呼び出された場合は、ファケイド パブリックAPIを使用します（create_taxonomic save_taxonomiclist_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=[...] に渡します。実行時に、深層は構成されたバックエンドからそのディレクトリを一覧表示し、SKILL.md を 1 つの特権として含む直列の各子ディレクトリを検出します。検出は単一レベルであり、再帰的ではありません。

スキップ

---
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...

深層は実行時に特権を検証します。読み取れないまたは解析できないフロントマことと、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）と MongoDB イメージ（/app/<agent-subdirectory>/skills）の両方で機能します。スキルがエージェントソース ツリー内の他の場所に存在する場合は、AGENTIC_SKILLS_DIR をその相対ディレクトリに設定し、skills=[...] をそれに相対的にするようにします。実行時に、リージョンは検出された各特権からフロントマを読み取り、そのメタデータ（名前、説明、解決されたパス）をシステム プロンプトの特権システム ブロックとして LM に渡します。

段階的な説明

1をオンにすると、LM にはボディではなくスキップメタデータのみが表示されます。ユーザーがセキュリティについて質問した場合、LMread_file("<agent-dir>/skills/security-checklist/SKILL.md") は と決定し、フルコンテキストはToolMessage 2のコンテキストで として到達します。

これにより、基本的なプロンプトがリージョンに保たれ（メタデータは特権あたり約 50 トークン）、深い専門知識をオンデマンドで読み込むことができます。

バンドルされたツールファイルとサンドボックス

ToolsPd の書込み可能なファイルシステムとシェルハンドラーは引き続き WORKSPACE_DIR を使用し、デフォルトは /tmp/agent-workspace になります。それをスニペット スペースとして保持します。

バンドルされた特権は、代わりに読み取り専用のリソースとして扱われます。 ToolsPd は、デフォルトのスキー ルートを 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 をスキームディレクトリに設定せずに、そのルートの下のファイルをロードできます。書込み、編集、 シェル操作は引き続き書込み可能なワークスペースに残ります。スキーム ルートは、SDK インポート時ではなく、 ツール ポッドのスタートアップ時に解決される ため、通常の静的 SDK インポートが機能します。インポート順序の回避策は必要ありません。

サブエージェントの非継承

特権は、それを宣言するエージェントにのみ表示されます。エージェントがサブエージェント（ taskツールを使用）を生成する場合、それらのサブエージェントは親の操作を継承しません。ルールskills=[...] ファイルを必要とする各サブエージェント仕様に を渡します。

予約されたツール名

ディープエージェント ランタイムでは、組み込み用の9 ツール名が予約されます。これらの名前のいずれかでは、 を登録しないでください。組み込みの が暗黙的にシャドウされ、スキーやサンドボックスの動作が中断されます。@app.tool()

• read_file、write_file、edit_file、ls、glob、grep（ファイルシステム）

• execute （シェル）

• write_todos （計画）

• task (subagent dispatch)

競合する名前を選択すると、組み込みが暗黙的にシャドウされます。インポート時のエラーはありません。

サイズガイダンス

ターゲット <200 SR.md ボディあたり 行。より大きな特権：

• ロード時により多くのコンテキストを消費するようになりました（各 read_file はフルボディ ダンプです）

• 複雑な展開で LM の単一メッセージ コンテキスト制限に達するリスク

• スキームを複数のフォーカス ファイルに分裂ことをお勧めします

ヒント: EKILL.md 編集後にスレッドをリセットする

ランタイムは、スレッドの有効期間にわたってエージェント状態で skills_metadata をキャッシュします。 SKILL.mdファイルを編集する場合、既存のスレッドはリセットされるまで古いメタデータを使用し続けます。開発環境では、スレッドを削除するか、新しいセッションを開始します。本番環境では: スキーリングの変更は、新しいモデル/プロンプトのバージョンのロールアウトと組み合わせる必要があります。

完全最小の例

参照実装については、「 エージェント エンジンの例のリポジトリ 」で「 コード レビュー エージェント 」を参照してください。

• エージェント エンジンの例のリポジトリagents/code-reviewer-agent/src/code_reviewer_agent/main.py — ワイヤリング

• エージェント エンジンの例のリポジトリagents/code-reviewer-agent/skills/*/SKILL.md （例特権）

耐久性のあるネイティブ割り込み

耐久性のあるワークフローは、LingGraph のネイティブinterrupt() 呼び出しを再生し、新しく生成されたネイティブ ID を以前に記録された OA アクティビティの位置に変換します。完全に停止、リプレイ、Command(resume=...) フローとそのコード呼び出しサイトについては、「 耐久性のある LingGraph の割り込みと再開 」を参照してください。

要件

• Python >:=3.11

• uv

開発者設定

uv sync --extra dev

テスト

CI が実行する同じチェック（lint +形式+ pyrite + テスト）には、統合実行者: リポジトリ ルートからの ./scripts/test.sh agent-engine-sdk-langgraph を使用します。

uv run pytest

型チェック

uv run pyright

APIドキュメントの再生成

make docs

リンティングと形式

# 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