Skip to main content
Glama
Sign In

Convocore

by app.convocore.mcp
OverviewDiscussionsAdmin

interact_with_agent

Destructive

Send one test message to one of the user's Convocore agents and return the agent's reply, exactly as a customer chatting with it would see it. The agent answers with its own prompt, knowledge base and tools, so a turn can run the agent's configured actions (bookings, lookups) and spends credits like a real chat. Returns { assistantText, uiEngineEnabled, uiEngineSnapshot, uiEngineSummary, actions, metadata, turns, durationMs, timedOut }.

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).

  • 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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "agentId": "<agentId>",
      "convoId": "<convoId>"
    },
    "name": "interact_with_agent"
  }
}

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 observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds substantive context beyond them: it spends real Convocore credits (LLM + voice + tools), can trigger the agent's configured actions (bookings, lookups), and is explicitly NOT a dry-run. It also discloses timeout bounds, sanitizer drop rules, and region/bucket behavior. The only shortfall is that it doesn't spell out auth/permission prerequisites.

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 sectioned with clear headers, but the bulk of the text is a full UI Engine message-contract and payload-shape reference that belongs in the referenced get_ui_engine_spec tool, not in the selection/invocation surface. It self-admits this by telling the caller to fetch the spec first, so a large fraction of the text does not earn its place here.

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 compensates fully: it enumerates the exact return keys, explains how to read uiEngineEnabled true vs. false responses, warns about credit cost, and documents the timeout/sanitizer edge cases an agent would otherwise be surprised by.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3, but the description adds genuine operational meaning: bucket is auto-derived from CONVOCORE_API_REGION and should rarely be overridden, disableUiEngine forces plain text for one turn, variablesOverrides apply only to this turn, and toolTest exercises a single HTTP tool. A handful of the 26 parameters (replyTo, actionMetadata, agentProfileId, v2, sessionId) get no narrative treatment, keeping it off a 5.

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?

Opens with a specific verb+resource+scope: send one message to a Convocore agent and return the reply as a customer would see it. It immediately distinguishes itself from sibling test tools (test_agent_tool, test_agent_tool_request, run_agent_auto_test) by naming them as alternatives for narrower jobs.

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/when-not rules: reuse convoId for history vs. fresh one for a new conversation, prompt="start" for the greeting, raw:true only for full traces, isTest/toolTest for testing, and dedicated siblings for tool dry-runs and multi-turn suites. Nothing about selecting this tool is left to inference.

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

All Convocore toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources