Assistant Response Formats

Deepdesk Assistants can produce responses in different formats depending on the use case and integration requirements. The formats fall into three main categories:

1. Plain Text Format
2. Custom JSON Schema Format
   • Flexible structured data format
   • Schema not enforced by the system
   • Ideal for SDK/API integrations with custom data requirements
   • Enables machine-to-machine communication
3. Object Formats
   • Predefined schemas with system-enforced structures:
     • Assistant Cue: Displays contextual information to agents in UI widgets
     • Knowledge Assist: Powers the dedicated knowledge base question-answering interface

Each format serves a specific purpose in the Deepdesk ecosystem. Understanding these formats and implementing them correctly ensures seamless integration between your assistants and the Deepdesk frontend. This chapter provides prompt instructions for each format to help you create assistants that reliably produce properly structured outputs.

Plain Text Responses

Plain text responses are the most straightforward format, delivering content without structured metadata.

Prompt Instructions for Plain Text Format

To ensure your assistant produces well-formatted plain text, include these instructions:

Respond in plain text with clear formatting:
- Use bullet points for lists of features
- Include numbered steps for procedures
- Highlight important warnings or notes with asterisks or capitalization
- Maintain a friendly, helpful tone throughout
- Do not use JSON or other structured formats

Your response will be displayed directly to the user, so ensure it's readable and well-organized.

Format Example

This is a plain text response that can include any content the assistant generates.
It can span multiple lines and include rich formatting like:
- Bullet points
- Numbered lists
1. First item
2. Second item

When to Use Plain Text Format

Use plain text format in these scenarios:

• Direct customer communication: When the assistant is called via a Route, sending responses directly to end customers
• Intermediary processing: When another assistant (like an Operator) will process the response and format it appropriately
  • Example: An Operator with instructions to return Cue schema calls an assistant for a summary. The assistant returns plain text, and the Operator formats it into the correct schema.
• Simple integration needs: When working with systems that expect unstructured text
• Maximum compatibility: When you need responses to work across different clients and interfaces

Implementation Considerations

• Plain text is the default response format if no other format is specified
• Include formatting guidelines in your instructions for consistency
• Even in plain text, you can use markdown-style formatting for improved readability
• Test responses in the actual interface to ensure proper display

Assistant Cue Responses

Assistant Cue responses are designed to display relevant information to human agents in the Deepdesk widgets. Each cue appears as a separate message in the "Assistant Updates" section in the interface.

Prompt Instructions for Assistant Cue Format

To ensure your assistant produces properly formatted cues, include these instructions:

Format your response as follows:
[
{
"code": "your-assistant-code",
"name": "Your Assistant Name",
"response": "The response based on the instructions"
}
]

How the Assistant Cue System Works

When an assistant outputs a response in the Cue format, the Deepdesk frontend system:

1. Detects the JSON structure with the required fields
2. Renders it as a specialized UI component (the "Assistant Updates" widget)
3. Uses the "name" field as the header text
4. Displays the "response" field as the body content
5. Maintains the association with the specific assistant via the "code" field

If the assistant's response doesn't follow this exact schema, the frontend system will not recognize it as a Cue and won't display it in the specialized UI component.

Schema Structure

The output from the assistant must match this exact schema:

[
{
"code": "assistant-code",  // The unique identifier of the assistant
"name": "Assistant Name",  // Display name shown in the UI header
"response": "Response text from the assistant"  // Content shown in the UI body
}
]

Each field serves a specific purpose:

• code: Identifies which assistant provided the response (must match a valid assistant code)
• name: Creates the header text in the UI widget (should be human-readable)
• response: Contains the actual content to display (can include markdown formatting)

Cue Response Formatting

The content shown in the UI can contain markdown formatting:

• Use bullet points for lists of features
• Include numbered steps for procedures
• Highlight important warnings or notes with asterisks or capitalization
• Single backticks allow users to easily copy content: contenttocopy
• Triple backticks allow users to use the content directly in a chat interaction

Your response will be displayed directly to the agent, so ensure it's readable and well-organized.

Visual Representation

When rendered in the UI, an Assistant Cue appears in the widget under "ASSISTANT UPDATES" with:

• The assistant name as a header (e.g., "Compliance Assistant")
• The response text in the body
• Action buttons (thumbs up/down, close)

When to Use Assistant Cue Format

Use the Assistant Cue format when:

• Providing information to human agents rather than end customers
• Creating specialized assistants that provide contextual insights
• Building multi-assistant workflows where each assistant has a specific role
• Creating assistants that need visual distinction in the interface
• Implementing escalation paths between different assistant types

On Demand Assistants

On Demand Assistants are assistants that are called directly by the agent. They produce responses in the Assistant Cue format that appears in the UI widget.

Prompt Instructions for On Demand Assistants

For On Demand Assistants, include these instructions in your prompt:

When providing specialized information to the agent, format your response as a cue:
[{
"code": "your-assistant-code",
"name": "Your Assistant Name",
"response": "Your detailed response based on the instructions"
}]

This will display your response in the Assistant Updates section. Make sure your response is clear, concise, and formatted for readability.

If you have no relevant information to provide, respond with an empty object: {}

On Demand Assistants typically return a single cue, but they can theoretically return multiple cues in an array format (similar to Operators) or remain silent by returning an empty object if they have nothing relevant to contribute.

Operator Assistants and Multiple Cues

Operator assistants can call multiple specialized assistants and return multiple cues.

Prompt Instructions for Operator Assistants

For operators that need to return multiple cues, include these instructions:

Examine the conversation and determine which specialized assistants should respond.
Call the relevant assistants and return their responses as a list of objects.
Only include assistants that provide meaningful responses.
Exclude any responses that are "none," "{}", or equivalent. If a response seems irrelevant, omit it.
If an assistant's response contains markdown, keep that intact.
If none of the assistants seems relevant, respond with: "[]".

Format each valid response with these keys:
- code: The assistant's unique code
- name: The assistant's display name
- response: The complete response text (in plain text or markdown, not JSON)

Example Operator Response Format
[
{
"code": "compliance-assistant",
"name": "Compliance Assistant",
"response": "It looks like this customer needs to be verified, if not already: the visitor has provided their account number, which may require verification for security purposes."
},
{
"code": "product-assistant",
"name": "Product Assistant",
"response": "This customer is eligible for our premium package based on their account history."
}
]

Implementation Considerations

• Configure the assistant with Response Format set to "JSON Schema" in settings
• Ensure the referenced assistant code exists in your environment
• Use consistent, recognizable assistant names for clarity in the UI
• For operators, implement proper filtering to avoid irrelevant responses
• Test with various conversation flows to ensure proper rendering

Knowledge Assist Responses

Knowledge Assist responses provide a dedicated interface where human agents can ask questions and receive documented information with source references. This interface appears in the widget under "KNOWLEDGE ASSISTANT" in the Deepdesk interface, allowing agents to quickly find verified information while assisting customers.

How the Knowledge Assist System Works

Knowledge Assist is a specialized RAG (Retrieval Augmented Generation) implementation that:

1. Presents a dedicated question-answering interface to human agents
2. Processes agent questions through knowledge sources
3. Returns formatted answers with source attributions
4. Displays the information in a structured UI widget with feedback controls

To configure a Knowledge Assist, you need to:

• Create a Knowledge Assistant first via Admin Settings > Knowledge Assistant
  • This is where you connect to the knowledge sources and provide custom instructions
• Create an assistant that uses the call_knowledge_assist tool
• Set the response format to "JSON Schema"
• Select "Knowledge Assist" as the response format schema

Prompt Instructions for Knowledge Assist Format

To ensure proper formatting of Knowledge Assist responses, include these instructions in your prompt:

When answering questions:
1. Format your response as a valid JSON object with these exact fields:
- "answer": Provide a clear, concise response to the question
- "question": Include the original question being answered
- "sources": Include an array of sources that provided the information
- Each source should have a "name" (document title) and "url" (reference link)

2. Ensure your answer is accurate, concise, and helpful
3. Always provide source attribution when available
4. Format any lists or technical information for readability

Example format:
{
"answer": "Your detailed response here...",
"question": "The original question",
"sources": [
{"name": "Source document name", "url": "URL to source"}
]
}

Schema Structure

{
"answer": "Answer text that responds to the user's question with detailed information.",
"question": "Original question that was asked",
"sources": [
{
"name": "Source document name",
"url": "URL or reference to the source"
},
{
"name": "Second source name",
"url": "Second source URL"
}
]
}

Each field serves a specific purpose:

• answer: Contains the response to the agent's question
• question: Reflects the original question for context
• sources: Provides attribution and reference links when applicable

Required and Optional Fields

• answer (required): The response text
• question (required): The original question being answered
• sources (optional): Array of source references that provided the information
  • name (required if sources included): Title or name of the source
  • url (required if sources included): URL or reference identifier

Visual Representation

When rendered in the UI, a Knowledge Assist response appears in the widget under "KNOWLEDGE ASSISTANT" with:

• The question in bold
• The answer text in the body with proper formatting
• Source links at the bottom (if provided)
• Feedback controls (thumbs up/down)

When to Use Knowledge Assist Format

Use Knowledge Assist format when:

• Creating an assistant specifically for knowledge retrieval
• Building a dedicated interface for agents to query company knowledge
• Implementing a system that requires source citation and attribution
• Providing verified information from authoritative sources

Implementation Considerations

• Include specific instructions for source citation in your assistant prompt
• Consider using skip_evaluation:true when external systems already return properly formatted Knowledge Assist responses
• Ensure knowledge sources are well-structured for accurate retrieval
• Test the system with common agent questions to verify accuracy
• Pay attention to answer formatting for readability in the UI

Custom JSON Schema Responses

For assistants that need structured outputs beyond the predefined formats, Deepdesk offers the option to use custom JSON Schema responses. This is particularly useful for assistants called via the SDK or API that need to return structured data.

How JSON Schema Format Works

When you select "JSON Schema" as the response format in assistant settings:

1. The system expects the assistant to return JSON-formatted responses
2. Unlike the Knowledge Assist format, the schema structure is not enforced or validated
3. The response can follow any structure defined in your prompt instructions
4. The response is passed directly to the consuming application

Configuration Steps

To configure an assistant to use custom JSON Schema:

1. In the assistant settings, set "Response format" to "JSON Schema"
2. Include detailed schema instructions in your prompt

Prompt Instructions for Custom JSON Responses

Your prompt must include clear instructions about the expected JSON structure:

Return your response in the following JSON format:
{
"status": "success or error",
"data": {
"field1": "Value for field1",
"field2": "Value for field2",
"nested": {
"subfield": "Value for subfield"
}
},
"metadata": {
"timestamp": "Current timestamp",
"version": "1.0"
}
}

Ensure all fields are properly formatted and follow JSON syntax:
- Use double quotes for keys and string values
- Do not include trailing commas
- Properly escape special characters

Example Use Cases

Custom JSON Schema responses are ideal for:

• Integration with external systems that require specific data structures
• Building assistants that feed data into dashboards or analytics tools
• Creating assistants that return machine-readable data for further processing
• Standardizing outputs for API-based workflows
• Building custom data extraction flows

Implementation Considerations

• Thoroughly document the expected schema in your prompt instructions
• Include examples of valid responses to guide the assistant
• Provide error handling instructions for cases where the requested data is unavailable
• Consider adding validation logic in your consuming application
• Test with various input scenarios to ensure consistent output formatting
• Include fallback options for unexpected data patterns

Validating Response Formats

When implementing assistants with specific response formats:

1. Test extensively with varied inputs
2. Ensure all required fields are present and properly formatted
3. Verify the format matches downstream system expectations
4. Consider implementing a schema validation layer
5. Use appropriate error handling for malformed responses
6. Create automated tests for your critical response formats

By focusing on clear prompt instructions for each response format, you can create assistants that reliably produce the right output for seamless integration with your systems.