.. _auto_agent_turn:

*AGENT CONVERSATIONAL TURN*
===========================

Runs ONE bounded conversational turn of a named AI agent (ai.agents.json) through AgentOrchestrator::runConversationalTurn -- loads or starts a conversation blob, appends the user's message (or, when a pending_ask is outstanding, injects it as that ask's answer), runs the tool loop until an answer or an ask_* tool call ends the round, persists the blob, and returns this call's transcript delta. A thin server transport for browser-facing conversational agents; not an LLM-callable tool.

When to use
-----------

Tagged: ``agent``, ``agent_turn``, ``conversation``, ``conversational_turn``, ``assembler``, ``fora``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - Agent Name
     - agent_name
     - text
     - —
     - ✓
     - Key into ai.agents.json identifying the agent to run this turn against (e.g. fora_ai_agent).
   * - Message
     - message
     - textarea
     - —
     - ✓
     - The user's text for this turn. When the conversation has an outstanding pending_ask, this value is treated as the answer to that ask rather than a new user message.
   * - Conversation Id
     - conversation_id
     - text
     - —
     - 
     - Blob id of an existing conversation to resume. Leave blank to start a new conversation.
   * - Project Id
     - project_id
     - text
     - —
     - ✓
     - Project scope for this turn's tool calls.
   * - Context
     - context
     - textarea
     - —
     - 
     - Optional seed context object, as a JSON string; json-decoded before being passed to the orchestrator. Falls back to an empty context if not valid JSON.
   * - Provider
     - provider
     - text
     - —
     - 
     - Optional LLM provider override (e.g. claude, openai). Leave blank to use the agent's default.
   * - Model
     - model
     - text
     - —
     - 
     - Optional LLM model override. Leave blank to use the provider's default model.
   * - View State
     - view_state
     - json
     - —
     - 
     - Optional snapshot of what the user currently sees in the UI (current project, visible panes/tabs, open tabs), as an object or a JSON-encoded string; normalized before use. Folded into this turn's <current_context> as a compact screen_state line so the agent can ground 'what am I looking at' answers. Absent/empty leaves turn behavior unchanged.

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - Conversation Id
     - conversation_id
     - string
     - Blob id of the conversation (newly created, or echoed back when resuming).
   * - Status
     - status
     - string
     - 'answered' (turn produced a final message), 'awaiting_user' (an ask_* tool call ended the round), or 'error'.
   * - Final Message
     - final_message
     - textarea
     - The assistant's text for this round; empty when status is 'awaiting_user' or 'error'.
   * - Pending Ask
     - pending_ask
     - json
     - The outstanding ask (tool_use_id, tool_name, question, options, asked_at) when status is 'awaiting_user'; null otherwise.
   * - Transcript Delta
     - transcript_delta
     - json
     - The agent_raw_v1 transcript entries appended by this call, in order; empty array on error.
   * - Error
     - error
     - string
     - Error message when the turn failed; null on success.

Disciplines
-----------

- ai_ml.agents

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>agent_turn</code>. Schema hash: <code>7acf024a9ea2</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>