Agentの設定を行う¶
ホストのインストールには/etc/obs-agent/config.tomlを使用します。インストールプログラムがこのファイルを作成します。編集する前にこのファイルをバックアップし、その後で内容を確認し、サービスを再起動してください。このファイルには認証情報が含まれています。ファイルの所有権はroot:obs-agent、権限は0640です。完全なファイルを公開するようなことはしないでください。
設定の編集¶
config_version = 1
[beak]
url = "https://beak.example.com"
agent_id = "replace-with-agent-id"
api_key = "replace-with-agent-api-key"
[llm]
# model = "auto"
# request_timeout = "5m"
# max_tokens = 0
[runtime]
working_dir = "/var/lib/obs-agent/work"
# http_allowed_domains = ["example.com", "api.example.com"]
[profile]
cache_dir = "/var/lib/obs-agent/profile-cache"
[logging]
level = "info"
# format = "text"
[update]
base_url = "https://releases.example.com/obs-agent"
# auto_enabled = true
[tools.browser]
# enabled = true
[tools.web_search]
# enabled = true
インストーラーは必須の設定と明示された設定を書き込みます。未設定のフィールドには既知の環境変数または組み込みの既定値を使います。サンプルのフィールドを明示的に設定するにはコメントを解除してください。update.socket_path が未設定の場合、Agent は update.state_path と同じディレクトリの update.sock を使います。仮のパスは不要です。
実行時間とツールの使用時間の制限¶
| 設定 | デフォルト | 範囲 |
|---|---|---|
runtime.max_run_duration |
"2h" |
各実行に対するソフト時間制限です。セッション自体の存続時間ではありません。"0s" で無効にします。 |
runtime.subagent.max_runtime |
"8h" |
サブエージェントの監督予算も、親タスクの残り時間によって制限されます。 |
runtime.wait_for_max_duration |
"8h" |
1つのwait_forリクエストです。また、親タスクの残り時間にも制限があります。 |
8時間制限は、2時間の実行制限を延長するものではありません。サブエージェントは親エージェントのキャンセル処理を引き継ぎます。親エージェントの残り時間を超えるwait_forリクエストは拒否されます。より長いタスクを実行するには、runtime.max_run_durationを明示的に設定し、適切なサブエージェントと待機制限を維持する必要があります。
柔軟な予算が終了すると、Agentはストリーミングやコンパクションのリクエスト、または他のツールの実行を待ちます。有効な最終的な回答を保持します。さらに多くの作業が必要な場合は、新しいツールを開始せず、最大1つの要約をリクエストします。失敗した要約はチェックポイントとして返されます。実際の所要時間は予算を超えることがあります。もしコンテキストが要約を保持できない場合、または敏感な設定情報が構造化された出力としてのみ表示される場合は、Agentは直接チェックポイントを返します。
時間制限が有効な場合、各モデルリクエスト、再試行を含むすべてのリクエストは、合計時間、経過時間、残りの時間を示す一時的なuserメッセージで終了します。このメッセージはセッション履歴に保存されません。このメッセージには、ツールの数、モデルの呼び出し回数、トークンの使用状況は含まれません。呼び出し回数やトークンの合計数は内部診断用の情報として扱われ、もはや実行を停止しません。時間制限が無効な場合は、予算に関するメッセージは表示されません。
接続されたobscliのセッションでは、以下のものを使用します:
| 命令 | 行動 |
|---|---|
/max-run-duration |
保存した設定を表示し、Agentアプリケーションの状態、および経過時間/残りの時間を表示します。 |
/max-run-duration 10m |
このセッションでは、各実行の制限時間を10分間に設定します。 |
/max-run-duration +5m |
5分間の追加時間;継承されたデフォルト設定では、一貫したデフォルト値を持つAgentオンラインカードが必要です。 |
/max-run-duration 0 |
セッションの時間制限を無効にする |
/max-run-duration reset |
各Agentのデフォルト状態を復元する |
設定は永続化され、現在と以降の実行に適用されます。各実行でタイマーが新しく開始します。要約段階に入った実行は調査を再開しません。実行中のサブタスクは親の制限変更に従いますが、独自の制限がより短い場合はそれを維持します。API は GET/PUT /api/v1/sessions/:id/max-run-duration です。PUT 本文には {"duration":"+5m"} などを指定できます。変更できるのは書き込み権限を持つセッション参加者だけです。applied は接続中の Agent が応答して適用を確認したことを意味します。pending、offline、unsupported は有効になったことを意味しません。
承認待ち時間も実行時間に算入されます。期限に達すると待機が終了し、未実行のツールは実行されません。期限後の承認で停止した操作を再開することはできません。実行制限を変更すると待機期限が再計算されます。Browser 操作の承認は、独立して 30 分後に失効します。実行時間を延長しても承認の有効期間は延長されません。手動キャンセル、モデルリクエストのタイムアウト、ツールのタイムアウトは互いに独立しています。
例えば、既存の[runtime]セクションにmax_run_duration = "4h"を設定し、4時間を指定します。その後、以下のようにして検証し、再起動します。ホストやコンテナのデフォルト値は2時間です。コンテナはAGENT_MAX_RUN_DURATION=4hを設定できます。
真偽値には true または false、数値には引用符なしの数値、リストには配列、期間には "5m" などの単位付き文字列を使います。旧フィールド max_llm_calls と max_run_tokens を含む未知のフィールドやテーブルは無視されます。既知のフィールドには有効な型と値が必要です。不正な構文や未対応の設定バージョンは拒否されます。旧環境変数の制限と AGENT_MAX_TOOL_CALL_ITERATIONS エイリアスは読み取られません。
設定の優先順位¶
ホストへのインストールでは、優先順位は TOML、既知の環境変数、組み込みの既定値の順です。フィールドが存在すれば、値が ""、false、0 でも環境変数より優先されます。不正な値はエラーとなり、他の値にフォールバックしません。
デフォルトのファイルは/etc/obs-agent/config.tomlです。もしこのファイルがない場合、Agentが使用され、agent.envというフォーマットが代わりに使用されます。これらのファイルは統合されません。アップグレード時には、古いファイルは移行され、バックアップも保持されます。既存のTOMLの設定やユーザーのコメントはそのまま保持されます。
TOML対応のAgentにおいて、Linuxのインストーラーは--config /etc/obs-agent/config.tomlを明示的に使用するサービスを作成します。アップグレード前のチェックでは、同じファイルが使用されます。主要なサービスは、互換性のあるagent.envをロードしません。古いアップデートツールでは、依然としてこの互換性が利用されています。
フィールドを削除するか、コメントを付けることで、環境変数やデフォルト値がその値を提供できるようになります。config_version = 1は設定スキーマのバージョンであり、Agentのリリースバージョンではありません。サポートされていないバージョンは受け入れられません。
Agentの設定ツールでは、変更可能な設定のみを変更し、コメントや空白行、その他のフィールドは保持されます。同時に複数の変更を加えると、古くなった変更が無効になってしまいます。再試行する前に、ファイルを再度確認してください。
検証、エクスポート、および再起動¶
sudo cp -p /etc/obs-agent/config.toml /etc/obs-agent/config.toml.bak
sudo vi /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
sudo systemctl status obs-agent
検証に失敗した場合は、再起動しないでください。エクスポートコマンドは、古いアップデーターが読み取れるファイルに、既知の設定のみを書き込みます。生成されたagent.envの設定ファイルを編集しないでください。Agentの設定ツールがこのファイルを同期します。
別のファイルを選択するには、obs-agent --config /path/to/config.tomlを使用してください。このオプションを古い--env-fileオプションと組み合わせてはいけません。
もしサービスが起動できない場合は、バックアップを復元し、互換性ファイルを再生成してください。
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
従来の設定からアップグレード¶
TOML 対応版への最初のホストアップグレードでは、切り替え前に agent.env を変換して検証します。手動の変換やフィールドの対応付けは不要です。既定値と同じ値を含め、有効な既知の設定を維持します。旧形式の空の値は、従来どおり未設定として扱います。
未知の変数はTOMLに入力されません。インストールプログラムは、変数の名前のみを報告し、元のファイルはバックアップに保存されます。これらの変数の元の目的を確認してください。一般的な環境変数グループは存在しません。
古いアップデートプロセスでは、既存のコマンドをそのまま使用でき、新しい引数や事前の自己アップデートは不要です。アイドルプロテクションは引き続き有効です。マイグレーションや起動に失敗した場合でも、アップグレードにより古いプログラム、設定、サービスが復元されます。アイドルプロトコルがない場合、確定された歴史的な実行環境では、最初の移行中に作業が中断される可能性があります。アップグレードされた実行環境では、アイドルプロテクションが利用されます。
コンテナAgentの設定を行います。¶
コンテナは環境変数のみを使用します。config.toml を読み取りも生成もせず、Agent のファイル引数 --config と --env-file もサポートしません。Docker、Compose、Kubernetes のインストールページにある環境設定を使ってください。
Docker の --env-file 引数は引き続き使用できます。Docker が変数をコンテナに注入し、Agent がそのファイルを読むことはありません。コンテナのインストールガイドを参照してください。
アップグレードの互換性¶
LocalProviderは、agent_max_llm_callsやagent_max_tool_call_iterationsをもはや読み取ったり送信したりしません。
公開されたインストールプロトコルでは、依然として旧バージョンのAgentsやその他のインストーラー用の古い制限フィールドを受け入れて転送することができます。新しいAgentsでは、これらのフィールドは読み取られず、また強制されません。
BREAKING CHANGE: 新しい Agents では累積呼び出し数とトークン数の制限は適用されません。デプロイ前に、コスト管理がこれらのフィールドに依存していないことを確認してください。まず Beak をアップグレードし、その後に既存のインストールまたは自動アップグレード手順で Agents を更新します。古い Agents は接続とチャットが可能ですが、セッションの制限は適用しません。任意の機能 session_run_duration=v1 が対応状況を示します。Agent をロールバックすると旧制限が復活し、セッション単位の上書き設定は無視されます。後のアップグレードに備えてセッション設定を保持してください。Beak のロールバック時に NULL 許容の run_duration 列を削除しないでください。インストーラーとアップデーターの呼び出し契約は変更されません。