Agentic Chat API (Zarna AI)

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

Overview

CRM

File Management

Communication

AI & Analytics

Management

Overview

Key Features

Endpoints

Query (Streaming)

System Health

Pool Status

Restart Pool

Performance Metrics

Event Types

Streaming Events

Frontend Integration

React Hook for Streaming

Python

Example Queries

Data Retrieval

Analytics

Operations

Complex Queries

Performance

With Agent Pool

Without Agent Pool (Legacy)

Agent Pool Architecture

Error Handling

Next Steps

Agent Pool System

Agentic System

Backend Service

CRM Agent

Overview

CRM

File Management

Communication

AI & Analytics

Management

​Overview

​Key Features

​Endpoints

​Query (Streaming)

​System Health

​Pool Status

​Restart Pool

​Performance Metrics

​Event Types

​Streaming Events

​Frontend Integration

​React Hook for Streaming

​Python

​Example Queries

​Data Retrieval

​Analytics

​Operations

​Complex Queries

​Performance

​With Agent Pool

​Without Agent Pool (Legacy)

Agent Pool Architecture

​Error Handling

​Next Steps

Agent Pool System

Agentic System

Backend Service

CRM Agent

Overview

Key Features

Endpoints

Query (Streaming)

System Health

Pool Status

Restart Pool

Performance Metrics

Event Types

Streaming Events

Frontend Integration

React Hook for Streaming

Python

Example Queries

Data Retrieval

Analytics

Operations

Complex Queries

Performance

With Agent Pool

Without Agent Pool (Legacy)

Error Handling

Next Steps