コンテンツにスキップ

Agentの日次運用マニュアル

この文書は、Agentサービスのインストールを完了したユーザーを対象としています。この文書では、Agentの状態を確認する方法、サービスの管理、設定の変更、ログの表示、セッションのバグレポートの収集、手動での更新、およびAgentのアンインストール方法について説明しています。

以下のコマンドはLinux/systemdインストール方法に適用されます。サービス管理、設定変更、およびアンインストールコマンドの実行には、通常、ホストでsudo権限が必要です。

Agentファイルの場所を確認

デフォルトインストール後、Agentに関連するファイルは以下の場所に配置されます:

種類 デフォルトの場所
Agentプログラム /usr/local/bin/obs-agent
アップデータープログラム /usr/local/bin/obs-agent-updater
設定ファイル /etc/obs-agent/config.toml、agent.envは、古いアップデートプロセスとの互換性のためにのみ使用されます。
作業ディレクトリ /var/lib/obs-agent/work
プロファイルキャッシュ /var/lib/obs-agent/profile-cache
ログディレクトリ /var/log/obs-agent
メインログファイル /var/log/obs-agent/log
systemdサービス obs-agent.service

SkillおよびMCPのアップデート

Agentは、基本設定をロードし、SkillsおよびMCPのリソースを一つずつ準備する前に接続します。依存関係の準備中はチャットが利用可能です。既存のセッション内で後からのリクエストは、新たに準備された機能を使用できます。

依存関係のある Skills は、事前の検査に合格する必要があります。ホストへのインストールでは、不足する依存関係や要件を満たすバージョンを追加します。コンテナではイメージに依存関係を含める必要があります。更新に失敗したリソースは使用できなくなり、旧版には戻りません。準備済みの他のリソースは使用できます。通常の同期は既定で約 10 分ごとです。失敗すると 30 秒後に再試行し、成功すると通常の間隔に戻ります。より短い間隔を設定している場合、再試行にもその間隔を使います。

Agent、Skill、またはMCPのページで、チェックの結果を確認してください。もしローカルリソースが準備完了しているにもかかわらず、そのステータスが変わっていない場合、報告の接続に問題がある可能性があります。その場合、後ほどの同期で再度報告されます。セッションを再インストールしたり、新たに作成する必要はありません。

Agentの状態確認

Agentが実行中かどうかを確認:

systemctl status obs-agent

サービスがアクティブかどうかのみを確認:

systemctl is-active obs-agent

現在インストールされているAgentバージョンを確認:

/usr/local/bin/obs-agent --version

Agentの実行ユーザーを確認:

systemctl show obs-agent -p User -p Group

デフォルトでは、Agentサービスはrootとして永続的に実行されるのではなく、obs-agentユーザーとして実行されます。rootは主にインストール、アップグレード、アンインストールなどのホスト管理アクションに使用されます。

Agentの開始、停止、再起動

Agentを開始:

sudo systemctl start obs-agent

Agentを停止:

sudo systemctl stop obs-agent

Agentを再起動:

sudo systemctl restart obs-agent

設定を変更した後、通常、新しい設定を有効にするためにサービスを再起動する必要があります:

sudo systemctl restart obs-agent

Agentログの表示

最近のsystemdログを表示:

journalctl -u obs-agent -n 100

最新のログを継続的に表示:

journalctl -u obs-agent -f

Agentのメインログファイルを表示:

tail -n 100 /var/log/obs-agent/log

Agentの起動に失敗した場合は、最初に以下を確認することをお勧めします:

systemctl status obs-agent
journalctl -u obs-agent -n 100

オフラインのローカルバグレポートを収集する

AgentがBeakに接続できない場合、モデル呼び出しが失敗するか、またはセッションツールが実行できない場合は、このコマンドをAgentホスト上で直接実行してください。

obs-agent --bug-report

既定の深度は 0 です。ホスト、プロセス、設定、ログ、検出可能なすべてのセッション、ランタイムの証拠を収集し、詳細な LLM の証拠はエクスポートしません。レポートは既定で現在のディレクトリに保存します。--bug-report-output にはディレクトリではなく ZIP の完全なパスを指定してください。出力先のファイルは存在していてはならず、親ディレクトリは事前に存在する必要があります。

obs-agent --bug-report --bug-report-output /var/tmp/report.zip --depth 2

