Invoking agents
===============

``aidb.agent_converse()``
は、プロンプトをエージェントに送信し、回答が生成されるか、制限に到達するまで、その推論ループを実行します-考え、オプションでツールを呼び出し、観察、繰り返します。

.. code:: sql

   SELECT * FROM aidb.agent_converse(
       agent_name      => db_helper,
       prompt          => How many rows are in the orders table?,
       conversation_id => NULL,  -- optional; continue an existing conversation by id. Default: NULL (starts a new conversation)
       read_only       => NULL,  -- optional; force read-only mode on/off. Default: NULL (auto: on for a read replica, off otherwise)
       output_type     => NULL,  -- optional; override the agents structured output schema for this call. Default: NULL (use the agents own configuration)
       debug           => NULL   -- optional; also emit every action as a NOTICE. Default: NULL (false)
   );

   __OUTPUT__
                 message               |           conversation_id           | error
   - ------------------------------------+--------------------------------------+-------
    The orders table has 4,213 rows.   | 8f14e45f-ceea-467e-9575-a3d1a2c1a123 |
   (1 row)

:ref:`Managing agents <Managing agents>` と同様に、これはエージェントロジックの障害不明なエージェント、ループ途中の推論の障害、超過した予算に対して発生することはありません。
``error``
は代わりに返された行に値が設定されるため、呼び出しのトランザクションおよび既にログに記録されているすべてその試行)はまだコミットします。

``output_type``
を渡して、このコールのみにエージェントの構成済み出力スキーマをオーバーライドします。ビルドの方法については、
:ref:`構造化された出力 <構造化された出力>` を参照してください。

会話
----

すべての\ ``agent_converse`` コールは、 ``conversation_id``
によって識別される会話に属します。最初の呼び出しでそれを省略すると、AIDBが生成します。エージェント自分自身の以前の履歴をコンテキストとして、後の呼び出しに同じIDを渡して会話を続行します。

.. code:: sql

   SELECT * FROM aidb.agent_converse(db_helper, And how many are still pending?,
       conversation_id => 8f14e45f-ceea-467e-9575-a3d1a2c1a123);

最初のプロンプトを送信する前にIDを用意しておきたい場合たとえば、UIセッションとともにログに記録する場合、
``aidb.start_agent_session()`` で前もって1つ作成します。

.. code:: sql

   SELECT * FROM aidb.start_agent_session(db_helper);
   SELECT * FROM aidb.agent_converse(db_helper, How many rows are in the orders table?,
       conversation_id => <the id start_agent_session returned>);

``start_agent_session``
はエージェント名のみを検証し、新しいIDを返します。会話は、それを使用する最初の\ ``agent_converse``
呼び出しまで、実際には存在しません。

会話の取得
^^^^^^^^^^

``aidb.get_conversation()``
は、会話のユーザープロンプトと最終的な回答を順番に結果ます。ツール呼び出しまたは中間推論ステップ、これらは「会話」ではなくアクティビティの詳細です。

.. code:: sql

   SELECT * FROM aidb.get_conversation(8f14e45f-ceea-467e-9575-a3d1a2c1a123);

   __OUTPUT__
    message_id | task_id | action_type |  role | sender_id |               contents
   - -----------+---------+--------------+-------+-----------+---------------------------------------
    ...        | ...     | user_prompt  | user  | postgres  | How many rows are in the orders table?
    ...        | ...     | answer       | agent | db_helper | The orders table has 4,213 rows.
   (2 rows)

``aidb.get_message()`` は、 ``message_id``
によって1つのメッセージのプレーンテキストコンテンツを取得します。どちらも\ ``aidb.conversation_log``
ビューによってサポートされており、直接照会することもできます。
``aidb.conversations``
は、会話ごとに1行メッセージ数、ステータス、最後のメッセージに集計します。完全な列リストについては、
:ref:`Agents reference <Agents reference>` を参照してください。

読み取り専用モード
------------------

``read_only => true``
を渡して、何も永続化せずにエージェントを実行します。会話履歴は書き込まれ、
``conversation_id`` は常に\ ``NULL``
として返されるため、読み取り専用の実行は後で再開できません。データベースがリードレプリカの場合、これは自動です明示的に渡す必要はありません。

