Standard Operating Procedures

• Multi-agent management with user-scoped access
• Tool execution system with 16+ built-in tools (including video & speech)
• Video generation: text_to_video, image_to_video, combine_video_audio
• Text-to-speech (AWS Polly, synchronous) for narration and demo videos
• Conversation context passed to tools—previous conversation and current query used to fill tool parameters (e.g. text_prompt, url)
• MCP (Model Context Protocol) server integration
• RAG-based knowledge retrieval from training data
• Conversation memory and context management (streaming and non-streaming)
• API key authentication (user-level and agent-level)
• REST API credit deduction: /api/v1/chat and /api/v1/query bill the agent owner per api_call
• Real-time agent testing and monitoring
• Immediate conversation_id return for context preservation
• UTF8MB4 database support for emoji and special characters
• URL resolver normalizes URLs (adds https:// when scheme is missing)
• Social platform integration (social.oshaani.com)
• Footer social links configurable in Django Admin (Social Links model)
• Public share URLs for published agents
• Email-based agent sharing with expiration
• Welcome email system for new users
• Tutorial button on chat page; video tutorial on intro page
• Pay-As-You-Go credits model with free credits for new users

1. Navigate to your agent's training page: /dashboard/{agent_id}/train/
2. Scroll to the "Tools Configuration" section
3. You'll see three categories:
   • Default Tools - Built-in system tools
   • Custom Tools - Your custom HTTP-based tools
   • MCP Tools - Tools from connected MCP servers
4. Toggle tools on/off using the checkboxes
5. Click "Save Tool Configuration" to apply changes

PATCH /api/agents/{agent_id}/
Authorization: Bearer YOUR_USER_TOKEN
Content-Type: application/json

{
  "configuration": {
    "enabled_tools": ["web_search", "url_resolver", "code_executor"],
    "disabled_tools": []
  }
}

PATCH /api/agents/{agent_id}/
Authorization: Bearer YOUR_USER_TOKEN
Content-Type: application/json

{
  "configuration": {
    "disabled_tools": ["text_to_image", "transcription"]
  }
}

{
  "configuration": {
    "use_rag": true,
    "rag_top_k": 5,
    "rag_threshold": 0.7
  }
}

• use_rag: Enable/disable RAG feature
• rag_top_k: Number of relevant chunks to retrieve (default: 5)
• rag_threshold: Similarity threshold for retrieval (default: 0.7)

{
  "configuration": {
    "tools_enabled": true,
    "max_tool_iterations": 10
  }
}

• tools_enabled: Enable/disable tool calling capability
• max_tool_iterations: Maximum tool call iterations (default: 10)

{
  "configuration": {
    "use_memory": true,
    "max_history_messages": 50
  }
}

• use_memory: Enable conversation memory
• max_history_messages: Maximum messages to keep in context

• Via Dashboard: Go to agent training page → Tools Configuration section
• Via API: GET /api/agents/{agent_id}/ → Check configuration.enabled_tools and configuration.disabled_tools

• GET /api/agents/ - List all user's agents
• POST /api/agents/ - Create new agent
• GET /api/agents/{id}/ - Get agent details
• PATCH /api/agents/{id}/ - Update agent
• DELETE /api/agents/{id}/ - Delete agent
• POST /api/agents/{id}/publish/ - Publish agent
• POST /api/agents/{id}/unpublish/ - Unpublish agent

• POST /api/agents/{id}/chat/ - Chat with agent
• POST /api/agents/{id}/query/ - Query agent
• POST /api/agents/{id}/invoke/ - Invoke agent action
• GET /api/agents/{id}/status/ - Get agent status
• GET /api/agents/{id}/history/ - Get interaction history

POST /api/agents/
Authorization: Bearer YOUR_USER_API_KEY
Content-Type: application/json

{
  "name": "Customer Support Bot",
  "description": "Helps customers with common questions",
  "model_id": 1,
  "agent_type": "quick_bot",
  "configuration": {
    "system_prompt": "You are a helpful customer support assistant.",
    "enabled_tools": ["web_search", "url_resolver"],
    "use_rag": true
  }
}

POST /api/agents/{agent_id}/chat/
Authorization: ApiKey YOUR_AGENT_API_KEY
Content-Type: application/json

{
  "message": "What is the weather today?",
  "conversation_id": "optional-conversation-id"
}

{
  "response": "I'll search for today's weather information...",
  "tool_calls": [
    {
      "tool_name": "web_search",
      "parameters": {"query": "weather today"},
      "result": "..."
    }
  ],
  "conversation_id": "conv-123",
  "iterations": 2
}

• POST /api/v1/chat - Simple chat endpoint
• POST /api/v1/query - Simple query endpoint
• GET /api/v1/agents - List accessible agents
• GET /api/v1/agents/{id} - Get agent info

POST /api/v1/chat
Authorization: ApiKey YOUR_AGENT_API_KEY
Content-Type: application/json

{
  "message": "Hello, how can you help me?"
}

{
  "response": "Hello! I can help you with...",
  "tool_calls": [],
  "iterations": 1,
  "conversation_id": "conv-abc123"
}

• POST /api/create_conversation - Create new conversation
• POST /api/continue_conversation - Continue existing conversation
• POST /api/webhook/agent/ - Agent webhook (API key; each call starts a new conversation)
• GET /api/get_answer - Get answer by request_id
• POST /api/find_conversation - Find conversation details
• PUT /api/upload_file - Upload files
• GET /api/download_file - Download files
• POST /api/create_upload_url - Create upload URL
• POST /api/get_download_url - Get download URL

POST /api/create_conversation
Authorization: ApiKey YOUR_AGENT_API_KEY
Content-Type: application/json

{
  "message": "What is machine learning?"
}

{
  "request_id": "req-550e8400-e29b-41d4-a716",
  "conversation_id": "conv-550e8400-e29b-41d4-a716",
  "status": "pending",
  "message": "Request queued for processing. Use /api/get_answer with request_id to get results. Use conversation_id to continue the conversation."
}

GET /api/get_answer?request_id=req-550e8400-e29b-41d4-a716
Authorization: ApiKey YOUR_AGENT_API_KEY

POST /api/continue_conversation
Authorization: ApiKey YOUR_AGENT_API_KEY
Content-Type: application/json

{
  "conversation_id": "conv-550e8400-e29b-41d4-a716",
  "message": "Tell me more about that"
}

Authorization: ApiKey YOUR_AGENT_API_KEY

Alternative header:

X-API-Key: YOUR_AGENT_API_KEY

• The agent must be published. Unpublished agents cannot be reached with an agent API key.
• Every successful POST starts a new conversation. Webhook calls do not continue each other. To send a follow-up in the same thread, use POST /api/continue_conversation with the conversation_id returned in the webhook response.

• At least one of message, text, or payload is required.
• message or text: optional natural-language instruction (either key may be used).
• payload: optional JSON object. It is appended to the composed user message under a [Webhook payload] section so tools and retrieval see structured caller data.
• metadata: optional JSON object. It is not sent to the model; it is echoed back in the HTTP 202 response so you can correlate upstream ids (CRM id, trace id, etc.).

POST /api/webhook/agent/
Authorization: ApiKey YOUR_AGENT_API_KEY
Content-Type: application/json

{
  "message": "Summarize this inbound event for the team.",
  "payload": {
    "event": "ticket.created",
    "ticket_id": "TKT-4412",
    "priority": "high"
  },
  "metadata": {
    "trace_id": "run-2026-04-27-001",
    "source": "zendesk"
  }
}

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "conversation_id": "660e8400-e29b-41d4-a716-446655440001",
  "agent_id": 123,
  "status": "pending",
  "metadata": {
    "trace_id": "run-2026-04-27-001",
    "source": "zendesk"
  },
  "message": "Queued. Poll GET /api/get_answer with request_id for the result."
}

GET /api/get_answer?request_id=550e8400-e29b-41d4-a716-446655440000
Authorization: ApiKey YOUR_AGENT_API_KEY

• GET /api/mcp-servers/ - List MCP servers
• POST /api/mcp-servers/ - Create MCP server
• GET /api/mcp-servers/{id}/ - Get server details
• PUT /api/mcp-servers/{id}/ - Update server
• DELETE /api/mcp-servers/{id}/ - Delete server
• POST /api/mcp-servers/{id}/test_connection/ - Test connection
• GET /api/mcp-servers/list_tools/?agent_id={id} - List available tools

POST /api/mcp-servers/
Authorization: Bearer YOUR_USER_API_KEY
Content-Type: application/json

{
  "agent": 1,
  "name": "filesystem",
  "description": "Local filesystem access",
  "transport_type": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
  "auto_connect": true
}

Authorization: Bearer YOUR_USER_API_KEY

Authorization: ApiKey YOUR_AGENT_API_KEY

X-API-Key: YOUR_AGENT_API_KEY

{
  "request_id": "req-550e8400-e29b-41d4-a716",
  "conversation_id": "conv-550e8400-e29b-41d4-a716",
  "status": "pending",
  "message": "Request queued for processing. Use /api/get_answer with request_id to get results. Use conversation_id to continue the conversation."
}

