# RevCent MCP Overview: AI Threads AI/MCP-focused overview of AI Threads in RevCent. --- ## Purpose This guide explains what AI Threads are, how they are created, what they contain, and how AI/MCP clients should use the `GetAIThread` operation to inspect a specific AI Assistant run. An AI Thread is the execution record for a specific run of an AI Assistant. --- ## Core Concept An AI Assistant is the reusable configuration: ```text AI Assistant = instructions + trigger settings + flow + third-party AI integration ``` An AI Thread is a specific run of that AI Assistant: ```text AI Thread = one execution/run of an AI Assistant ``` When an AI Assistant is triggered, RevCent creates a unique AI Thread. The AI Thread records the messages, steps, and tool calls that occurred during that run. --- ## AI Assistant vs AI Thread | Concept | Meaning | |---|---| | AI Assistant | The configured assistant: instructions, trigger, flow, limits, and enabled tools. | | AI Thread | A specific execution/run of that AI Assistant. | | AI Thread Message | A user, assistant, or system message inside the thread. | | Tool Call | A function/tool request made by the assistant during the thread. | | Previous AI Thread | A prior thread whose context may be passed into a new thread. | Important: ```text Do not confuse the AI Assistant with the AI Thread. ``` An AI Assistant can run many times. Each run creates its own AI Thread. --- ## How AI Threads Are Created AI Threads are created when an AI Assistant is triggered. AI Assistants can be triggered from different sources: ```text api web_app account_event ``` Common creation paths: ```text TriggerAIAssistant via API/MCP AI Assistant triggered from the RevCent web app AI Assistant triggered by an account event AI Assistant triggered by another AI Assistant/system tool ``` The `TriggerAIAssistant` operation returns: ```text ai_thread_id ai_assistant_id ``` Use the returned `ai_thread_id` with: ```text GetAIThread ``` to inspect the thread later. --- ## Related Operations | Operation | Purpose | |---|---| | `GetAIThread` | Retrieve details of a specific AI Thread. | | `TriggerAIAssistant` | Trigger an on-demand AI Assistant and create a new AI Thread. | | `GetAIAssistant` | Retrieve the AI Assistant configuration associated with the thread. | | `GetAIAssistants` | Find an AI Assistant when only its name/description is known. | --- ## `GetAIThread` Operation Operation: ```text GetAIThread ``` Title: ```text Get An AI Thread ``` Purpose: ```text Retrieve the details of a specific AI Thread. ``` Input: ```json { "ai_thread_id": "TTTTTTTTTTTTTTTTTTTT" } ``` The `ai_thread_id` must be a 20-character AI Thread ID. --- ## What `GetAIThread` Returns `GetAIThread` can return: ```text id status messages message_count total_tokens total_time_ms previous_ai_thread trigger ai_assistant third_party_integration time_delay_expires created_date_unix updated_date_unix ``` These fields allow AI/MCP to understand what happened during a specific AI Assistant run. --- ## AI Thread Status The AI Thread status can be: ```text Running Complete Timer Cancelled Error ``` | Status | Meaning | |---|---| | `Running` | The thread is currently processing. | | `Complete` | The thread finished successfully. | | `Timer` | The thread is delayed/hibernating due to a time delay. | | `Cancelled` | The thread was cancelled. | | `Error` | The thread ended with an error. | If status is `Timer`, then `time_delay_expires` indicates when the AI Thread will resume. --- ## Messages The `messages` array contains the message history for the AI Thread. Each message can include: ```text role content tool_call_id tool_calls previous_ai_thread created_date_unix third_party_name third_party_model ``` Supported message roles: ```text user assistant system ``` Messages are the primary way to inspect what the assistant saw, said, requested, and received during the thread. --- ## Tool Calls Inside AI Threads AI Thread messages can include tool calls. Tool call fields can include: ```text id type function_name function_args ``` The tool call `type` is: ```text function ``` A tool call represents a tool/function request made by the AI during the thread. Conceptual example: ```json { "role": "assistant", "content": "", "tool_calls": [ { "id": "call_123", "type": "function", "function_name": "GetSale", "function_args": "{\"sale_id\":\"SSSSSSSSSSSSSSSSSSSS\"}" } ] } ``` A later message may include `tool_call_id` to show that it is associated with a tool call submission/result. --- ## Why Tool Calls Matter Tool calls make AI Threads useful for auditing and debugging. They show: - which operation/tool the assistant requested, - what arguments were sent, - whether the assistant attempted to retrieve or modify data, - what sequence of actions happened during the thread, - where a mistake or unexpected result may have occurred. When reviewing an AI Thread, AI/MCP should inspect tool calls carefully before summarizing what the assistant did. --- ## Trigger Information The `trigger` object explains why the AI Thread was created. Trigger source values include: ```text api web_app account_event ``` If source is `api`, the thread may include the API call that triggered it. If source is `web_app`, the thread may include the web user that triggered it. If source is `account_event`, the thread may include the event notation. Examples of account event notations include: ```text sale.created sale.created.success.paid fraud_detection.created shipping.updated.shipped subscription.updated.renewed.success sentinel.alert ``` The trigger source helps determine whether the thread was manually run, API-triggered, or caused by an automated account event. --- ## Associated AI Assistant `GetAIThread` returns the AI Assistant associated with the thread: ```text ai_assistant.id ai_assistant.name ``` Use `GetAIAssistant` if you need to inspect the assistant configuration that produced the thread. The AI Assistant configuration can explain: - base instructions, - trigger settings, - account event filters, - flow nodes, - time delay nodes, - branch nodes, - third-party AI integration, - assistant limits. --- ## Previous AI Thread / Handoff AI Threads can be related to previous AI Threads. This happens when `TriggerAIAssistant` is called with: ```text previous_ai_thread ``` The previous-thread object can include: ```text ai_thread_id include_messages ``` If `include_messages = true`, previous messages may be passed into the new thread. Important: ```text Including previous thread messages consumes more tokens. ``` Only include previous messages when the previous context is truly necessary. If providing `previous_ai_thread` with messages, do not duplicate the same existing messages in the new `messages` array. --- ## Messages From Previous Threads Inside a message, `previous_ai_thread` can indicate the message originated from a prior AI Thread. This is useful for handoff flows, where one AI Assistant passes context to another AI Assistant. The thread-level `previous_ai_thread` field can also indicate that the current AI Thread was created from a previous AI Thread handoff. --- ## AI Thread Usage Metrics `GetAIThread` can return usage/performance metrics: ```text message_count total_tokens total_time_ms ``` Use these to understand: - how large the thread became, - how many messages were exchanged, - how many tokens were consumed, - how long the thread took to process. These metrics are helpful for debugging, cost awareness, performance review, and assistant optimization. --- ## Third-Party AI Integration AI Threads can include the third-party AI integration used for the run. The thread can identify: ```text third_party_integration.id third_party_integration.name third_party_integration.third_party.id third_party_integration.third_party.name ``` Individual messages can also include: ```text third_party_name third_party_model ``` This helps identify which AI provider/model processed messages in the thread. --- ## TriggerAIAssistant Relationship `TriggerAIAssistant` creates a new AI Thread. Important rule: ```text Only AI Assistants with trigger = on_demand can be triggered via API. ``` If you do not know the AI Assistant ID: ```text Use GetAIAssistants first. ``` If triggering for a specific RevCent item, include: ```text source_type = item item_type item_id ``` Supported item types include: ```text sale customer product_sale shipping subscription subscription_renewal salvage_transaction transaction chargeback fraud_detection ``` Optional messages can be included when triggering the assistant. --- ## Typical Review Workflow When a user asks what happened in an AI Assistant run: ```text 1. Get the AI Thread ID. 2. Call GetAIThread. 3. Review status. 4. Review trigger source. 5. Review associated AI Assistant. 6. Review messages in order. 7. Review tool calls and arguments. 8. Review message_count, total_tokens, and total_time_ms. 9. Summarize what happened. 10. If needed, retrieve related items referenced by tool calls. ``` --- ## Debugging Workflow When troubleshooting a failed or unexpected run: ```text 1. GetAIThread. 2. Check status: Error, Cancelled, Timer, Running, or Complete. 3. Inspect the last messages. 4. Inspect tool calls before the issue. 5. Check function_args for invalid IDs or missing fields. 6. Check whether the assistant had the correct trigger/event/item context. 7. Check whether a previous thread handoff added confusing or stale context. 8. Check token/time usage. 9. Review the AI Assistant configuration with GetAIAssistant. ``` --- ## AI Thread as an Audit Trail An AI Thread is useful as an audit trail because it can show: - why the run started, - which assistant ran, - which model/provider was used, - what messages were sent, - what tool calls were requested, - what arguments were sent to tools, - how many messages/tokens were consumed, - whether the run completed, errored, was cancelled, or entered a timer state. For high-impact assistant workflows, always inspect the thread before making claims about what the AI did. --- ## Time Delay / Timer Threads An AI Assistant flow can include an `action_time_delay` node. When a thread reaches a time delay, its status may become: ```text Timer ``` In this state: ```text The thread is hibernating until time_delay_expires. ``` Do not treat `Timer` as failure. Inspect `time_delay_expires` to understand when the thread is scheduled to continue. --- ## AI Threads vs AI Voice Calls AI Threads are for AI Assistant runs. AI Voice Calls are separate records produced by AI Voice Agents. Do not use `GetAIThread` to inspect AI Voice Call transcripts or call metadata. Use AI Voice Call operations, such as: ```text GetAIVoiceCall ``` for voice-agent call details. --- ## Human-in-the-Loop Guidance When a human asks about an AI Thread, AI/MCP should: - explain the thread status, - summarize the purpose of the run, - identify the AI Assistant that ran, - summarize key messages and tool calls, - avoid exposing sensitive details unnecessarily, - retrieve related RevCent items if needed to explain the outcome, - distinguish between what the assistant intended and what the tools actually did. --- ## No-Human-in-the-Loop Guidance When an external agent inspects an AI Thread without a human in the loop: ```text Use GetAIThread only for the provided ai_thread_id. Do not infer unrelated context. Do not trigger a new AI Assistant unless explicitly authorized. Return structured findings. Stop safely if the thread ID is missing or invalid. ``` --- ## Common Mistakes to Avoid Do not: - confuse AI Assistant ID with AI Thread ID, - assume a thread is complete without checking `status`, - ignore `Timer` status, - ignore tool calls when summarizing what happened, - assume tool arguments were valid without inspecting them, - trigger another assistant run just to inspect an existing thread, - duplicate previous-thread messages when triggering a handoff, - expose sensitive customer/payment/fraud data unnecessarily. --- ## Recommended Summary Format When summarizing an AI Thread for a user: ```text AI Thread: [id] Status: [status] AI Assistant: [name/id] Trigger: [source / notation / API call / web user] Messages: [message_count] Tokens: [total_tokens] Processing time: [total_time_ms] What happened: - [Brief ordered summary] Tool calls: - [function_name] with [high-level argument summary] Outcome: - [Complete / Timer / Error / Cancelled / Running] ``` --- ## Final AI/MCP Instruction An AI Thread is a specific run of an AI Assistant. Use `GetAIThread` to inspect the contents, purpose, status, messages, tool calls, trigger source, usage metrics, model/provider context, and previous-thread handoff details for that run. When an AI Assistant is triggered, a new AI Thread is created. Each AI Thread represents the steps, messages, and tool calls that occurred during that specific AI Assistant run. --- Document Parent Directory * [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.