Creating Conversations

Basic Conversation Creation

Creating a conversation is the first step to building any conversational AI application. Every conversation requires settings that define its behavior and capabilities.

from noxus_sdk.client import Client
from noxus_sdk.resources.conversations import ConversationSettings

client = Client(api_key="your_api_key_here")

# Basic conversation settings
settings = ConversationSettings(
    model=["gpt-4o-mini"],
    temperature=0.7,
    max_tokens=300,
    extra_instructions="You are a helpful assistant."
)

# Create the conversation
conversation = client.conversations.create(
    name="My First Conversation",
    settings=settings
)

print(f"Created conversation: {conversation.id}")

Configuration Options

Model Selection

Choose the appropriate AI model for your use case:

# Single model
settings = ConversationSettings(
    model=["gpt-4o-mini"]  # Fast and cost-effective
)

# Multiple models (fallback order)
settings = ConversationSettings(
    model=["gpt-4o", "gpt-4o-mini"]  # Try GPT-4o first, fallback to mini
)

# Different models for different purposes
creative_settings = ConversationSettings(
    model=["gpt-4o"],  # More creative and capable
    temperature=0.8
)

factual_settings = ConversationSettings(
    model=["gpt-4o-mini"],  # Fast for factual queries
    temperature=0.2
)

Temperature and Creativity

Control the randomness and creativity of responses:

# Very deterministic (good for factual content)
factual_settings = ConversationSettings(
    model=["gpt-4o-mini"],
    temperature=0.0,  # Most deterministic
    extra_instructions="Provide factual, consistent answers."
)

# Balanced (good for general conversation)
balanced_settings = ConversationSettings(
    model=["gpt-4o-mini"],
    temperature=0.7,  # Balanced creativity
    extra_instructions="Be helpful and engaging."
)

# Creative (good for content generation)
creative_settings = ConversationSettings(
    model=["gpt-4o"],
    temperature=0.9,  # Most creative
    extra_instructions="Be creative and think outside the box."
)

Token Limits

Control response length and cost:

# Short responses
concise_settings = ConversationSettings(
    model=["gpt-4o-mini"],
    max_tokens=100,  # Brief responses
    extra_instructions="Keep responses under 50 words."
)

# Medium responses
standard_settings = ConversationSettings(
    model=["gpt-4o-mini"],
    max_tokens=500,  # Standard length
    extra_instructions="Provide comprehensive but concise answers."
)

# Long responses
detailed_settings = ConversationSettings(
    model=["gpt-4o"],
    max_tokens=1500,  # Detailed responses
    extra_instructions="Provide thorough, detailed explanations."
)

Adding Tools

Tools extend conversation capabilities beyond basic text generation:

Web Research Tool

from noxus_sdk.resources.conversations import WebResearchTool

web_tool = WebResearchTool(
    enabled=True,
    extra_instructions="Focus on recent, reliable sources. Always cite sources."
)

research_settings = ConversationSettings(
    model=["gpt-4o-mini"],
    temperature=0.4,
    max_tokens=600,
    tools=[web_tool],
    extra_instructions="Use web research when you need current information."
)

research_bot = client.conversations.create(
    name="Research Assistant",
    settings=research_settings
)

Knowledge Base Integration

from noxus_sdk.resources.conversations import KnowledgeBaseQaTool

# Single knowledge base
kb_tool = KnowledgeBaseQaTool(
    enabled=True,
    kb_id="your_knowledge_base_id",
    extra_instructions="Provide detailed answers with specific references."
)

# Multiple knowledge bases with selector
from noxus_sdk.resources.conversations import KnowledgeBaseSelectorTool

kb_selector = KnowledgeBaseSelectorTool(
    enabled=True,
    extra_instructions="Choose the most relevant knowledge base for each query."
)

kb_settings = ConversationSettings(
    model=["gpt-4o-mini"],
    temperature=0.3,
    tools=[kb_tool, kb_selector],
    extra_instructions="Always check knowledge bases first for company-specific information."
)

support_bot = client.conversations.create(
    name="Support Bot",
    settings=kb_settings
)

Workflow Integration

from noxus_sdk.resources.conversations import WorkflowTool

workflow_tool = WorkflowTool(
    enabled=True,
    workflow={
        "id": "data_analysis_workflow_id",
        "name": "Data Analyzer",
        "description": "Analyze datasets and generate insights"
    },
    name="Data Analysis",
    description="Run data analysis on uploaded files"
)

analyst_settings = ConversationSettings(
    model=["gpt-4o"],
    temperature=0.4,
    tools=[workflow_tool],
    extra_instructions="Use the data analysis workflow for any data-related requests."
)

data_analyst = client.conversations.create(
    name="Data Analyst Bot",
    settings=analyst_settings
)

Specialized Conversation Types

Customer Support Bot

from noxus_sdk.resources.conversations import (
    ConversationSettings,
    KnowledgeBaseQaTool,
    WebResearchTool
)