Note: The conversation_id is now returned immediately when creating a conversation, allowing you to maintain chat context across multiple API calls.

import requests

# Configuration
BASE_URL = "https://your-domain.com/api"
AGENT_API_KEY = "your-agent-api-key"

# Chat with agent
response = requests.post(
    f"{BASE_URL}/v1/chat",
    headers={
        "Authorization": f"ApiKey {AGENT_API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "message": "What is artificial intelligence?"
    }
)

result = response.json()
print(f"Response: {result['response']}")
print(f"Tool calls: {result.get('tool_calls', [])}")

const API_KEY = "your-agent-api-key";
const BASE_URL = "https://your-domain.com/api";

// Create conversation (async)
const createResponse = await fetch(`${BASE_URL}/create_conversation`, {
  method: 'POST',
  headers: {
    'Authorization': `ApiKey ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: "Hello, agent!"
  })
});

const { request_id, conversation_id } = await createResponse.json();

// Store conversation_id for maintaining context
console.log('Conversation ID:', conversation_id);

// Poll for results
const pollAnswer = async () => {
  const response = await fetch(
    `${BASE_URL}/get_answer?request_id=${request_id}`,
    {
      headers: { 'Authorization': `ApiKey ${API_KEY}` }
    }
  );
  return response.json();
};

// Poll until completed
let result = await pollAnswer();
while (result.status === 'pending' || result.status === 'processing') {
  await new Promise(resolve => setTimeout(resolve, 1000));
  result = await pollAnswer();
}

console.log('Final response:', result.response);

// Continue the conversation using conversation_id
const continueResponse = await fetch(`${BASE_URL}/continue_conversation`, {
  method: 'POST',
  headers: {
    'Authorization': `ApiKey ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    conversation_id: conversation_id,
    message: "Tell me more about that"
  })
});

const continueResult = await continueResponse.json();
console.log('Continued conversation response:', continueResult);

curl -X POST https://your-domain.com/api/agents/1/chat/ \
  -H "Authorization: ApiKey YOUR_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

curl -X POST https://your-domain.com/api/v1/chat \
  -H "Authorization: ApiKey YOUR_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

curl -X GET https://your-domain.com/api/mcp-servers/list_tools/?agent_id=1 \
  -H "Authorization: Bearer YOUR_USER_API_KEY"

• request_id - Used to poll for the initial response via /api/get_answer
• conversation_id - Returned immediately, used to continue the conversation via /api/continue_conversation

The conversation_id is available immediately, allowing you to start a new conversation thread while the initial request is still being processed asynchronously.

• Redis server (message broker)
• Celery worker process
• Django application server

• Automatic Chunking: Training data is automatically chunked into smaller pieces
• Embedding Generation: Uses AWS Bedrock Titan Embeddings or Ollama embeddings
• Semantic Search: Retrieves only relevant chunks based on query similarity
• Vector Store Backends: Supports both in-memory and Qdrant vector databases

{
  "agent": 1,
  "name": "filesystem",
  "description": "Local filesystem access",
  "transport_type": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
  "auto_connect": true
}

• Agent - Agent configuration and status
• Conversation - Conversation threads
• ConversationMessage - Individual messages
• AgentRequest - Async request tracking
• ConversationFile - Uploaded/generated files
• TrainingData - Agent training data
• MCPServer - MCP server configurations
• ToolCall - Tool execution tracking

• JIRA - Atlassian JIRA Cloud (OAuth 2.0 3LO)
• Confluence - Atlassian Confluence (OAuth 2.0 3LO)
• GitLab - GitLab repositories (OAuth 2.0)
• GitHub - GitHub repositories (OAuth 2.0)
• Google - Google Workspace (Drive, Docs, Sheets, Gmail) (OAuth 2.0)
• Microsoft - Microsoft 365 (OneDrive, SharePoint, Outlook, Teams) (OAuth 2.0)
• Slack - Slack workspace (OAuth 2.0) - Coming soon

• Replace {connector_id} with the actual connector ID after creating the connector
• The callback URL is provided in the API response when creating a connector
• The URL must match EXACTLY (including protocol, domain, path, and trailing slash)

• https://example.com/api/connectors/1/oauth/callback/ (JIRA connector #1)
• https://example.com/api/connectors/2/oauth/callback/ (GitHub connector #2)
• https://example.com/api/connectors/3/oauth/callback/ (Google connector #3)
• https://example.com/api/connectors/4/oauth/callback/ (Microsoft connector #4)

• Create Connector: POST /api/connectors/ (returns callback_url)
• Initiate OAuth: POST /api/connectors/{connector_id}/oauth/initiate/ (returns callback_url)
• OAuth Callback: GET /api/connectors/{connector_id}/oauth/callback/ (handled automatically)

1. Navigate to your published agent's detail page
2. Click "Share Agent (Email)" button
3. Enter recipient's email address
4. Optionally add a message and set expiration
5. An email with a unique share link is sent to the recipient
6. Recipient clicks the link and accepts the share
7. They can now access and use your agent

• email - Recipient's email address (required)
• message - Optional message to include
• expires_days - Optional expiration in days

• Resend Email: Resend share invitation email
• Withdraw Share: Remove pending invitations
• Revoke Access: Remove access from accepted shares

1. Navigate to your published agent's detail page
2. Click "Public Share URL" button
3. Optionally set expiration date
4. Copy the generated share URL
5. Share the URL with anyone (via email, social media, website, etc.)
6. Anyone with the URL can access your agent (after login/registration)

1. Go to agent detail page: /dashboard/{agent_id}/
2. Click "Public Share URL" button
3. Set optional expiration (in days)
4. Click "Generate Share URL"
5. Copy the generated URL

{
  "expires_days": 30  // Optional: expiration in days
}

• Unique token for each share
• Accessible by anyone with the URL
• Requires user login/registration to use
• Automatically redirects to agent chat after authentication

• Active public share URL is displayed on agent detail page
• Shows access count and last accessed time
• Shows expiration date if set

• Click "Deactivate" button on agent detail page
• Or use API: POST /dashboard/{agent_id}/public-share/deactivate/
• Deactivated URLs no longer grant access

POST /dashboard/{agent_id}/public-share/
Authorization: Session or User API Key
Content-Type: application/json

{
  "expires_days": 30
}

{
  "success": true,
  "share_url": "https://your-domain.com/dashboard/public/{token}/",
  "expires_at": "2024-02-15T00:00:00Z"
}

