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¶
| 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¶
| 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
Auto-generated from platform schema. Worker id: agent_turn. Schema hash: 7acf024a9ea2. Hand-curated docs in workerexamples/ override this page when present.