Agentic Chat API (Zarna AI)

Natural language interface to your CRM data with multi-agent AI system

Overview

The Agentic Chat API, powering Zarna AI (the intelligent chatbot), provides a natural language interface to query and interact with your CRM data using a multi-agent AI system with persistent agent pools for optimal performance.

Base Path: /agentic-chat

Key Features

• Natural Language Queries: Ask questions in plain English
• Multi-Agent System: Specialized agents for different tasks
• Agent Pool: Pre-warmed agents eliminate 5-11s cold start
• Real-time Streaming: Server-Sent Events for live responses
• Context Awareness: Maintains conversation history

Endpoints

Query (Streaming)

Execute a natural language query against your CRM data.

POST /agentic-chat/query

Request Body:

{
  "company_id": "550e8400-e29b-41d4-a716-446655440000",
  "query": "How many active deals do we have in the pipeline?",
  "chat_id": "bb0e8400-e29b-41d4-a716-446655440666",
  "pool_options": {
    "prefer_warm": true,
    "max_wait_time": 120
  }
}

Parameters:

Field	Type	Required	Description
company_id	UUID	No	Context company (optional)
query	string	Yes	Natural language query
chat_id	UUID	Yes	Conversation ID for context
pool_options	object	No	Pool configuration

Example Request:

curl -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "query": "Show me all companies in the technology sector",
    "chat_id": "bb0e8400-e29b-41d4-a716-446655440666"
  }' \
  "http://localhost:8000/agentic-chat/query"

Response (Server-Sent Events):

data: {"type": "start", "query_id": "cc0e8400-e29b-41d4-a716-446655440777", "timestamp": "2024-01-22T10:30:00Z"}

data: {"type": "agent_start", "agent": "data_retrieval", "task": "Querying companies table"}

data: {"type": "chunk", "content": "I found 42 companies in the technology sector. Here's the breakdown:\n\n"}

data: {"type": "chunk", "content": "**Top Companies by Revenue:**\n1. Acme Corp - $15M\n2. TechStart Inc - $5M\n"}

data: {"type": "data", "companies": [{"id": "...", "name": "Acme Corp", "revenue": 15000000}]}

data: {"type": "agent_complete", "agent": "data_retrieval", "duration": 2.3}

data: {"type": "complete", "query_id": "cc0e8400-e29b-41d4-a716-446655440777", "total_time": 3.8}

System Health

Check agent pool system health.

GET /agentic-chat/pools/health

Response:

{
  "total_pools": 5,
  "healthy_pools": 5,
  "degraded_pools": 0,
  "failed_pools": 0,
  "active_queries": 3,
  "total_queries_processed": 1247,
  "avg_response_time_seconds": 3.2,
  "uptime_hours": 48.5
}

Pool Status

Get status for a specific firm’s agent pool.

GET /agentic-chat/pools/{firm_id}/status

Response:

{
  "firm_id": "770e8400-e29b-41d4-a716-446655440222",
  "status": "healthy",
  "warm_agents": 3,
  "queued_requests": 1,
  "active_requests": 2,
  "total_processed": 156,
  "avg_response_time": 3.5,
  "last_activity": "2024-01-22T10:29:45Z",
  "created_at": "2024-01-20T08:00:00Z"
}

Status Values:

• healthy: Operating normally
• degraded: Some agents unavailable
• failed: Pool not operational
• initializing: Starting up

Restart Pool

Manually restart a firm’s agent pool.

POST /agentic-chat/pools/{firm_id}/restart

Response:

{
  "message": "Pool restarted successfully",
  "firm_id": "770e8400-e29b-41d4-a716-446655440222",
  "status": "initializing"
}

Performance Metrics

Get aggregated performance metrics.

GET /agentic-chat/metrics

Response:

{
  "queries": {
    "total": 1247,
    "successful": 1198,
    "failed": 49,
    "success_rate": 0.961
  },
  "performance": {
    "avg_response_time": 3.2,
    "p50_response_time": 2.8,
    "p95_response_time": 5.1,
    "p99_response_time": 8.3
  },
  "pools": {
    "total": 5,
    "healthy": 5,
    "avg_pool_size": 2.8
  },
  "period": {
    "start": "2024-01-20T08:00:00Z",
    "end": "2024-01-22T10:30:00Z"
  }
}

