ディープエージェントの構築

依存関係の更新

ディープエージェントを作成するには、deepagentsパッケージをプロジェクトの pyproject.tomlファイルに追加します。

dependencies = [
    "deepagents==0.5.3",
    ... # other dependencies
]

deepagentsパッケージは、 agent-engine-sdk-langgraphパッケージのオプションの依存関係です。 SDK は、アプリがApp.deep_agent() 関数を呼び出すときにのみ deepagentsパッケージをインポートするため、プロジェクトで明示的に宣言する必要があります。

機能フラグを更新

次のフラグを agent.yamlファイルに追加して、agent.yaml でディープエージェント機能を有効にします。

features:
  deep_agent: true
  ... # other features

このフラグは、ディープ エージェントが依存する組み込みのファイルシステムとシェルハンドラーを登録するようにツール サンドボックスに指示します。

パラメーター

App.deep_agent() メソッドは次のパラメーターを受け入れます:

特権エージェントの作成

特権を呼び出すディープエージェントを作成するには、特権ディレクトリのパスのリストを App.deep_agent() メソッドの skills パラメーターに渡します。

次の例では、 @app.entrypoint宣言された関数を変更して、単一のツールと スキームディレクトリ を持つディープエージェントを作成します。

from agent_engine_sdk_langgraph import App
app = App()
@app.entrypoint
def build_agent():
    return app.deep_agent(
        llm=my_llm,
        tools=[my_tool],
        subagents=[],
        skills=["skills/security-review"],
    )

セキュリティ検証

初期化時に、App.deep_agent() メソッドは次のチェックを実行し、いずれかが失敗した場合はエラーを発生させます。

• SubAgentクラスで string モデル参照を確認します。各 SubAgent.model 属性は、string ではなく LMインスタンスである必要があります。 string モデル名は SecureWrappedLLMクラスをバイパスし、プラットフォームはエージェントを拒否します。このメソッドは最大 10 レベルのネストをチェックします。

• 手動指定された backend パラメータを確認します。 プラットフォームはサンドボックスを所有し、AgentEngineToolSandboxBackendクラスをバックエンドとして強制します。カスタムバックエンドを指定すると、プラットフォームのサンドボックスがバイパスされ、プラットフォームはバックエンド を拒否します。

これらのチェックに加えて、App.deep_agent() メソッドは、deepagents ライブラリがグラフをコンパイルする前に、llm パラメータと SecureWrappedLLMクラスのすべての SubAgent.model 属性に渡される LMインスタンスを自動的にラップします。

能力ディレクトリ構造

特権は次のディレクトリ構造内にあります。ディレクトリ名はフロントマッパーの nameフィールドと一致します。

<workspace-directory>/
└── skills/
    └── <skill-name>/
        └── SKILL.md

skills パラメータに渡されるルール パスは、エージェントの ワークスペースディレクトリに相対的です。これは、agent.yamlファイルを含むディレクトリです。

SR.md 形式

有効な SKILL.mdファイルはYAML フロントマで始まる必要があります。次の例は、有効な SKILL.mdファイルのテンプレートです。

---
name: <skill-name>
description: <one-sentence description for LLM discovery>
---
# Skill Title
Detailed instructions or reference material for the agent...

YAML フロントマに次のフィールドを含める必要があります。

エージェントへの特権の渡し

次の例では、ツールディレクトリパスのリストを App.deep_agent() メソッドに渡します。

agent = app.deep_agent(
    llm=my_llm,
    tools=[],
    skills=["skills/security-review", "skills/style-guide"],
)

サポートされている操作

AgentEngineToolSandboxBackendクラス操作は実行時にエージェントによって自動的に呼び出され、エージェント作成者によって直接呼び出されることはありません。 AgentEngineToolSandboxBackendクラスは次の操作をサポートしており、それぞれが対応する filesystem_* または shell_execute ツールとして LM に公開されます。

Error Handling

バックエンドはすべてのエラーをエージェントグラフに表示する前にクラス化するため、エージェントは操作を再試行するかどうかを決定できます 。次の表は、利用可能なエラー分類とその原因を示しています。

プラットフォームは、エージェントに表示される前に、すべてのエラーメッセージからすべての内部ワークスペース パスを削除します。

Filesystem Sandbox

ディープ エージェントはサンドボックス化されたファイルシステム内で動作します。サンドボックスには次のレイヤーが含まれています。

• 書き込み可能なワークスペース（WORKSPACE_DIR ）:/tmp/agent-workspace デフォルトは ディレクトリです。エージェントサンドボックス セッション中、サンドボックスはエージェントの パスへのアクセスを制限し、同時セッションが分離されるようにします。生成されたファイルには、相対パスまたはWORKSPACE_DIR/.sessions/<session-hash>/ /tmpディレクトリ配下パスを使用します。

• 読み取り専用リソースルート（READONLY_RESOURCE_ROOTS ）:AGENTIC_AGENT_WORKDIR 環境変数とskills/ ディレクトリから入力されます。このレイヤーでは、エージェントはセッションごとのワークスペース内と外のSKILL.md ファイルを読み取ることができるため、オンデマンドでスキップ コンテンツを読み込むことができます。

# .env
AGENTIC_AGENT_WORKDIR=/app
# Do NOT add: WORKSPACE_DIR=/app