# Support bot with knowledge base and escalation
support_kb_tool = KnowledgeBaseQaTool(
    enabled=True,
    kb_id="support_kb_id",
    extra_instructions="Check for existing solutions and troubleshooting steps."
)

support_settings = ConversationSettings(
    model=["gpt-4o-mini"],
    temperature=0.3,  # Consistent, helpful responses
    max_tokens=400,
    tools=[support_kb_tool],
    extra_instructions="""You are a customer support assistant.
    - Always be empathetic and helpful
    - Check the knowledge base for solutions first
    - If you can't solve the issue, suggest contacting human support
    - Ask clarifying questions when needed"""
)

support_bot = client.conversations.create(
    name="Customer Support Bot",
    settings=support_settings
)

Content Creation Assistant

content_settings = ConversationSettings(
    model=["gpt-4o"],
    temperature=0.7,  # Creative but controlled
    max_tokens=800,
    tools=[WebResearchTool(
        enabled=True,
        extra_instructions="Research current trends and examples"
    )],
    extra_instructions="""You are a content creation assistant.
    - Help with blog posts, social media, and marketing copy
    - Research current trends when relevant
    - Ask about target audience and goals
    - Provide multiple options when possible"""
)

content_assistant = client.conversations.create(
    name="Content Creator",
    settings=content_settings
)

Technical Documentation Bot

from noxus_sdk.resources.conversations import NoxusQaTool

tech_doc_settings = ConversationSettings(
    model=["gpt-4o"],
    temperature=0.2,  # Precise, technical responses
    max_tokens=1000,
    tools=[
        KnowledgeBaseQaTool(
            enabled=True,
            kb_id="technical_docs_kb_id",
            extra_instructions="Reference official documentation and code examples"
        ),
        NoxusQaTool(
            enabled=True,
            extra_instructions="Help with Noxus platform questions"
        )
    ],
    extra_instructions="""You are a technical documentation assistant.
    - Provide accurate, detailed technical information
    - Include code examples when relevant
    - Reference official documentation
    - Ask for clarification on technical requirements"""
)

tech_bot = client.conversations.create(
    name="Technical Assistant",
    settings=tech_doc_settings
)

Advanced Configuration

Multi-Tool Conversations

from noxus_sdk.resources.conversations import (
    WebResearchTool,
    KnowledgeBaseQaTool,
    WorkflowTool,
    NoxusQaTool
)

# Comprehensive assistant with multiple capabilities
multi_tool_settings = ConversationSettings(
    model=["gpt-4o"],
    temperature=0.6,
    max_tokens=600,
    tools=[
        WebResearchTool(
            enabled=True,
            extra_instructions="Use for current events and recent information"
        ),
        KnowledgeBaseQaTool(
            enabled=True,
            kb_id="company_kb_id",
            extra_instructions="Use for company policies and procedures"
        ),
        WorkflowTool(
            enabled=True,
            workflow={
                "id": "report_generator_id",
                "name": "Report Generator",
                "description": "Generate formatted reports"
            }
        ),
        NoxusQaTool(
            enabled=True,
            extra_instructions="Help with Noxus platform questions"
        )
    ],
    extra_instructions="""You are a versatile AI assistant with multiple tools:
    - Use web research for current information
    - Check company knowledge base for internal information
    - Use workflows for complex data processing
    - Help with Noxus platform questions
    - Choose the most appropriate tool for each request"""
)

versatile_assistant = client.conversations.create(
    name="Versatile Assistant",
    settings=multi_tool_settings
)

Conversation with Agent

Create conversations that use pre-configured agents:

# First, get an existing agent
agent = client.agents.get("agent_id_here")

# Create conversation using the agent's settings
agent_conversation = client.conversations.create(
    name="Chat with Agent",
    agent_id=agent.id  # Uses agent's settings automatically
)

# No need to specify settings - they come from the agent
print(f"Created conversation with agent: {agent.name}")

Asynchronous Creation

For high-performance applications:

import asyncio

async def create_multiple_conversations():
    client = Client(api_key="your_api_key_here")

    # Define different conversation types
    conversation_configs = [
        {
            "name": "Support Bot",
            "settings": ConversationSettings(
                model=["gpt-4o-mini"],
                temperature=0.3,
                tools=[KnowledgeBaseQaTool(enabled=True, kb_id="support_kb")]
            )
        },
        {
            "name": "Content Creator",
            "settings": ConversationSettings(
                model=["gpt-4o"],
                temperature=0.7,
                tools=[WebResearchTool(enabled=True)]
            )
        },
        {
            "name": "Data Analyst",
            "settings": ConversationSettings(
                model=["gpt-4o"],
                temperature=0.4,
                tools=[WorkflowTool(
                    enabled=True,
                    workflow={"id": "analysis_workflow", "name": "Analyzer"}
                )]
            )
        }
    ]

    # Create all conversations concurrently
    tasks = [
        client.conversations.acreate(
            name=config["name"],
            settings=config["settings"]
        )
        for config in conversation_configs
    ]

    conversations = await asyncio.gather(*tasks)

    return conversations