読み取り専用の実行は、一度に2つのことを強制します。すべてのツール呼び出しはそのステートメントの\ ``SET LOCAL transaction_read_only = on``
の下で実行され、読み取り専用ではないツールは、そもそもエージェントが表示または呼び出すことができるものから除外されます。
MCPツールは、分類方法に関係なく、常に読み取り専用モードで除外されます。外部サーバー自身の読み取り/書き込み動作は、AIDBが検証できるものではありません。読み取り専用の実行中に :ref:`Delegation <Delegation>` が発生した場合、デリゲート自分自身のサブ呼び出しも強制的に読み取り専用になります。

デバッグモード
--------------

``aidb_internal.action_log``
に書き込まれる通常の履歴に加えて、代わりにではなく、すべてのアクションモデルの要求/応答、ツール呼び出しとその結果、推論ステップをPostgres
``NOTICE`` として出力するためにも\ ``debug => true``
を渡します。これは、エージェントが対話的に動作するのを監視したり、\ ``psql``
はデフォルトで\ ``NOTICE``
をターミナルに出力したり、そのパスを選択した理由をデバッグしたりするのに役立ちます。

.. code:: sql

   SELECT * FROM aidb.agent_converse(db_helper, How many rows are in the orders table?, debug => true);

   NOTICE:  [tool_call] run_sql_query({"query": "SELECT count(*) FROM orders"})
   NOTICE:  [tool_response] run_sql_query -> [{"count": 4213}]
   NOTICE:  [answer] The orders table has 4,213 rows.

各\ ``NOTICE``
には、そのアクションの要求/応答ペイロードプロンプト、ツール引数、および結果が含まれます。切り詰められますが、
**編集されません**
。これらの詳細には、独自のツールから返されたデータが含まれる場合があります、クライアント出力またはサーバーログを表示できる人に表示されないコンテキストでは、
``debug => true``
を避けてください。これは、runが行うデリゲートのサブコールにも適用されます。

予算と制限
----------

各\ ``agent_converse``
コールは4つのバジェットによって制限され、すべてオプショナルで
:ref:`promoteb.create_agent <promoteb.create_agent>` に設定されます。

.. csv-table::
  :header: Parameter,What it caps
  :widths: 10,30
  :align: left
  :class: longtable

  `input_token_budget`,Input tokens for the call.
  `output_token_budget`,Output tokens for the call.
  `max_iterations`,"Reasoning rounds — one model call plus any tools it calls in that round, not individual tool calls. A hard ceiling of 25 always applies, regardless of configuration, as a backstop against a runaway agent."
  `timeout`,Wall-clock seconds for the call. Defaults to 300 seconds if unset.

予算を超過した場合に何が起こるかは、\ ``budget_strategy``
によって異なります。

.. csv-table::
  :header: Strategy,Behavior
  :widths: 10,30
  :align: left
  :class: longtable

  `attempt_complete` (default),予算を最初に超過すると、3つの追加の推論ラウンドを付与、モデルの時間が残りわずかであることを伝えて、ラップアップします。次に、まだ終了していない場合はエラーで停止します。
  `error`,エラーですぐに停止します。
  `summarize`,すぐに停止し、モデルにこれまでに行ったことの簡単なステータスレポートを求め、それをエラーではなく回答として返します。
  `ignore`,1回限りの警告をPostgres `WARNING`としてログに記録し、制限なしで続行します。

コンテキストの長さ
------------------

長い会話は自動的に制限されます。タスクの組み立てられたプロンプトが内部で追跡されるサイズの推定値を超えると、AIDBはモデルに履歴の古い部分を要約するように求め、元のターンの代わりにその概要を続行します。これは、長時間実行される会話がモデルのコンテキストウィンドウを吹き飛ばさないようにするための基本的な自動バウンディングです。構成するものは何もありません。これが発生すると、アクティビティログに\ ``compaction``
エントリが表示されます。会話の背後にある完全なアクティビティ履歴については、
:ref:`デバッグモード <デバッグモード>` を参照するか、 ``aidb_internal.action_log``
を直接照会します。すべてのモデルの要求/応答、およびツール呼び出し/応答、
``aidb.get_conversation()`` が返すユーザー向けメッセージだけでなく。