外部エージェントの統合
Python SDKまたはHTTP APIを使用してカスタムAIエージェントをEdison Watchと統合し、エージェントのアクティビティを追跡、制御、監視します。
Edison Watchは、外部AIエージェントを統合するためのAPIとSDKを提供し、ツール呼び出しの追跡、セキュリティポリシーの施行、およびエージェントアクティビティのリアルタイム監視を可能にします。
前提条件
エージェントを統合する前に:
- Edison Watchサーバーが実行中であり、アクセス可能であること
- ダッシュボードからのAPIキー(Settings → API Keys)
- Python 3.8以上(Python SDK用)またはHTTPクライアント(直接API用)
Settings → API Keysの下のEdison WatchダッシュボードからAPIキーを取得します。APIキーはエージェントを認証し、アクティビティをユーザーアカウントに関連付けます。
サーバーの場所: EDISON_WATCH_API_BASE環境変数をEdison WatchサーバーのURL(例: https://dashboard.edison.watch)に設定します。SDKはこの値を読み取ってサーバーに接続します。
クイックスタート (Python/LangGraph)
最も迅速に統合する方法は、@edison.track()デコレータを備えたedison-watch Python SDKを使用することです。
インストール
環境変数
以下の環境変数を設定します(またはEdisonコンストラクターに渡します):
必須: EDISON_WATCH_API_BASEをEdison WatchサーバーのURL(例: https://dashboard.edison.watch)に設定する必要があります。
最小限の統合
エージェントのツール呼び出しを追跡するために、わずか4行を追加します:
@edison.track()デコレータは自動的に以下を行います:
- 実行前にツール呼び出しのメタデータをEdison Watchに送信
- 呼び出しがセキュリティポリシーをトリガーする場合、承認を待機
- 実行後に期間と結果を記録
- ダッシュボードのタイムラインに表示
エージェントの登録(オプション)
より良い整理と追跡のために、Edison Watchに名前付きエージェントを登録することができます。これは、複数のエージェントタイプや役割を管理する場合に便利です。
エージェントの作成
レスポンス:
agent_idはagent:HEX(32文字の16進数)形式で自動的に生成されます。
エージェントの一覧表示
レスポンス:
エージェントの削除
レスポンス:
エージェントの登録はオプションです。エージェントを登録せずに追跡APIを直接使用できます。登録は主に管理的な整理と報告に役立ちます。
Edison SDKリファレンス
Edisonクラスは、エージェントアクティビティを追跡するためのPython SDKを提供します。
コンストラクター
環境変数:
EDISON_WATCH_API_BASE: サーバーURL(必須 - Edison Watchサーバーに設定)EDISON_WATCH_API_KEY: 認証用APIキー(必須)
コンストラクター引数として提供されない場合、これらの値は環境変数から読み取られます。
追跡デコレータ
@edison.track()デコレータは、実行を追跡するために関数をラップします:
パラメーター:
session_id: この呼び出しのセッションIDを上書きname: ツール名を上書き(デフォルトは関数名)
動作:
- 実行前に
/agent/beginを呼び出し(ゲーティング + 承認待機) - 関数を実行
- 実行後にステータス、期間、結果サマリーとともに
/agent/endを呼び出し - ブロックされ承認されない場合、
PermissionErrorを発生
LangChainツールのラップ
LangChainツールの場合、wrap_tools()を使用します:
またはbind_tools()を使用して1ステップでラップとバインドを行います:
セッション管理
セッションは、関連するツール呼び出しをグループ化します。デフォルトでは、各Edisonインスタンスは一意のセッションIDを作成しますが、セッションを共有できます:
呼び出しごとにセッションを上書きすることもできます:
直接HTTP API(非Python)
Pythonを使用していない場合、HTTPエンドポイントを介して直接統合できます。
ツール呼び出しの追跡開始
レスポンス:
ステータスコード:
200 OK: リクエスト処理済み(approvedフィールドを確認)400 Bad Request: 無効なリクエストボディ401 Unauthorized: APIキーがないか無効
重要: approvedがfalseの場合、ツール呼び出しはセキュリティポリシーによってブロックされました。ダッシュボードでの手動承認を待つか、エラーを適切に処理してください。
追跡完了
ツールを実行した後、/agent/endを呼び出します:
レスポンス:
ツール名の正規化
ツール名がまだbuiltin_またはagent_で始まっていない場合、自動的にagent_がプレフィックスとして付けられます:
web_search→agent_web_searchagent_my_tool→agent_my_tool(変更なし)builtin_system→builtin_system(変更なし)
例: 完全な統合
マルチエージェント設定
異なる役割や権限を持つ複数のエージェントを実行する場合、個別のagent_nameとagent_typeを持つEdisonインスタンスを作成します:
各エージェントのアクティビティはダッシュボードで個別に追跡され、ダッシュボードの権限設定を通じてエージェントタイプごとに異なる権限を設定できます。
権限設定
追跡されたツールは、権限システムでagent_プレフィックス付きで名前が付けられます。Edison Watchダッシュボードでこれらを設定します:
- ダッシュボードのServersに移動します
agentサーバーを見つけるか作成します(SDK経由で追跡されたツールはこのサーバーの下に表示されます)- 各ツールをクリックして権限を設定します
権限設定:
各ツールについて以下を設定できます:
- Enabled: ツールの実行が許可されているかどうか
- Write Operation: ツールがデータを変更できる(例: メール送信、ファイル作成)
- Read Private Data: ツールが機密内部データにアクセスする
- Read Untrusted Public Data: ツールが外部/信頼できないコンテンツを処理する
- ACL: アクセス制御レベル(PUBLIC, PRIVATE, SECRET, TOP_SECRET)
設定例:
agent_web_searchとして追跡されるweb_searchツールの場合:
- Enabled: ✓
- Write Operation: ✗
- Read Private Data: ✗
- Read Untrusted Public Data: ✓
- ACL: PUBLIC
agent_send_emailとして追跡されるsend_emailツールの場合:
- Enabled: ✓
- Write Operation: ✓
- Read Private Data: ✗
- Read Untrusted Public Data: ✗
- ACL: SECRET
セキュリティフラグ:
write_operation: ツールがデータを変更できる(例: メール送信、ファイル作成)read_private_data: ツールが機密内部データにアクセスするread_untrusted_public_data: ツールが外部/信頼できないコンテンツを処理する
Lethal Trifecta: ツール呼び出しが3つのフラグすべて(プライベートデータ + 信頼できないコンテンツ + 書き込み)を組み合わせる場合、Edison Watchは手動承認のために一時停止します。
ACLレベル:
PUBLIC: 機密でないデータPRIVATE: 機密または内部データSECRET: 高度な機密データ
施行: データは高いACLから低いACLに流れることはできません(例: SECRET → PUBLIC)。
詳細な設定ガイダンスについては、権限の設定を参照してください。
エラー処理
ブロックされたツール呼び出し
ツール呼び出しがセキュリティポリシーによってブロックされた場合:
ネットワークエラー
SDKはネットワークエラーを適切に処理し、ログに記録します。Edison Watchに到達できない場合:
- ツール実行は継続します(ベストエフォート追跡)
- エラーはログに記録されますが、例外は発生しません
- ヘルスチェックがバックグラウンドで実行され、接続性を検出します
タイムアウト処理
手動承認がタイムアウト(デフォルト: 30秒)を超えた場合:
timeout_sパラメーターは、PermissionErrorを発生させる前に承認を待つ時間を制御します。
ベストプラクティス
- 説明的なエージェント名を使用する:
hr_assistant,eng_copilot,finance_analyst - エージェントタイプを設定する: 管理しやすいように役割ごとにエージェントをグループ化します
- セッションを適切に共有する: 会話内の関連するツール呼び出しに同じ
session_idを使用します - 承認を適切に処理する: ブロックされた呼び出しは承認を待つか、適切に失敗する必要があります
- 事前に権限を設定する: エージェントをデプロイする前にダッシュボードでツール権限を設定します
- ダッシュボードを監視する: エージェントのアクティビティを確認し、必要に応じて権限を調整します
トラブルシューティング
401 Unauthorized
EDISON_WATCH_API_KEYが正しく設定されていることを確認してください- ダッシュボードでAPIキーがアクティブであることを確認してください
ツール呼び出しがブロックされる
- ダッシュボードでツール権限を確認してください(Servers → agent → Tools)
- ツール名が一致していることを確認してください(
agent_プレフィックス付き) - 必要に応じてダッシュボードでブロックされた呼び出しを承認してください
ツール呼び出しがダッシュボードに表示されない
- Edison Watchサーバーが実行されていることを確認してください
api_baseへのネットワーク接続を確認してください- サーバーログのエラーを確認してください
ヘルスチェックの失敗
- Edison Watchが
api_baseでアクセス可能であることを確認してください - ファイアウォール/ネットワーク設定を確認してください
- サーバーが実行されていることを確認してください:
curl https://dashboard.edison.watch/health
助けが必要ですか? エージェントアクティビティの監視についてはダッシュボードガイドを確認するか、[email protected]にメールでサポートを依頼してください。