このコマンドは通常の Agent ランタイムの起動、WebSocket 接続、モデル呼び出し、承認要求、ファイルのアップロードを行いません。標準出力は JSON の 1 行のみです。status は completed または partial で、絶対パス、サイズ、SHA-256、安定したエラーコードが含まれます。どちらの状態も ZIP が安全性検証に合格したことを示し、終了コードは 0 です。

別の設定ファイルを使う場合は --config /etc/obs-agent/config.toml を追加し、Agent のキャッシュとローカル診断エンドポイントを読めるアカウントで実行します。深度は 0..3 です。depth 1 は呼び出し構造、depth 2 は記録済みのプロバイダー要求・応答・ツールの証拠を元の内容で追加します。稼働中の Agent は事前に [diagnostics] の chat_depth = 2 以上を使用している必要があり、それ以前の呼び出しは復元できません。depth 3 はローカル専用で、UNREDACTED と表示され、マスクしていない内容を保持します。そのまま共有しないでください。

ローカル環境でレポートを開くには、以下のようにします:

obscli bug-report view /var/tmp/report.zip

ビューアーは基本レポート、過去の詳細 LLM レポート、統合レポートに対応し、アーカイブをアップロードしません。

稼働中の Agent は、既定で Profile キャッシュ内の diagnostics/runtime.sock に権限 0600 のローカル診断エンドポイントを公開します。heap と goroutine のプロファイル、30 秒の CPU プロファイル、5 秒のランタイムトレース、コマンドライン、メトリクス、実行タイムラインを収集します。Unix ソケットのみを使い、TCP では待ち受けません。無効にするには config.toml の [runtime] で local_diagnostics_enabled = false を設定します。

容器内で、以下の内容を含むレポートを生成し、コピーします:

docker exec obs-agent obs-agent --bug-report --bug-report-output /app/obs-agent-support.zip
docker cp obs-agent:/app/obs-agent-support.zip ./obs-agent-support.zip

ZIP サイズの固定上限はありません。収集時には出力ファイルシステムの空き容量を動的に確保します。コピー前に size_bytes と sha256 を確認してください。どの深度のレポートにも機密情報が含まれる可能性があります。マスクするのは config.toml(旧インストールでは agent.env)内の機密値の代入のみです。他の設定、セッション内容、ログ、記録された LLM の証拠は元の内容を保持します。深度 3 は最初の呼び出しからの完全な生の記録も含みます。ファイルのモードは 0600 です。管理されたサポート経路でのみ転送し、使用後は削除してください。

セッションのバグレポートを収集する

Agentが予期せぬ状態で応答しない場合、またはツールが停止したり、接続が不安定な場合は、影響を受けたセッション内のAgentに診断レポートの収集とアップロードを依頼することができます(設定ファイル内の機密なアサインのみをマスクします)。Agentは、一時的なダウンロードリンクを指定されたサポート用のメールアドレスに直接送信することができるため、レポートを手動でダウンロードして転送する必要はありません。

手順、権限の詳細、メール送信、失敗時の対応については、セッションから Agent の不具合報告を収集・送信するを参照してください。

オンライン収集は現在のセッションに限定され、chat_depth=0..2のみを受け付け、デフォルトは0です。セッションの認証を適用し、レポートをアップロードします。chat_depth=3は拒否されます。

Agent設定の変更

Agentのランタイム設定は、デフォルトで以下に書き込まれます:

/etc/obs-agent/config.toml

変更前にバックアップすることをお勧めします:

sudo cp -p /etc/obs-agent/config.toml /etc/obs-agent/config.toml.bak

設定を編集:

sudo vi /etc/obs-agent/config.toml

一般的な設定には以下が含まれます:

設定項目 説明
beak.url サービスアドレスAgentは、以下に接続されます。
beak.api_key Agent アクセス認証情報
beak.agent_id 現在のAgent ID
llm.base_url LLM サービスアドレス
llm.api_key LLM 呼び出し認証情報
runtime.working_dir Agent ツール実行用の作業ディレクトリ
profile.cache_dir Agentのプロフィール、Skill、およびスキーマキャッシュディレクトリ
update.base_url Agentのリリース・ダウンロードアドレス
update.auto_enabled ローカルな自動アップグレードスイッチ。独立したアップデートチェッカーによって確認されます。

Agentが企業プロキシを通じてBeak、LLM、またはリリースサービスにアクセスする必要がある場合は、obs-agentフォワードプロキシの構成に説明されているとおりプロキシ変数とエンタープライズCAを構成してください。