Event Types

Streaming Events

Event	Description	Data Fields
start	Query processing started	query_id, timestamp
agent_start	Agent begins task	agent, task
chunk	Content chunk	content
data	Structured data	varies by query
agent_complete	Agent finishes	agent, duration
complete	Query complete	query_id, total_time
error	Error occurred	message, error_code

Frontend Integration

React Hook for Streaming

import { useState, useCallback } from 'react'

export function useAgenticChat() {
  const [messages, setMessages] = useState<Message[]>([])
  const [isStreaming, setIsStreaming] = useState(false)

  const sendQuery = useCallback(async (query: string, chatId: string) => {
    setIsStreaming(true)

    const response = await fetch('http://localhost:8000/agentic-chat/query', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
        'Accept': 'text/event-stream'
      },
      body: JSON.stringify({
        query,
        chat_id: chatId
      })
    })

    const reader = response.body!.getReader()
    const decoder = new TextDecoder()
    let currentMessage = ''

    while (true) {
      const { done, value } = await reader.read()
      if (done) break

      const chunk = decoder.decode(value)
      const lines = chunk.split('\n')

      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = JSON.parse(line.slice(6))

          if (data.type === 'chunk') {
            currentMessage += data.content
            setMessages(prev => {
              const newMessages = [...prev]
              if (newMessages.length > 0 && newMessages[newMessages.length - 1].role === 'assistant') {
                newMessages[newMessages.length - 1].content = currentMessage
              } else {
                newMessages.push({ role: 'assistant', content: currentMessage })
              }
              return newMessages
            })
          } else if (data.type === 'complete') {
            setIsStreaming(false)
          }
        }
      }
    }
  }, [])

  return { messages, isStreaming, sendQuery }
}

Python

import requests
import json

def stream_query(query: str, chat_id: str, token: str):
    """
    Stream agentic chat query
    """
    response = requests.post(
        'http://localhost:8000/agentic-chat/query',
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json',
            'Accept': 'text/event-stream'
        },
        json={
            'query': query,
            'chat_id': chat_id
        },
        stream=True
    )

    for line in response.iter_lines():
        if line:
            line = line.decode('utf-8')
            if line.startswith('data: '):
                data = json.loads(line[6:])

                if data['type'] == 'chunk':
                    print(data['content'], end='', flush=True)
                elif data['type'] == 'complete':
                    print(f"\n\nQuery completed in {data['total_time']}s")

Example Queries

Data Retrieval

"Show me all companies in healthcare with revenue over $10M"
"List active deals in the pipeline stage"
"Find contacts at Acme Corp who are executives"

Analytics

"What's the average deal size for Q4 2024?"
"Calculate revenue growth year-over-year"
"Show me conversion rates by deal stage"

Operations

"Create a new company called NewCo in the software industry"
"Update the status of Deal X to closed-won"
"Add a note to the Acme Corp account"

Complex Queries

"Compare the top 5 companies by revenue and show their deal pipeline"
"Analyze our fastest-closing deals and identify common patterns"
"Generate a summary of all interactions with tech companies this month"

Performance

With Agent Pool

• First query (cold firm): ~7-8 seconds
• Subsequent queries (warm pool): ~3-4 seconds
• Peak throughput: ~10 queries/second
• Concurrent users: Supports 100+ simultaneous users

Without Agent Pool (Legacy)

• Every query: ~12-15 seconds (5-11s cold start + 7s execution)

Agent Pool Architecture

Learn about performance optimization

Error Handling

Code	Error	Description
400	invalid_query	Query cannot be understood
401	unauthorized	Authentication required
404	chat_not_found	Chat ID doesn’t exist
422	query_failed	Query execution error
429	rate_limit_exceeded	Too many requests
503	pool_unavailable	Agent pool not ready

Error Response:

{
  "detail": "Failed to execute query",
  "error_code": "query_failed",
  "message": "Could not find company with that name"
}

Next Steps

Agent Pool System

Performance optimization architecture

Agentic System

Multi-agent orchestration

Backend Service

Service implementation details

CRM Agent

CRM-specific agent capabilities