Skip to main content
Glama
Moe03

Convocore MCP Server

by Moe03
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

interact_with_agent

Runs one Convocore agent turn over WebSocket and returns the streamed reply aggregated into a single response, including text, UI-engine output, actions, metadata, and turn status.

Instructions

Run ONE agent turn over the Convocore /interact WebSocket and return the streamed result aggregated into a single response. Opens a WSS connection to wss://-gcp-api.vg-stuff.com/interact, sends one InteractObject (agentId + convoId + bucket + prompt + optional context), collects every chunk (text + UI-engine + actions + metadata + sync_chat_history) until the server closes (code 1000) or the timeout fires, then returns: { assistantText, uiEngineEnabled, uiEngineSnapshot, uiEngineSummary, actions, metadata, turns, closeCode, durationMs, timedOut, chunkCount, chunks? }.

USAGE:

  • Use the SAME convoId across turns to keep history; use a fresh one to start a new conversation.

  • prompt: "start" triggers the agent's initial greeting (no user message added).

  • prompt: "@cancel:<reason>" cancels an in-flight turn (rarely useful from a single MCP call).

  • prompt: "@rewind:<nodeId>" rewinds a node-based agent.

  • For images, set messageType="visual" and pass visualPayload.

  • bucket is auto-derived from CONVOCORE_API_REGION; only override if you really mean to talk to the other region.

  • Set raw: true to include every streamed chunk (debug frames, chunkIndex, every UI Engine snapshot, etc.) when you need the full trace. Default keeps the response token-cheap.

  • TESTING: set isTest: true for test chats. Pass toolTest: { toolId, toolName, mode: validate|generate-and-test } to exercise one HTTP tool (or use dedicated test_agent_tool). Pass variablesOverrides / initNodesOptions to trial variables without permanently changing them.

  • For a direct HTTP dry-run of a tool's serverUrl use test_agent_tool_request. For multi-turn suites use run_agent_auto_test.

INTERPRETING THE RESPONSE:

  • When uiEngineEnabled: false, the agent streamed plain Markdown — read assistantText.

  • When uiEngineEnabled: true, the agent streamed UI Engine snapshots — read uiEngineSnapshot (parsed final TurnProps) and uiEngineSummary (compact per-message summary). assistantText may be empty in this mode.

  • To force plain text on a UI-Engine-enabled agent for one turn, pass disableUiEngine: true.

UI ENGINE — TWO LAYERS YOU MUST KEEP STRAIGHT:

