Openagent workspace inspect

OpenAgent workspace inspect

Use this skill when the user asks anything about their OpenAgent workspace: past conversations, a specific visitor, what the AI said or did, how the agents are configured, what's in the knowledge base, or whether a workflow is running.

The tools are read-only. Never claim to be creating, editing, or deleting anything through them.

What each tool does (and when to reach for it)

• search_conversations — start here for anything scoped to a time window or a topic. Supports query (substring in the latest visitor message), siteId, state (NEW/BOT_ASSIGNED/HUMAN_ASSIGNED/WAITING_CUSTOMER/CLOSED), sinceIso, limit (max 50). Returns id + preview + counts, freshest first. Follow up with get_conversation for the details.

• get_conversation(id) — the full transcript for one conversation, with every message and its sender kind (VISITOR, AI_AGENT, HUMAN_AGENT, SYSTEM). Use after search_conversations produces a candidate, or when the user pastes a conversation UUID directly.

• get_visitor(id) — CRM record + linked contact + last 25 journey events (page views, referrer, etc). Use when the user wants to know who a visitor is, not what they said. PII notice: this returns email, phone, and any custom identification fields. Don't dump the raw payload back if the user is on a shared screen; summarise.

• list_mcp_invocations — audit log of MCP-client tool calls made by the AI orchestrator (the OTHER direction of MCP: Ai calling out to Shopify, Stripe, etc). Filter by conversationId, toolId, status (SUCCESS/ERROR/TIMEOUT/UNAPPROVED). Args are already PII-redacted at the storage layer. Use for the "the AI took a weird action, what did it call?" investigation.

• list_agents — every configured AI agent: slug, name, isDefault, tools whitelist, system-prompt excerpt (first 400 chars). Use to answer "which agent handles this conversation" or "why isn't the AI calling tool X".

• list_workflows({enabledOnly}) — workflow catalog with trigger type + enabled flag. Doesn't include the step graph (dashboard is better for that). Use to answer "is the refund workflow live?".

• get_kb_document(id) — knowledge base doc metadata + first 8 KB of source text. Use when debugging why the AI answered a certain way — inspect the docs it was grounded in.

The scope of what you can see

The PAT the user handed you inherits exactly the scope of the user that issued it. In practice:

• TENANT_ADMIN PAT — everything in the workspace, every site, every conversation.
• SUPPORT_ENGINEER PAT — only conversations/visitors on the sites their UserSite rows grant. Cross-tenant queries always return zero rows.
• SUPER_ADMIN PAT — tenant-admin view of the tenant the PAT was issued in (no cross-tenant querying via MCP).

If a tool returns { "error": "conversation not found or out of scope" }, don't fabricate why — either the id is wrong or the PAT can't reach it. Ask the user to double-check.

How to answer common questions

Pick the tool sequence that gets to the answer in the fewest calls. Some examples:

"Which conversations mentioned refunds today?" → search_conversations({ query: "refund", sinceIso: <today-midnight>, limit: 50 }) → summarise counts and top 5 previews.

"What did the AI actually say in conversation <uuid>?" → get_conversation({ id: "<uuid>" }) → paraphrase the AI's messages, quote important lines verbatim.

"Did the AI call the Shopify refund tool for that conversation?" → list_mcp_invocations({ conversationId: "<uuid>" }) → look for tool names + statuses. If nothing returned, say "no MCP tool calls on that conversation."

"Why is the AI answering this way about our return policy?" → (a) search_conversations to get the conversation id, (b) get_conversation to read the AI's answer, (c) if the answer cites [doc:N] tags, ask the user which doc UUID they want inspected and call get_kb_document.

"Which of our workflows are turned on right now?" → list_workflows({ enabledOnly: true }) → list name + trigger kind.

"Who's the visitor in conversation <uuid>?" → get_conversation({ id }) returns the visitor.id → get_visitor({ id: <visitor-id> }) for the CRM view.

Failure modes and how to handle them

• 401 unauthorized on any call — PAT is missing, malformed, expired, or revoked. Tell the user to check Settings → Personal Access Tokens and reissue.
• { error: "not found or out of scope" } — either wrong id or role scope. Don't invent an explanation.
• Empty arrays — legitimately no results. Say so; don't retry with looser filters unless the user asked to.
• Truncation — get_kb_document returns the first 8 KB of sourceText. If you need more, say so; there's no "get_kb_chunk" tool yet.

Boundaries

• You cannot write anything. No create, no update, no delete. If the user asks to change something, tell them to use the dashboard or the JWT-authenticated REST API. Do not claim you did it.
• No cross-tenant queries. The PAT is bound to one tenant.
• No customer-facing outreach. These tools don't send messages to visitors. If the user wants to reply to a visitor, they open the conversation in the dashboard.
• Real customer data. Assume every conversation and CRM record is real. Redact when summarising if the user is on a shared screen.

Further reference

• references/tools.md — full input schemas and return shapes for each tool
• references/example-workflows.md — copy-pasteable prompts for common support-ops questions
• references/errors.md — the full status catalog for MCP invocations you'll see in list_mcp_invocations