# Create conversations asynchronously
conversations = asyncio.run(create_multiple_conversations())
for conv in conversations:
    print(f"Created: {conv.name} (ID: {conv.id})")

Validation and Testing

Validate Settings

def validate_conversation_settings(settings):
    """Validate conversation settings before creation"""

    # Check required fields
    if not settings.model:
        raise ValueError("Model is required")

    # Validate temperature range
    if not 0.0 <= settings.temperature <= 1.0:
        raise ValueError("Temperature must be between 0.0 and 1.0")

    # Validate max_tokens
    if settings.max_tokens <= 0:
        raise ValueError("max_tokens must be positive")

    # Check tool configuration
    for tool in settings.tools:
        if hasattr(tool, 'kb_id') and not tool.kb_id:
            raise ValueError("Knowledge base tool requires kb_id")

    return True

# Use validation
try:
    validate_conversation_settings(settings)
    conversation = client.conversations.create(name="Test", settings=settings)
except ValueError as e:
    print(f"Invalid settings: {e}")

Test Conversation

def test_conversation(conversation, test_messages):
    """Test a conversation with sample messages"""

    results = []

    for message_text in test_messages:
        try:
            message = MessageRequest(content=message_text)
            response = conversation.add_message(message)

            results.append({
                "input": message_text,
                "output": response.message_parts,
                "success": True
            })

        except Exception as e:
            results.append({
                "input": message_text,
                "output": str(e),
                "success": False
            })

    return results

# Test the conversation
test_messages = [
    "Hello, how can you help me?",
    "What's the weather like today?",
    "Can you help me write a blog post?"
]

test_results = test_conversation(support_bot, test_messages)
for result in test_results:
    status = "✅" if result["success"] else "❌"
    print(f"{status} {result['input'][:30]}... -> {result['output'][:50]}...")

Best Practices

Naming Conventions

Use descriptive names for conversations:

# ✅ Good - descriptive and purposeful
conversation = client.conversations.create(
    name="Customer Support - Product Questions",
    settings=settings
)

# ❌ Bad - generic and unclear
conversation = client.conversations.create(
    name="Bot 1",
    settings=settings
)

Settings Organization

Create reusable settings configurations:

# Define common settings
SUPPORT_SETTINGS = ConversationSettings(
    model=["gpt-4o-mini"],
    temperature=0.3,
    max_tokens=400,
    extra_instructions="Be helpful and empathetic"
)

CREATIVE_SETTINGS = ConversationSettings(
    model=["gpt-4o"],
    temperature=0.8,
    max_tokens=800,
    extra_instructions="Be creative and engaging"
)

# Use predefined settings
support_bot = client.conversations.create(
    name="Support Bot",
    settings=SUPPORT_SETTINGS
)

Tool Selection

Only enable tools that are needed:

# ✅ Good - specific tools for specific purposes
support_tools = [
    KnowledgeBaseQaTool(enabled=True, kb_id="support_kb")
]

research_tools = [
    WebResearchTool(enabled=True),
    KnowledgeBaseQaTool(enabled=True, kb_id="research_kb")
]

# ❌ Bad - too many tools without clear purpose
all_tools = [web_tool, kb_tool1, kb_tool2, workflow_tool, noxus_tool]

Next Steps

Messaging

Learn how to send messages and handle responses

Tools

Explore all available conversation tools in detail

Examples

See complete conversation implementations

API Reference

Detailed API reference for conversation settings

Overview

Getting Started

MCP Server

Concepts

Conversations

Workflows

Resources

Guides

API Reference

Basic Conversation Creation

Configuration Options

Model Selection

Temperature and Creativity

Token Limits

Adding Tools

Web Research Tool

Knowledge Base Integration

Workflow Integration

Specialized Conversation Types

Customer Support Bot

Content Creation Assistant

Technical Documentation Bot

Advanced Configuration

Multi-Tool Conversations

Conversation with Agent

Asynchronous Creation

Validation and Testing

Validate Settings

Test Conversation

Best Practices

Next Steps

Messaging

Tools

Examples

API Reference

​Basic Conversation Creation

​Configuration Options

​Model Selection

​Temperature and Creativity

​Token Limits

​Adding Tools

​Web Research Tool

​Knowledge Base Integration

​Workflow Integration

​Specialized Conversation Types

​Customer Support Bot

​Content Creation Assistant

​Technical Documentation Bot

​Advanced Configuration

​Multi-Tool Conversations

​Conversation with Agent

​Asynchronous Creation

​Validation and Testing

​Validate Settings

​Test Conversation

​Best Practices

​Next Steps

Messaging

Tools

Examples

API Reference

Basic Conversation Creation

Configuration Options

Model Selection

Temperature and Creativity

Token Limits

Adding Tools

Web Research Tool

Knowledge Base Integration

Workflow Integration

Specialized Conversation Types

Customer Support Bot

Content Creation Assistant

Technical Documentation Bot

Advanced Configuration

Multi-Tool Conversations

Conversation with Agent

Asynchronous Creation

Validation and Testing

Validate Settings

Test Conversation

Best Practices

Next Steps