LAYER 1 — AGENT LLM OUTPUT CONTRACT (what the tested agent is INSTRUCTED to emit):

  • The agent's system prompt forces its LLM to output ONE JSON ARRAY of message objects: [ { "type": "text"|"choice"|"visual"|"cardV2"|"carousel"|"iFrame"|"form"|"input", "payload": {...} }, ... ]

  • The very first character MUST be "[" and the very last MUST be "]". No prose, no ```json fences, no leading/trailing newlines.

  • Preferred message order in the array: text intro -> card / carousel / visual -> iFrame (if video URL exists) -> choice buttons (CTAs).

  • Buttons / image URLs / iFrame URLs MUST come from KB or tool output. NEVER invent URLs. If KB has nothing, omit the button or fall back to text.

  • select / radio fields MUST include a non-empty options[] of { value, label }. If real options are unknown, use type "text" or "textarea" instead.

  • form / input messages WEB CHANNELS ONLY (web-chat / text). On voice / telephony / WhatsApp / SMS / messaging the server strips them.

  • WhatsApp extra rule: only use visual / cardV2 / carousel when you have a verified image URL from KB or a tool — otherwise use text only.

LAYER 2 — WIRE FORMAT (what arrives over the /interact WebSocket):

  • When chunk.ui_engine === true, chunk.chunk is a JSON-stringified TurnProps SNAPSHOT of the bot turn so far.

  • SNAPSHOTS ARE OVERWRITING — replace the in-progress turn with the latest parse, never concatenate.

  • Parsed shape: { from: "bot", ts, modelId?, messages: ChatMessage[] }.

  • Each ChatMessage wraps the agent's array entry: { from: "bot", type, ts, mid?, item: { type, payload } }. So agent emits [{ type, payload }, ...] -> wire wraps each as { ..., item: { type, payload } } inside messages[].

PAYLOAD SHAPES (item.payload): text -> { message } (Markdown supported). choice -> { buttons: [{ name, request: { type: "open_url"|"text", payload: { url|message } } }] }. visual -> { image } (URL ending in .png/.jpg/.jpeg/.webp/.gif/.svg/.avif/.bmp). cardV2 -> { title, imageUrl?, description?: { text }, buttons?: UiEngineButton[] }. carousel -> { cards: CardPayload[] }. iFrame -> { layout: "vertical"|"horizontal", url } (vertical = video embeds, horizontal = general web). form -> { title?, description?, fields: UiEngineInputField[], submitButton?, onSubmit: { type: "submit_form", message? } }. Web channels only. input -> { field: UiEngineInputField, submitOnEnter?, onSubmit: { type: "submit_input", message? } }. Web channels only. UiEngineInputField.type: text|email|password|number|tel|url|textarea|select|checkbox|radio|date|time|datetime-local|file.

WHEN ui_engine === false (or omitted): chunk.chunk is plain Markdown text — append to the in-progress assistant message. TO FORCE PLAIN TEXT on a UI-Engine-enabled agent for one turn: pass disableUiEngine: true on the InteractRequest.

SERVER SANITIZERS YOU SHOULD KNOW (so you do not get surprised when a message disappears):

  • form messages with zero valid fields are DROPPED.

  • input messages with an invalid field are DROPPED.

  • select / radio fields with empty / duplicate / missing-label options are DROPPED.

  • any field missing id or label is DROPPED.

For the FULL UI Engine schema (every payload field, validation rules, allowed enums) call get_ui_engine_spec first.

WARNING: This consumes Convocore credits exactly like a real agent turn (LLM + voice + tools). It is NOT a dry-run.

Input Schema

NameRequiredDescriptionDefault
v2NoForce routing to the v2 (node-based) handler.
rawNoWhen true, include every raw streamed chunk in the response. Default false (token-cheap aggregated view only).
bucketNoRegion bucket. Auto-derived from CONVOCORE_API_REGION when omitted (eu-gcp -> "voiceglow-eu", na-gcp -> "(default)").
isTestNoMarks the turn as a test interaction.
promptNoUser message. Special values: "start" (initial greeting), "@cancel:<reason>", "@rewind:<nodeId>".
agentIdYesThe ID of the agent to interact with.
convoIdYesConversation ID. Reuse across turns to keep history; use a fresh ID to start a new conversation.
replyToNoReply context when the user is replying to a previous message.
toolTestNoRun a single tool in test mode.
agentDataNoOptional agent override. When provided with at least an `ID`, the server skips loading the agent doc from Firestore.
kbPreviewNoKnowledge-base preview mode (skips node routing).
sessionIdNoOptional session id; defaults to convoId server-side.
timeoutMsNoHow long to wait for the streamed turn to complete before closing the WebSocket. Default 120000 (120s), max 600000 (10min).
isLLMStudioNoMarks the turn as originating from LLM Studio.
messageTypeNoType of input. Use "visual" together with visualPayload for images.
turnsHistoryNoOptional override of conversation turns. When set, the server uses this instead of fetching from Firestore.
visualPayloadNoImage/visual content for messageType: "visual" turns.
workspaceDataNoOptional workspace override.
actionMetadataNoIncludes mid (client-supplied message id) used for de-duplication.
agentProfileIdNoInternal profile id (e.g. agency_plan_builder_v1).
lightConvoDataNoPer-conversation user/context metadata (userName, userEmail, userPhone, origin, capturedVariables, ...). Surfaced to the agent system prompt where supported.
disableUiEngineNoDisable UI-engine JSON output for this turn.
initNodesOptionsNoOptional overrides for tools / variables / messages history at session init.
variablesOverridesNoCreate or override agent variables for this interact turn only (without permanently PATCHing variables).
disableRecordHistoryNoSkip persisting this turn to Firestore.
formSubmissionMetadataNoPayload describing a UI-engine form / input submission.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.6.17

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say non-readonly, open-world, non-idempotent, non-destructive; the description goes far beyond them by disclosing credit consumption, the exact close condition (code 1000 or timeout, default 120s/max 10min), which streamed artifacts are collected, and the server-side sanitizers that silently drop malformed form/input/select messages. That sanitizer list is behavior an agent genuinely cannot infer from any structured field.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded and well-sectioned, with the return shape stated up front so the agent knows what comes back. But it is very long, and much of it (per-payload-type shapes, UiEngineInputField enums, agent array contract) duplicates content that it itself redirects to get_ui_engine_spec, which bloats context for an agent that needs one call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 26 parameters, nested objects, and no output schema, the description supplies exactly the missing piece: an explicit enumerated return shape plus interpretation guidance for the uiEngineEnabled true/false branches. An agent has enough to call this correctly and read the result without further lookups.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and nearly all 26 parameters already carry their own descriptions, including bucket auto-derivation and prompt special values, so the baseline applies. The description adds only marginal extra meaning, chiefly pairing messageType="visual" with visualPayload and warning that bucket overrides should be rare.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb, resource, and transport: run ONE agent turn over the Convocore /interact WebSocket and return the aggregated streamed result. It explicitly frames the operation as a real agent turn that consumes credits, which separates it from the dry-run siblings without needing the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The USAGE block gives explicit when-to-use rules (reuse convoId for history, fresh for a new conversation), special prompt values, and names concrete alternatives for adjacent jobs: test_agent_tool for a single tool, test_agent_tool_request for an HTTP dry-run, run_agent_auto_test for multi-turn suites, get_ui_engine_spec for the full schema. Exclusions are covered by the WARNING noting this is not a dry-run.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools