Documentation

API Reference

Chat API

Endpoints for sending messages to agents, managing conversations, and processing AI responses with tool execution.

Message Flow

When a user sends a message, the following flow executes:

  1. Save user message — Stored in the conversation history
  2. Load context — Last 20 messages retrieved for context
  3. Prepare tools — Agent's tools are registered with Gemini as function declarations
  4. LLM call — User message + context sent to gemini-3-flash-preview
  5. Tool loop — If the LLM requests tool calls:
    • Execute each tool with validated arguments
    • Send results back to the LLM
    • Repeat until final text response
  6. Save & return — Assistant response saved and returned with tool call metadata

Tool Registry

The chat system uses a getToolRegistry() function that instantiates all 17 SDK tools at runtime. Each tool is converted from its Zod parameter schema to a Gemini FunctionDeclaration format via toolToGeminiFunction().

Only tools listed in the agent's config.tools array are made available for that conversation.

chat.sendMessage

protectedProcedure · mutation

Send a message to an agent and receive an AI-generated response.

Input

FieldTypeReqDescription
agentIdstring✓Agent UUID
messagestring✓User message text (max 10,000 chars)
conversationIdstring?—Existing conversation ID (omit to create new)

Response

TypeScript
{
  conversationId: "conv-uuid",
  message: {
    id: "msg-uuid",
    role: "assistant",
    content: "Here's the analysis you requested...",
    toolCalls: [
      {
        name: "csv_parse",
        args: { csvData: "..." },
        result: { headers: [...], rows: [...] },
        durationMs: 45
      },
      {
        name: "statistics",
        args: { data: [...] },
        result: { mean: 50000, median: 45000, ... },
        durationMs: 12
      }
    ],
    createdAt: "2024-01-15T10:30:00Z"
  }
}

chat.getConversation

protectedProcedure · query

Get a conversation with all its messages.

Input

TypeScript
{ conversationId: string }

Returns

Conversation object with agent info, all messages (with tool calls), and timestamps.

chat.getConversations

protectedProcedure · query

List all conversations for the authenticated user.

Input

TypeScript
{ agentId?: string, limit?: number, offset?: number }

Optionally filter by agent. Returns conversation summaries with last message preview.

chat.deleteConversation

protectedProcedure · mutation

Delete a conversation and all its messages. Only the conversation owner can delete.

Input

TypeScript
{ conversationId: string }

Related