llm.modelはオプションであり、デフォルトではautoのルーティングが使用されます。従来のLLM_MODEL=defaultは依然としてautoとしてロードされます。固定モデルが必要な場合にのみ、実際のモデルIDを設定してください。詳細については、Agentの構成:グループ、優先順位、デフォルト値、空値、マイグレーション、およびパーミッション]を参照してください。

変更完了後、サービスを再起動:

sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent

設定エラーによってサービスが起動に失敗した場合は、バックアップから復元できます:

sudo cp -p /etc/obs-agent/config.toml.bak /etc/obs-agent/config.toml
sudo obs-agent --config-tool agent-export --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent
注意

config.tomlファイルおよびその生成された互換性ファイルagent.envには、APIキー、トークン、アクセスアドレスなどの機密情報が含まれている可能性があります。完全な設定ファイルを公開のチャット、チケット、コードリポジトリ、またはスクリーンショットに送ることはしないでください。

個人用 Owl キーモード

Agent は既定でインストール時の Owl 認証情報を使用します。個人用 Owl キーモードでは、通常のセッションは作成者の個人用 Open API キーを使います。スケジュールタスクとユーザー Webhook は設定作成者のキーを使います。追加の質問で送信者のキーに切り替わることはありません。IM とそこから派生した委任はインストール時の認証情報を維持します。個人キーが未登録、無効、削除済みの場合、実行を拒否し、インストール時の認証情報にはフォールバックしません。

まず、マッチングするBeak、Backend/Connector、Owl、そしてAgentのコンポーネントをアップグレードします。作成者の個人キーが同期されていることを確認してください。Owlはruntime-profile/v1をサポートする必要があり、インストール時にはその機能を確認します。マッチングするフロントエンドにインストール設定を保存し、その後Agentを再インストールしてAGENT_OWL_USER_TOKEN_ENABLED=trueを適用します。デフォルト値はfalseです。通常のアップグレードでは、ローカルモードが維持されます。設定を保存したり、再起動しても、新しいインストールモードには変わりません。

各アイデンティティは、隔離されたOwl Profileおよびクエリ結果のディレクトリを使用します。デフォルトのディレクトリからの歴史的な結果はコピーされません。キーのローリングまたは無効化により、古いキーを使用している実行中の作業やキュー内の作業がキャンセルされます。必要に応じて新しいリクエストを送信してください。アクセス拒否の場合は、ターゲットワークスペース内の作成者の役割とクエリ権限を確認してください。他の認証情報を使用して拒否を回避しないでください。Profileの隔離機能は、同じシステムユーザー下での任意のスクリプトにオペレーティングシステムのサンドボックスを提供しません。

デプロイ前に Backend outbox のデータベース変更をレビューしてください。このモードを無効にした状態で Beak をデプロイし、続いて Backend/Connector、新機能に対応する Owl と完全な Agent 配布パッケージ、フロントエンドをデプロイします。設定を保存して再インストールすると有効になります。ロールバック前にはモードを無効にして再インストールしてください。古い認証情報で新しい状態が上書きされないよう、認証情報リビジョンのウォーターマークと既存の暗号化設定を保持します。

Agentの手動更新またはロールバック

v0.16.0から、新しいメンテナンスプロトコルをサポートするホストは、古いプロセスを停止する前に既存の作業を完了し、完全な配布パッケージをインストールし、起動時および実行時のバージョンを確認します。セッションでは、メンテナンスの結果、成功、失敗、回復の結果が表示されます。メンテナンス中に送信されたメッセージはBeakに保持され、再接続後に自動的に復旧します。使用可能な依存関係は引き続きインストールされ、不足している依存関係は追加されます。ダウンロードや検証の失敗は、既存の回復フローを通じて以前の配布パッケージを復元します。

内部バージョンの収束ループ、obscli agent pin-version、およびPOST /api/v1/agents/{id}/version:pinは削除されました。AGENT_UPDATE_ENABLEDおよびAGENT_UPDATE_CHECK_INTERVAL_SECONDSはもはや適用されません。ローカルのsystemdタイマーによって自動的なアップグレードが実行され、これはupdate.auto_enabledによって制御されます。既存のアップデート機能は引き続きサポートされます。--target-versionは、ある操作の対象を選択し、永続的なバージョンピンを生成しません。

Agentはローカルアップデータを介してバージョンを切り替えることができます。

古いアップデーターは、手動で置き換えずに既存のアップグレードコマンドを使えます。アイドル保護に対応する Agents は実行中のタスクの完了を待ちます。アップグレード中に Beak が受け付けた新しい会話は、再接続後に自動で再試行されます。アイドルプロトコルを持たない古い Agents は初回移行時に直接再起動するため、実行中の会話が中断する場合があります。その後のアップグレードではアイドル保護を使います。

