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が実行中かどうかを確認:
サービスがアクティブかどうかのみを確認:
現在インストールされているAgentバージョンを確認:
Agentの実行ユーザーを確認:
デフォルトでは、Agentサービスはrootとして永続的に実行されるのではなく、obs-agentユーザーとして実行されます。rootは主にインストール、アップグレード、アンインストールなどのホスト管理アクションに使用されます。
Agentの開始、停止、再起動¶
Agentを開始:
Agentを停止:
Agentを再起動:
設定を変更した後、通常、新しい設定を有効にするためにサービスを再起動する必要があります:
Agentログの表示¶
最近のsystemdログを表示:
最新のログを継続的に表示:
Agentのメインログファイルを表示:
Agentの起動に失敗した場合は、最初に以下を確認することをお勧めします:
オフラインのローカルバグレポートを収集する¶
AgentがBeakに接続できない場合、モデル呼び出しが失敗するか、またはセッションツールが実行できない場合は、このコマンドをAgentホスト上で直接実行してください。
既定の深度は 0 です。ホスト、プロセス、設定、ログ、検出可能なすべてのセッション、ランタイムの証拠を収集し、詳細な LLM の証拠はエクスポートしません。レポートは既定で現在のディレクトリに保存します。--bug-report-output にはディレクトリではなく ZIP の完全なパスを指定してください。出力先のファイルは存在していてはならず、親ディレクトリは事前に存在する必要があります。
このコマンドは通常の 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 と表示され、マスクしていない内容を保持します。そのまま共有しないでください。
ローカル環境でレポートを開くには、以下のようにします:
ビューアーは基本レポート、過去の詳細 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のランタイム設定は、デフォルトで以下に書き込まれます:
変更前にバックアップすることをお勧めします:
設定を編集:
一般的な設定には以下が含まれます:
| 設定項目 | 説明 |
|---|---|
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 は初回移行時に直接再起動するため、実行中の会話が中断する場合があります。その後のアップグレードではアイドル保護を使います。
もし管理されたアップグレードに失敗した場合、インストール者は以前のバイナリ、設定、およびサービスを復元しようとします。同時に、失敗の診断情報も保持されます。同じターゲットに対する再試行は、既存のバックオフポリシーに従います。新しいターゲットは、以前のターゲットの遅延を引き継ぎません。
リリースソースの最新バージョンに更新:
たとえAgentが最新バージョンであるとしても、このコマンドによって、Browserなどのコンポーネントの再インストールが実行されます。バージョンが変わらない場合、背景タイマー検査ではこれらのコンポーネントを再インストールすることはありません。
特定のバージョンをインストール:
ロールバックには同じコマンドが使用されます。例えば、v0.1.9にロールバックする場合は、次のようにコマンドを入力します:
自動更新タイマーのステータスを確認:
更新に失敗した場合は、以下の確認を優先してください:
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のアンインストール¶
アンインストールスクリプトはデフォルトではアンインストール計画のみを表示し、コンテンツを削除しません:
正しいことを確認した後、--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-agentobs-agent.serviceobs-agent-update-check.serviceobs-agent-update-check.timer/etc/sudoers.d/obs-agentobs-agentユーザーおよびユーザーグループ
アンインストールは、skill-dep.shによってインストールまたは確認されたスキルランタイム依存関係(システムコマンド、言語ランタイム、Python/Nodeパッケージ、フォント、またはその他のシステムパッケージなど)を削除しません。これらの依存関係は、もともとホストに存在していた共有コンポーネント、または他のサービスによって再利用される可能性があり、Agentのアンインストール処理では削除できません。
一般的なチェック¶
ページにAgentがオフラインと表示される¶
以下の順序でチェックすることをお勧めします:
- ホストサービスが実行中かどうか:
systemctl status obs-agent - ホストネットワークがサービスアドレスにアクセスできるか;
beak.url、beak.api_key、beak.agent_id、/etc/obs-agent/config.tomlが正しいかどうか。- 最近のログに認証失敗、ネットワーク接続失敗、またはDNS解決失敗があるかどうか。
Agent設定の変更が有効にならない¶
サービスが再起動されたかどうかを確認:
次に、ログをチェックして、新しいプロセスが開始されたことを確認:
更新後、Agentバージョンが変更されない¶
最初に現在のバージョンを確認:
次に、更新ログを確認:
指定されたバージョンの更新の場合、コマンドのバージョン番号がリリースソースのバージョン番号と一致することを確認してください。