• Free Tier: Basic features with daily limits
• Starter: Increased limits for individuals
• Professional: Advanced features for teams
• Enterprise: Unlimited features for organizations
• Pay-As-You-Go: Flexible usage-based pricing with no monthly commitment

• Message (chat): 3 credits per message
• API call (REST): 0.08 credits per /api/v1/chat or /api/v1/query call (agent owner is billed)
• Tool call: 0.15 credits per tool execution
• Storage: 0.002 credits per MB
• Agent creation: 1.5 credits per agent
• Video generation: 30–75 credits depending on duration and model (text_to_video, image_to_video)

Free credits: New users receive free credits (configurable via FREE_CREDITS_AMOUNT, e.g. 200) on first login. Credits are drawn from the platform Credit Ledger.

REST API: When external clients call /api/v1/chat or /api/v1/query with an agent API key, the agent owner is charged per api_call; insufficient credits return 402.

• Messages: Chat messages sent to agents
• Tool Calls: Tools executed by agents
• API Calls: API requests made
• Storage: File storage used (in MB)
• Agent Creations: Number of agents created

• Click "Analytics" in the header navigation
• View real-time usage statistics
• See usage by metric type
• Monitor remaining limits
• Track usage trends

1. Navigate to Credits section in header
2. View current credit balance
3. Purchase additional credits
4. Monitor credit usage
5. Set up auto-recharge (coming soon)

Oshaani Social (social.oshaani.com) is a dedicated social platform where users can:

• Share AI Agents: Publish your created agents and showcase them to the community
• Discover Agents: Browse and discover innovative AI agents created by others
• Build Communities: Connect with other developers and AI enthusiasts
• Collaborate: Work together on AI projects and share knowledge
• Get Feedback: Receive community feedback on your AI creations
• Learn: Access tutorials, best practices, and use cases

• Complete toolchain from creation to deployment to sharing
• Community support and knowledge sharing
• Access to pre-built agents and templates
• Learning resources and best practices

• Professional AI agent creation platform
• Scalable deployment options
• Enterprise-grade security and reliability
• Integration with existing tools and workflows

• Showcase your AI creations
• Build a following and reputation
• Monetization opportunities (coming soon)
• Collaboration with other creators

• Developer Tools: Advanced APIs, SDKs, and developer resources
• Marketplace: Buy and sell AI agents and templates
• Analytics Dashboard: Enhanced analytics across platforms
• Mobile Apps: iOS and Android applications
• Enterprise Features: Advanced security, SSO, and team management
• Auto-Recharge: Automatic credit top-up when balance is low
• Team Sharing: Share agents with entire teams or organizations

• Contact Form: General inquiry form for questions and support requests
• Demo Booking: Dedicated form for scheduling personalized product demos
• Email Notifications: All submissions are sent to support@oshaani.com
• Form Validation: Client-side and server-side validation for data integrity
• Responsive Design: Mobile-friendly modal interface
• Success Feedback: Visual confirmation after successful submission

• Recipient: support@oshaani.com (configurable via CONTACT_FORM_EMAIL setting)
• Sender: support@oshaani.com (from DEFAULT_FROM_EMAIL setting)
• Email Backend: SMTP with AWS SES fallback
• Email Format: HTML with plain text fallback

• Subject: "Demo Request from [Name]" or "Contact Form Submission from [Name]"
• Format: HTML email with styled template
• Content: All form fields formatted in a professional layout
• Footer: Includes source information (Oshaani website contact form)

• CONTACT_FORM_EMAIL: Recipient email (default: support@oshaani.com)
• DEFAULT_FROM_EMAIL: Sender email (default: support@oshaani.com)
• EMAIL_HOST: SMTP server hostname
• EMAIL_PORT: SMTP server port
• EMAIL_HOST_USER: SMTP username
• EMAIL_HOST_PASSWORD: SMTP password
• AWS_ROLE_ARN: AWS role for SES fallback (optional)