もし管理されたアップグレードに失敗した場合、インストール者は以前のバイナリ、設定、およびサービスを復元しようとします。同時に、失敗の診断情報も保持されます。同じターゲットに対する再試行は、既存のバックオフポリシーに従います。新しいターゲットは、以前のターゲットの遅延を引き継ぎません。

リリースソースの最新バージョンに更新:

sudo /usr/local/bin/obs-agent-updater

たとえAgentが最新バージョンであるとしても、このコマンドによって、Browserなどのコンポーネントの再インストールが実行されます。バージョンが変わらない場合、背景タイマー検査ではこれらのコンポーネントを再インストールすることはありません。

特定のバージョンをインストール:

sudo /usr/local/bin/obs-agent-updater --target-version v0.2.0

ロールバックには同じコマンドが使用されます。例えば、v0.1.9にロールバックする場合は、次のようにコマンドを入力します:

sudo /usr/local/bin/obs-agent-updater --target-version v0.1.9

自動更新タイマーのステータスを確認:

systemctl status obs-agent-update-check.timer
systemctl list-timers obs-agent-update-check.timer

更新に失敗した場合は、以下の確認を優先してください:

  • update.base_urlを/etc/obs-agent/config.tomlで確認し、生成された互換性ファイルが同期されていることを確認してください。
  • install.sh、対象バージョンのインストールパッケージ、および検証ファイルがリリースアドレスに存在するかどうか;
  • journalctl -u obs-agent-update-check.service -n 100でダウンロード、検証、またはスケジューリングエラーがあるかどうか;
  • journalctl -u obs-agent -n 100で起動またはエラーが再起動されるかどうか。

/etc/obs-agent/config.toml の [proxy] にプロキシを設定し、古いアップデーター用に agent.env をエクスポートします。自動アップデートでのプロキシの継続使用を参照してください。

Agentのアンインストール

アンインストールスクリプトはデフォルトではアンインストール計画のみを表示し、コンテンツを削除しません:

curl -fsSL https://static.guance.com/obs-agent/uninstall.sh | sudo bash

正しいことを確認した後、--yesで完全なアンインストールを実行:

curl -fsSL https://static.guance.com/obs-agent/uninstall.sh | sudo bash -s -- --yes

アンインストールは以下の固定オブジェクトを削除します:

  • /usr/local/bin/obs-agent
  • /usr/local/bin/obs-agent-updater
  • /usr/local/bin/obs-agent-update-check
  • /etc/obs-agent
  • /var/lib/obs-agent
  • /var/log/obs-agent
  • obs-agent.service
  • obs-agent-update-check.service
  • obs-agent-update-check.timer
  • /etc/sudoers.d/obs-agent
  • obs-agentユーザーおよびユーザーグループ

アンインストールは、skill-dep.shによってインストールまたは確認されたスキルランタイム依存関係(システムコマンド、言語ランタイム、Python/Nodeパッケージ、フォント、またはその他のシステムパッケージなど)を削除しません。これらの依存関係は、もともとホストに存在していた共有コンポーネント、または他のサービスによって再利用される可能性があり、Agentのアンインストール処理では削除できません。

一般的なチェック

ページにAgentがオフラインと表示される

以下の順序でチェックすることをお勧めします:

  1. ホストサービスが実行中かどうか:systemctl status obs-agent
  2. ホストネットワークがサービスアドレスにアクセスできるか;
  3. beak.url、beak.api_key、beak.agent_id、/etc/obs-agent/config.tomlが正しいかどうか。
  4. 最近のログに認証失敗、ネットワーク接続失敗、またはDNS解決失敗があるかどうか。

Agent設定の変更が有効にならない

サービスが再起動されたかどうかを確認:

sudo systemctl restart obs-agent

次に、ログをチェックして、新しいプロセスが開始されたことを確認:

journalctl -u obs-agent -n 50

更新後、Agentバージョンが変更されない

最初に現在のバージョンを確認:

/usr/local/bin/obs-agent --version

次に、更新ログを確認:

journalctl -u obs-agent-update-check.service -n 100
journalctl -u obs-agent -n 100

指定されたバージョンの更新の場合、コマンドのバージョン番号がリリースソースのバージョン番号と一致することを確認してください。

フィードバック

このページは役に立ちましたか?