Guides

Agent700 API Chat Guide

The Agent700 Platform API provides a comprehensive chat completion system that allows you to interact with AI agents through natural language conversations. The chat API supports both streaming and non-streaming responses, multiple AI models, advanced features like MCP tools, PII scrubbing, and smart document evaluation.

Table of Contents

  1. Chat Concepts
  2. Data Models
  3. API Endpoints
  4. Request Parameters
  5. Response Formats
  6. Streaming Responses
  7. Model catalog first
  8. Code Examples
  9. Use Cases and Patterns
  10. Best Practices
  11. Troubleshooting

Chat Concepts

What is the Chat API?

The Chat API enables you to send messages to AI agents and receive intelligent responses. Each chat request can:

  • Use a persisted agent configuration via agentId (required)
  • Maintain conversation history through message arrays
  • Support streaming for real-time responses
  • Integrate with MCP tools for extended capabilities
  • Apply PII scrubbing for privacy protection
  • Use smart document evaluation for context-aware responses

Key Concepts

Agents

Agents are pre-configured AI assistants with specific:

  • Master Prompts: System instructions that define the agent's behavior
  • Model Settings: Default model, temperature, max tokens, etc.
  • Features: PII scrubbing, MCP tools, document evaluation, etc.
  • Revisions: Versioned configurations that can be referenced

Every chat request must include agentId for an agent you can access. Create agents with POST /api/agents first. Optional fields such as model, masterPrompt, and temperature can override the agent revision for that request when you own the agent.

Messages

Messages form the conversation history:

  • System Messages: Instructions that guide the agent's behavior (typically injected from agent configuration)
  • User Messages: Input from the user
  • Assistant Messages: Previous responses from the agent
  • Tool Messages: Results from tool calls (for MCP integration)

Messages are processed in order, maintaining conversation context.

Streaming vs Non-Streaming

  • Non-Streaming: Returns complete response after processing finishes
  • Streaming: Returns response chunks in real-time as they're generated (SSE)

Data Models

ChatRequest Schema

{
  "messages": [
    {
      "id": "message-uuid",
      "role": "user",
      "content": "Hello, how are you?"
    }
  ],
  "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
  "agentRevisionId": 1,
  "streamResponses": true,
  "model": "gpt-4",
  "temperature": 0.7,
  "topP": 1.0,
  "maxTokens": 1000,
  "reasoningEffort": "medium",
  "thinkingEnabled": false,
  "thinkingBudgetTokens": 1000,
  "scrubPii": true,
  "piiThreshold": 0.8,
  "smartDocEvaluation": false,
  "smartDocChunkSize": 1000,
  "smartDocChunkOverlap": 200,
  "smartDocEmbeddingModel": "text-embedding-ada-002",
  "smartDocTopK": 3,
  "fullDocAnalysis": false,
  "fullDocChunkSize": 2000,
  "fullDocChunkOverlap": 400,
  "fullDocMaxLength": 10000,
  "enableMcp": true,
  "mcpServerNames": ["filesystem", "github"],
  "mcpAutoApprove": false,
  "streamingEnabled": false
}

Required Fields:

  • messages (array): At least one message in the conversation
  • agentId (string, UUID): ID of the agent to use (create via POST /api/agents if needed)

Optional Fields:

  • agentRevisionId (integer): Use a specific agent revision instead of the current one
  • masterPrompt (string): Override the agent's system prompt for this request (agent owner only)
  • introductoryText (string): Override the agent's introductory text for this request (agent owner only)
  • streamResponses (boolean): Enable streaming (affects LLM handler behavior)
  • streamingEnabled (boolean): Enable SSE streaming for HTTP endpoint
  • model (string): Override agent's default model
  • temperature (number): Sampling temperature (0-2)
  • topP (number): Nucleus sampling parameter (0-1)
  • maxTokens (integer): Maximum tokens in response
  • reasoningEffort (string): Reasoning mode for supported models
  • thinkingEnabled (boolean): Enable extended thinking mode
  • thinkingBudgetTokens (integer): Token budget for thinking
  • scrubPii (boolean): Enable PII scrubbing
  • piiThreshold (number): PII detection confidence threshold
  • smartDocEvaluation (boolean): Enable smart document evaluation
  • smartDocChunkSize (integer): Chunk size for smart evaluation
  • smartDocChunkOverlap (integer): Overlap between chunks
  • smartDocEmbeddingModel (string): Embedding model name
  • smartDocTopK (integer): Number of top chunks to retrieve
  • fullDocAnalysis (boolean): Enable full document analysis
  • fullDocChunkSize (integer): Chunk size for full analysis
  • fullDocChunkOverlap (integer): Overlap for full analysis
  • fullDocMaxLength (integer): Maximum text length for analysis
  • enableMcp (boolean): Enable MCP tools
  • mcpServerNames (array): List of MCP server names
  • mcpAutoApprove (boolean): Auto-approve MCP tool calls

ChatMessage Schema

{
  "id": "28e2c8b8-c5bd-41df-9641-ccc9d0757e59",
  "role": "user",
  "content": "What is the weather today?"
}

Fields:

  • id (string, UUID, optional): Unique message identifier
  • role (string, required): Message role - "system", "user", "assistant", or "tool"
  • content (string or array, required): Message content - string for text-only, array for multimodal (see Multimodal Messages)

Role Types:

  • system: Instructions for the agent (typically from agent configuration)
  • user: User input messages
  • assistant: Previous agent responses
  • tool: Tool call results (for MCP integration)

Multimodal Messages (Images)

Messages can include images alongside text for vision-capable models. When including images, the content field becomes an array instead of a string.

Supported Models

Images are supported on:

  • OpenAI: gpt-4o, gpt-4o-mini, gpt-4-turbo, o1, o3, gpt-4.1, gpt-5, etc.
  • Claude: claude-3-5-sonnet, claude-3-opus, claude-sonnet-4, claude-opus-4, etc.
  • Gemini: gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash, gemini-2.5-pro, etc.
  • xAI (Grok): grok-2-latest, grok-3-latest, grok-3-fast-latest, etc.
  • Perplexity (Sonar): sonar, sonar-pro, sonar-reasoning-pro, sonar-deep-research (sonar-reasoning is deprecated; use sonar-reasoning-pro)
  • Mistral: pixtral-large-latest, mistral-large-latest, mistral-small-latest

Image Content Format

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "What's in this image?"
    },
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/jpeg",
        "data": "iVBORw0KGgoAAAANSUhEUgAA..."
      }
    }
  ]
}

Image Source Types

Base64 Encoded Image:

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/jpeg",
    "data": "<base64-encoded-image-data>"
  }
}

URL Image:

{
  "type": "image",
  "source": {
    "type": "url",
    "url": "https://example.com/image.jpg"
  }
}

Supported Image Formats

  • image/jpeg / image/jpg
  • image/png
  • image/gif
  • image/webp

Multiple Images

You can include multiple images in a single message:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Compare these two images" },
    {
      "type": "image",
      "source": { "type": "base64", "media_type": "image/jpeg", "data": "..." }
    },
    {
      "type": "image",
      "source": { "type": "base64", "media_type": "image/png", "data": "..." }
    }
  ]
}

Image Code Examples

JavaScript:

// Convert file to base64
async function fileToBase64(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => {
      const dataUrl = reader.result;
      const match = dataUrl.match(/^data:(image\/[^;]+);base64,(.+)$/);
      if (match) {
        resolve({ media_type: match[1], data: match[2] });
      } else {
        reject(new Error('Invalid image format'));
      }
    };
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
}

// Send message with image
async function sendImageMessage(accessToken, agentId, text, imageFile) {
  const { media_type, data } = await fileToBase64(imageFile);
  
  const response = await fetch('https://api.agent700.ai/api/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agentId: agentId,
      messages: [{
        role: 'user',
        content: [
          { type: 'text', text: text },
          {
            type: 'image',
            source: { type: 'base64', media_type, data }
          }
        ]
      }]
    }),
  });
  
  return response.json();
}

Python:

import base64
import requests

def send_image_message(access_token, agent_id, text, image_path):
    # Read and encode image
    with open(image_path, 'rb') as f:
        image_data = base64.b64encode(f.read()).decode('utf-8')
    
    # Determine media type from extension
    ext = image_path.split('.')[-1].lower()
    media_type = f'image/{ext}' if ext != 'jpg' else 'image/jpeg'
    
    response = requests.post(
        'https://api.agent700.ai/api/chat',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={
            'agentId': agent_id,
            'messages': [{
                'role': 'user',
                'content': [
                    {'type': 'text', 'text': text},
                    {
                        'type': 'image',
                        'source': {
                            'type': 'base64',
                            'media_type': media_type,
                            'data': image_data
                        }
                    }
                ]
            }]
        }
    )
    return response.json()

cURL:

curl -X POST https://api.agent700.ai/api/chat \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "BASE64_ENCODED_IMAGE_DATA"
          }
        }
      ]
    }]
  }'

ChatResponse Schema

{
  "error": null,
  "response": "Hello! How can I assist you today?",
  "finish_reason": "stop",
  "scrubbed_message": "",
  "prompt_tokens": 25,
  "completion_tokens": 10
}

Fields:

  • error (string, nullable): Error message if request failed
  • response (string, required): Complete response text
  • finish_reason (string, nullable): Reason for completion - "stop", "length", "content_filter", or "error"
  • scrubbed_message (string, nullable): Information about PII that was scrubbed
  • prompt_tokens (integer, optional): Number of tokens in the prompt
  • completion_tokens (integer, optional): Number of tokens in the completion

Finish Reasons:

  • stop: Model completed normally
  • length: Response was truncated due to token limit
  • content_filter: Content was filtered by safety systems
  • error: An error occurred during processing

API Endpoints

Chat Completion (Non-Streaming)

Send a chat request and receive a complete response.

Endpoint: POST /api/chat

Authentication: Required (JWT Bearer token or App Password)

Payment Required: Yes (agent owner must have active paid subscription)

Request Body: See ChatRequest Schema

Response: 200 OK

{
  "error": null,
  "response": "Hello! How can I assist you today?",
  "finish_reason": "stop",
  "scrubbed_message": ""
}

Error Responses:

  • 400 Bad Request: Invalid request format, missing agentId ("Agent ID is required"), or other validation errors
  • 401 Unauthorized: Missing or invalid authentication token
  • 402 Payment Required: Agent owner doesn't have active paid subscription
  • 500 Internal Server Error: Error processing chat request

Example Request:

curl -X POST https://api.agent700.ai/api/chat \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
    "messages": [
      {
        "role": "user",
        "content": "What is the weather today?"
      }
    ]
  }'

Chat Completion (Streaming)

Send a chat request and receive streaming responses via Server-Sent Events (SSE).

Endpoint: POST /api/chat

Authentication: Required (JWT Bearer token or App Password)

Payment Required: Yes

Request Body: Same as non-streaming, but with streamingEnabled: true

Response: 200 OK (SSE stream)

Headers:

  • Content-Type: text/event-stream
  • Cache-Control: no-cache
  • Connection: keep-alive
  • X-Accel-Buffering: no

SSE Event Format:

event: content
data: {"content": "Hello", "stream_id": "..."}

event: content
data: {"content": "! How", "stream_id": "..."}

event: done
data: {"finish_reason": "stop", "prompt_tokens": 25, "completion_tokens": 10}

event: error
data: {"error": "Error message"}

SSE Events:

  • content: Partial content chunk from the response
  • done: Stream completed successfully
  • error: An error occurred during processing

Example Request:

curl -X POST https://api.agent700.ai/api/chat \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
    "messages": [
      {
        "role": "user",
        "content": "Tell me a story"
      }
    ],
    "streamingEnabled": true
  }'

Fetch URL Metadata

Fetch and sanitize metadata from a URL for link previews.

Endpoint: GET /api/chat/fetch-url-metadata

Authentication: Required (JWT Bearer token or App Password)

Query Parameters:

  • url (string, required): HTTP or HTTPS URL to fetch

Response: 200 OK

{
  "title": "Example Page Title",
  "description": "This is an example page description",
  "image": "https://example.com/image.jpg",
  "url": "https://example.com/page"
}

Error Responses:

  • 400 Bad Request: Invalid URL, SSL failure, or request error
  • 413 Payload Too Large: URL content too large
  • 504 Gateway Timeout: Timeout fetching URL

Example Request:

curl -X GET "https://api.agent700.ai/api/chat/fetch-url-metadata?url=https://example.com" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Request Parameters

Basic Parameters

messages (required)

Array of chat messages forming the conversation history.

{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello!"
    },
    {
      "role": "assistant",
      "content": "Hi there! How can I help you?"
    },
    {
      "role": "user",
      "content": "What is 2+2?"
    }
  ]
}

agentId (required)

UUID of the agent to use. The agent's configuration (master prompt, model settings, etc.) is loaded from the current or specified revision. Requests without agentId return 400 with "Agent ID is required".

{
  "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
  "messages": [...]
}

agentRevisionId (optional)

Specific revision ID of an agent to use. If not provided, the agent's current revision is used.

{
  "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
  "agentRevisionId": 2,
  "messages": [...]
}

masterPrompt (optional, agent owner)

Override the agent revision's system prompt for this request only. Does not update the stored revision unless you use the agents API.

{
  "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
  "masterPrompt": "You are a medical assistant. Follow these instructions:\n\nNo diagnosis\n\nNo prescriptive actions\n\nNo medical advice",
  "messages": [...]
}

introductoryText (optional, agent owner)

Override the agent revision's introductory text for this request only.

{
  "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
  "introductoryText": "Welcome! I'm here to help you with medical questions.",
  "messages": [...]
}

Model Parameters

model (optional)

Override the agent's default model.

{
  "model": "gpt-4",
  "messages": [...]
}

temperature (optional)

Sampling temperature (0-2). Higher values make output more random.

{
  "temperature": 0.7,
  "messages": [...]
}

topP (optional)

Nucleus sampling parameter (0-1). Controls diversity via nucleus sampling.

{
  "topP": 0.9,
  "messages": [...]
}

maxTokens (optional)

Maximum number of tokens in the response.

{
  "maxTokens": 1000,
  "messages": [...]
}

Advanced Model Parameters

reasoningEffort (optional)

Reasoning effort hint for models that support explicit reasoning modes (e.g., "low", "medium", "high").

{
  "reasoningEffort": "medium",
  "messages": [...]
}

thinkingEnabled (optional)

Enable extended "thinking" mode for models that support it.

{
  "thinkingEnabled": true,
  "thinkingBudgetTokens": 1000,
  "messages": [...]
}

thinkingBudgetTokens (optional)

Token budget reserved for thinking when thinkingEnabled is true.

{
  "thinkingEnabled": true,
  "thinkingBudgetTokens": 2000,
  "messages": [...]
}

Privacy and Security Parameters

scrubPii (optional)

Enable PII (Personally Identifiable Information) scrubbing from messages.

{
  "scrubPii": true,
  "piiThreshold": 0.8,
  "messages": [...]
}

piiThreshold (optional)

PII detection confidence threshold (0-1). Higher values are more strict.

{
  "scrubPii": true,
  "piiThreshold": 0.9,
  "messages": [...]
}

Document Evaluation Parameters

smartDocEvaluation (optional)

Enable smart document evaluation using embeddings for alignment data placeholders.

{
  "smartDocEvaluation": true,
  "smartDocChunkSize": 1000,
  "smartDocChunkOverlap": 200,
  "smartDocEmbeddingModel": "text-embedding-ada-002",
  "smartDocTopK": 3,
  "messages": [...]
}

fullDocAnalysis (optional)

Enable full document analysis over alignment data placeholders (does not support streaming).

{
  "fullDocAnalysis": true,
  "fullDocChunkSize": 2000,
  "fullDocChunkOverlap": 400,
  "fullDocMaxLength": 10000,
  "messages": [...]
}

MCP (Model Context Protocol) Parameters

enableMcp (optional)

Enable MCP tools for this request if supported by the model.

{
  "enableMcp": true,
  "mcpServerNames": ["filesystem", "github"],
  "mcpAutoApprove": false,
  "messages": [...]
}

mcpServerNames (optional)

Array of MCP server names that may be used by this agent/request.

{
  "enableMcp": true,
  "mcpServerNames": ["filesystem", "github", "database"],
  "messages": [...]
}

mcpAutoApprove (optional)

Automatically approve MCP tool calls without requiring explicit user confirmation.

{
  "enableMcp": true,
  "mcpAutoApprove": true,
  "messages": [...]
}

Streaming Parameters

streamingEnabled (optional)

Enable SSE streaming for HTTP endpoint. When true, the endpoint returns Server-Sent Events instead of a JSON response.

{
  "streamingEnabled": true,
  "messages": [...]
}

streamResponses (optional)

Per-agent streaming preference. Affects how the underlying LLM handler behaves, but the endpoint controls transport.

{
  "streamResponses": true,
  "messages": [...]
}

Response Formats

Non-Streaming Response

Complete response returned after processing finishes.

{
  "error": null,
  "response": "Hello! How can I assist you today?",
  "finish_reason": "stop",
  "scrubbed_message": "",
  "prompt_tokens": 25,
  "completion_tokens": 10
}

Streaming Response (SSE)

Real-time response chunks via Server-Sent Events.

Content Event:

event: content
data: {"content": "Hello", "stream_id": "abc123"}

Done Event:

event: done
data: {"finish_reason": "stop", "prompt_tokens": 25, "completion_tokens": 10}

Error Event:

event: error
data: {"error": "Error processing request"}

Response with PII Scrubbing

When PII is detected and scrubbed:

{
  "error": null,
  "response": "I can help you with that.",
  "finish_reason": "stop",
  "scrubbed_message": "User mentioned email: [REDACTED]",
  "prompt_tokens": 30,
  "completion_tokens": 8
}

Error Response

When an error occurs:

{
  "error": "Error processing request: Connection timeout",
  "finish_reason": "error",
  "response": "Sorry, I encountered an error processing your request. Please try again.",
  "scrubbed_message": ""
}

Streaming Responses

Server-Sent Events (SSE)

The chat API supports real-time streaming via Server-Sent Events (SSE). This allows you to receive response chunks as they're generated, providing a better user experience for long responses.

Enabling Streaming

Set streamingEnabled: true in your request:

{
  "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
  "messages": [
    {
      "role": "user",
      "content": "Tell me a long story"
    }
  ],
  "streamingEnabled": true
}

SSE Event Types

content

Partial content chunk from the streaming response.

event: content
data: {"content": "Once", "stream_id": "abc123"}

event: content
data: {"content": " upon", "stream_id": "abc123"}

event: content
data: {"content": " a", "stream_id": "abc123"}

event: content
data: {"content": " time", "stream_id": "abc123"}

done

Stream completed successfully. Includes final metadata.

event: done
data: {"finish_reason": "stop", "prompt_tokens": 25, "completion_tokens": 100}

error

An error occurred during processing.

event: error
data: {"error": "Error processing request"}

Connection Management

  • Connection Limits: Each user can have a limited number of concurrent SSE connections (typically 5)
  • Automatic Disconnect: The server automatically disconnects after processing completes
  • One Message Per Connection: Each chat request requires a new connection

Handling SSE in JavaScript

async function streamChat(accessToken, agentId, messages) {
  const response = await fetch('https://api.agent700.ai/api/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agentId: agentId,
      messages: messages,
      streamingEnabled: true
    }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

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

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop() || '';

    for (const line of lines) {
      if (line.startsWith('event: ')) {
        const eventType = line.substring(7);
      } else if (line.startsWith('data: ')) {
        const data = JSON.parse(line.substring(6));
        
        if (eventType === 'content') {
          // Handle content chunk
          console.log('Content:', data.content);
        } else if (eventType === 'done') {
          // Handle completion
          console.log('Finished:', data.finish_reason);
        } else if (eventType === 'error') {
          // Handle error
          console.error('Error:', data.error);
        }
      }
    }
  }
}

Model catalog first

Before assigning a model to an agent or sending chat requests, call GET /api/models (optionally with ?category=text) and use a model's name from the response. The catalog is scoped to your organization (admin opt-out), includes capability flags and pricing, and is the same list the Agent700 UI uses.

Typical integration order:

  1. Discover — GET /api/models?category=text
  2. Configure (optional) — PUT /api/agents/{agentId} with { "model": "<name>" } to persist the choice on a new revision, or POST /api/agents when creating an agent
  3. Chat — POST /api/chat with agentId (agent's revision supplies the model), or add "model": "<name>" to override for a single request

Hard-coding model strings breaks when a model is deprecated or disabled for your org; the API returns 400 if the model is not in the active catalog.

Guide: guides/MODEL_CATALOG_INTEGRATION.md (add as a ReadMe Guide page).

Examples: APIdocs/Agent700-openapi-3.0.3.yaml — catalog_flow_* on GET /api/models, POST /api/agents, PUT /api/agents/{agentId}, and POST /api/chat. Short index: DYNAMIC_MODEL_SYSTEM.md — Integration patterns.

Code Examples

JavaScript/TypeScript

Basic Chat Request

async function sendChatMessage(accessToken, agentId, userMessage) {
  const response = await fetch('https://api.agent700.ai/api/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agentId: agentId,
      messages: [
        {
          role: 'user',
          content: userMessage
        }
      ]
    }),
  });

  if (!response.ok) {
    throw new Error(`Chat request failed: ${response.statusText}`);
  }

  return response.json();
}

// Usage
const result = await sendChatMessage(
  accessToken,
  'e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6',
  'Hello, how are you?'
);
console.log('Response:', result.response);

Chat with Conversation History

async function chatWithHistory(accessToken, agentId, conversationHistory) {
  const response = await fetch('https://api.agent700.ai/api/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agentId: agentId,
      messages: conversationHistory
    }),
  });

  if (!response.ok) {
    throw new Error(`Chat request failed: ${response.statusText}`);
  }

  const result = await response.json();
  
  // Add assistant response to conversation history
  conversationHistory.push({
    role: 'assistant',
    content: result.response
  });

  return result;
}

// Usage
let conversation = [
  { role: 'user', content: 'What is 2+2?' }
];

const result1 = await chatWithHistory(accessToken, agentId, conversation);
console.log('First response:', result1.response);

conversation.push({ role: 'user', content: 'What about 3+3?' });
const result2 = await chatWithHistory(accessToken, agentId, conversation);
console.log('Second response:', result2.response);

Streaming Chat Request

async function streamChat(accessToken, agentId, messages, onChunk, onComplete, onError) {
  const response = await fetch('https://api.agent700.ai/api/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agentId: agentId,
      messages: messages,
      streamingEnabled: true
    }),
  });

  if (!response.ok) {
    throw new Error(`Chat request failed: ${response.statusText}`);
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
  let currentEvent = null;
  let fullResponse = '';

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

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop() || '';

    for (const line of lines) {
      if (line.startsWith('event: ')) {
        currentEvent = line.substring(7).trim();
      } else if (line.startsWith('data: ')) {
        const data = JSON.parse(line.substring(6));
        
        if (currentEvent === 'content') {
          fullResponse += data.content;
          if (onChunk) onChunk(data.content, fullResponse);
        } else if (currentEvent === 'done') {
          if (onComplete) onComplete(data, fullResponse);
        } else if (currentEvent === 'error') {
          if (onError) onError(data.error);
        }
      }
    }
  }
}

// Usage
await streamChat(
  accessToken,
  agentId,
  [{ role: 'user', content: 'Tell me a story' }],
  (chunk, full) => {
    console.log('Chunk:', chunk);
    console.log('Full so far:', full);
  },
  (metadata, full) => {
    console.log('Complete:', full);
    console.log('Tokens:', metadata);
  },
  (error) => {
    console.error('Error:', error);
  }
);

Chat with MCP Tools

async function chatWithMcpTools(accessToken, agentId, userMessage) {
  const response = await fetch('https://api.agent700.ai/api/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agentId: agentId,
      enableMcp: true,
      mcpServerNames: ['filesystem', 'github'],
      mcpAutoApprove: false,
      messages: [
        {
          role: 'user',
          content: userMessage
        }
      ]
    }),
  });

  if (!response.ok) {
    throw new Error(`Chat request failed: ${response.statusText}`);
  }

  return response.json();
}

// Usage
const result = await chatWithMcpTools(
  accessToken,
  agentId,
  'List the files in the current directory'
);
console.log('Response:', result.response);

Python

Basic Chat Request

import requests

def send_chat_message(access_token, agent_id, user_message):
    url = 'https://api.agent700.ai/api/chat'
    headers = {
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    }
    data = {
        'agentId': agent_id,
        'messages': [
            {
                'role': 'user',
                'content': user_message
            }
        ]
    }
    
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()

# Usage
result = send_chat_message(
    access_token,
    'e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6',
    'Hello, how are you?'
)
print('Response:', result['response'])

Chat with Conversation History

def chat_with_history(access_token, agent_id, conversation_history):
    url = 'https://api.agent700.ai/api/chat'
    headers = {
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    }
    data = {
        'agentId': agent_id,
        'messages': conversation_history
    }
    
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    result = response.json()
    
    # Add assistant response to conversation history
    conversation_history.append({
        'role': 'assistant',
        'content': result['response']
    })
    
    return result

# Usage
conversation = [
    {'role': 'user', 'content': 'What is 2+2?'}
]

result1 = chat_with_history(access_token, agent_id, conversation)
print('First response:', result1['response'])

conversation.append({'role': 'user', 'content': 'What about 3+3?'})
result2 = chat_with_history(access_token, agent_id, conversation)
print('Second response:', result2['response'])

Streaming Chat Request

import requests
import json

def stream_chat(access_token, agent_id, messages, on_chunk=None, on_complete=None, on_error=None):
    url = 'https://api.agent700.ai/api/chat'
    headers = {
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    }
    data = {
        'agentId': agent_id,
        'messages': messages,
        'streamingEnabled': True
    }
    
    response = requests.post(url, headers=headers, json=data, stream=True)
    response.raise_for_status()
    
    buffer = ''
    current_event = None
    full_response = ''
    
    for line in response.iter_lines():
        if line:
            line = line.decode('utf-8')
            
            if line.startswith('event: '):
                current_event = line[7:].strip()
            elif line.startswith('data: '):
                data = json.loads(line[6:])
                
                if current_event == 'content':
                    full_response += data.get('content', '')
                    if on_chunk:
                        on_chunk(data.get('content', ''), full_response)
                elif current_event == 'done':
                    if on_complete:
                        on_complete(data, full_response)
                elif current_event == 'error':
                    if on_error:
                        on_error(data.get('error'))
    
    return full_response

# Usage
def on_chunk(chunk, full):
    print(f'Chunk: {chunk}')

def on_complete(metadata, full):
    print(f'Complete: {full}')
    print(f'Tokens: {metadata}')

def on_error(error):
    print(f'Error: {error}')

result = stream_chat(
    access_token,
    agent_id,
    [{'role': 'user', 'content': 'Tell me a story'}],
    on_chunk=on_chunk,
    on_complete=on_complete,
    on_error=on_error
)

cURL Examples

Basic Chat Request

curl -X POST https://api.agent700.ai/api/chat \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ]
  }'

Chat with Conversation History

curl -X POST https://api.agent700.ai/api/chat \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
    "messages": [
      {
        "role": "user",
        "content": "What is 2+2?"
      },
      {
        "role": "assistant",
        "content": "2+2 equals 4."
      },
      {
        "role": "user",
        "content": "What about 3+3?"
      }
    ]
  }'

Streaming Chat Request

curl -X POST https://api.agent700.ai/api/chat \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
    "messages": [
      {
        "role": "user",
        "content": "Tell me a story"
      }
    ],
    "streamingEnabled": true
  }'

Chat with Custom Model Settings

curl -X POST https://api.agent700.ai/api/chat \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
    "model": "gpt-4",
    "temperature": 0.7,
    "maxTokens": 1000,
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing"
      }
    ]
  }'

Chat with PII Scrubbing

curl -X POST https://api.agent700.ai/api/chat \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "e2f5206e-5bfc-4d5c-a7a2-31a18bfc8bd6",
    "scrubPii": true,
    "piiThreshold": 0.8,
    "messages": [
      {
        "role": "user",
        "content": "My email is [email protected]"
      }
    ]
  }'

Fetch URL Metadata

curl -X GET "https://api.agent700.ai/api/chat/fetch-url-metadata?url=https://example.com" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Use Cases and Patterns

Basic Conversation

Simple question-and-answer interaction:

const response = await sendChatMessage(
  accessToken,
  agentId,
  'What is the capital of France?'
);
console.log(response.response); // "The capital of France is Paris."

Multi-Turn Conversation

Maintaining context across multiple exchanges:

let conversation = [
  { role: 'user', content: 'I want to learn Python' }
];

// First turn
const response1 = await chatWithHistory(accessToken, agentId, conversation);
console.log(response1.response);

// Second turn - maintains context
conversation.push({ role: 'user', content: 'What are the basics?' });
const response2 = await chatWithHistory(accessToken, agentId, conversation);
console.log(response2.response);

Streaming for Better UX

Real-time response display for long answers:

await streamChat(
  accessToken,
  agentId,
  [{ role: 'user', content: 'Write a long article about AI' }],
  (chunk, full) => {
    // Update UI in real-time
    document.getElementById('response').textContent = full;
  },
  (metadata) => {
    console.log('Streaming complete');
  }
);

One-off prompts without saving an agent

Create a dedicated agent with POST /api/agents, call /api/chat with its agentId, and delete the agent when finished if you do not need to keep it.

Agent Revision Testing

Testing different agent configurations:

// Test revision 1
const response1 = await sendChatMessage(
  accessToken,
  agentId,
  'What is AI?',
  { agentRevisionId: 1 }
);

// Test revision 2
const response2 = await sendChatMessage(
  accessToken,
  agentId,
  'What is AI?',
  { agentRevisionId: 2 }
);

// Compare responses
console.log('Revision 1:', response1.response);
console.log('Revision 2:', response2.response);

PII Protection

Protecting sensitive information:

const response = await sendChatMessage(
  accessToken,
  agentId,
  'My SSN is 123-45-6789',
  { scrubPii: true, piiThreshold: 0.8 }
);

if (response.scrubbed_message) {
  console.log('PII was scrubbed:', response.scrubbed_message);
}

MCP Tool Integration

Using external tools through MCP:

const response = await chatWithMcpTools(
  accessToken,
  agentId,
  'List files in /home/user/documents'
);
// Agent can use filesystem MCP tools to list files

Smart Document Evaluation

Context-aware responses using embeddings:

const response = await sendChatMessage(
  accessToken,
  agentId,
  'What is your privacy policy?',
  {
    smartDocEvaluation: true,
    smartDocChunkSize: 1000,
    smartDocTopK: 3
  }
);
// Agent retrieves relevant chunks from alignment data

Best Practices

Message Management

  1. Maintain Conversation History: Include previous messages in the messages array to maintain context
  2. Limit History Length: Very long conversation histories can exceed token limits - consider truncating old messages
  3. Use Message IDs: Include id fields for messages to help track conversation state

Example:

// Good: Maintains context
const messages = [
  { role: 'user', content: 'What is Python?' },
  { role: 'assistant', content: 'Python is a programming language...' },
  { role: 'user', content: 'What can I build with it?' }
];

// Bad: Loses context
const messages = [
  { role: 'user', content: 'What can I build with it?' }
];

Error Handling

Always implement proper error handling:

async function safeChat(accessToken, agentId, message) {
  try {
    const response = await sendChatMessage(accessToken, agentId, message);
    
    if (response.error) {
      console.error('Chat error:', response.error);
      return null;
    }
    
    return response;
  } catch (error) {
    if (error.response?.status === 401) {
      // Token expired, refresh and retry
      const newToken = await refreshToken();
      return safeChat(newToken, agentId, message);
    } else if (error.response?.status === 402) {
      // Payment required
      console.error('Payment required for agent owner');
      return null;
    } else {
      console.error('Unexpected error:', error);
      return null;
    }
  }
}

Token Management

  1. Monitor Token Usage: Check prompt_tokens and completion_tokens in responses
  2. Set Appropriate Limits: Use maxTokens to prevent excessive token usage
  3. Handle Token Limits: Check finish_reason for "length" to detect truncation

Example:

const response = await sendChatMessage(accessToken, agentId, message);

if (response.finish_reason === 'length') {
  console.warn('Response was truncated due to token limit');
  // Consider increasing maxTokens or shortening the request
}

console.log(`Used ${response.prompt_tokens} prompt tokens and ${response.completion_tokens} completion tokens`);

Streaming Best Practices

  1. Handle Connection Limits: Be aware of SSE connection limits per user
  2. Implement Reconnection: Handle disconnections gracefully
  3. Buffer Management: Properly handle partial SSE messages

Example:

let reconnectAttempts = 0;
const maxReconnectAttempts = 3;

async function streamWithRetry(accessToken, agentId, messages) {
  try {
    await streamChat(accessToken, agentId, messages, onChunk, onComplete, onError);
  } catch (error) {
    if (reconnectAttempts < maxReconnectAttempts) {
      reconnectAttempts++;
      console.log(`Reconnecting... (attempt ${reconnectAttempts})`);
      await new Promise(resolve => setTimeout(resolve, 1000 * reconnectAttempts));
      return streamWithRetry(accessToken, agentId, messages);
    } else {
      console.error('Max reconnection attempts reached');
    }
  }
}

Performance Optimization

  1. Cache Agent Configurations: Store agent metadata to reduce API calls
  2. Batch Operations: When possible, batch multiple chat requests
  3. Use Streaming: For long responses, use streaming to improve perceived performance

Security Best Practices

  1. Use PII Scrubbing: Enable scrubPii when handling sensitive data
  2. Validate Input: Sanitize user messages before sending
  3. Secure Token Storage: Never expose access tokens in client-side code
  4. Monitor Usage: Track API usage to detect anomalies

Example:

function sanitizeMessage(message) {
  // Remove potentially dangerous content
  return message.trim().substring(0, 10000); // Limit length
}

const sanitized = sanitizeMessage(userInput);
const response = await sendChatMessage(
  accessToken,
  agentId,
  sanitized,
  { scrubPii: true, piiThreshold: 0.9 }
);

Model Selection

  1. Fetch the catalog first: Call GET /api/models and use models[].name — do not hard-code model strings in production integrations
  2. Use Agent Defaults: Let agents use their configured models unless you need to override per request
  3. Consider Cost: Use pricingTiers from the catalog to compare cost before assigning a model to a high-volume agent
  4. Match Use Case: Use capabilityTier, latencyClass, and capability flags (supportsVision, supportsMcp, etc.) from the catalog response

Troubleshooting

Common Errors and Solutions

"Payment required for agent owner" (402)

Cause: The agent owner doesn't have an active paid subscription.

Solutions:

  1. Verify the agent owner has an active paid subscription
  2. Check payment status in account settings
  3. Contact support if payment is active but still receiving this error

"Missing required field: messages" (400)

Cause: The messages array is missing or empty.

Solutions:

  1. Ensure the request body includes a messages array
  2. Verify the array contains at least one message
  3. Check that the JSON structure is valid

Example Fix:

// ❌ Incorrect
await sendChatMessage(accessToken, agentId, null);

// ✅ Correct
await sendChatMessage(accessToken, agentId, 'Hello');

"Authentication required" (401)

Cause: Missing or invalid authentication token.

Solutions:

  1. Include the Authorization: Bearer <token> header
  2. Verify the token is not expired
  3. Refresh the token if needed

Example Fix:

// Ensure token is included
const response = await fetch(url, {
  headers: {
    'Authorization': `Bearer ${accessToken}`, // Don't forget this!
  },
});

"Error processing request" (500)

Cause: Server error during chat processing.

Solutions:

  1. Check the error message in the response
  2. Verify request format is correct
  3. Retry the request after a short delay
  4. Contact support if the issue persists

Streaming Connection Issues

Issue: SSE connection fails or disconnects unexpectedly.

Solutions:

  1. Check connection limits (typically 5 concurrent connections per user)
  2. Implement reconnection logic
  3. Verify network stability
  4. Check for firewall/proxy issues blocking SSE

Example:

// Implement connection retry
let retries = 0;
const maxRetries = 3;

async function connectWithRetry() {
  try {
    await streamChat(accessToken, agentId, messages, onChunk, onComplete, onError);
  } catch (error) {
    if (retries < maxRetries) {
      retries++;
      await new Promise(resolve => setTimeout(resolve, 1000 * retries));
      return connectWithRetry();
    }
    throw error;
  }
}

Response Truncation

Issue: Response is cut off mid-sentence.

Cause: Response exceeded maxTokens limit.

Solutions:

  1. Increase maxTokens in the request
  2. Check finish_reason for "length" to detect truncation
  3. Consider breaking complex queries into smaller parts

Example:

const response = await sendChatMessage(
  accessToken,
  agentId,
  message,
  { maxTokens: 2000 } // Increase from default
);

if (response.finish_reason === 'length') {
  console.warn('Response was truncated. Consider increasing maxTokens.');
}

PII Not Being Scrubbed

Issue: PII scrubbing not working as expected.

Solutions:

  1. Verify scrubPii: true is set in the request
  2. Adjust piiThreshold (lower = more sensitive, higher = less sensitive)
  3. Check scrubbed_message in the response for details

Example:

const response = await sendChatMessage(
  accessToken,
  agentId,
  'My email is [email protected]',
  { scrubPii: true, piiThreshold: 0.7 } // Lower threshold = more aggressive
);

if (response.scrubbed_message) {
  console.log('PII scrubbed:', response.scrubbed_message);
}

MCP Tools Not Working

Issue: MCP tools not being called or approved.

Solutions:

  1. Verify enableMcp: true is set
  2. Check that the model supports MCP (some models don't)
  3. Ensure mcpServerNames includes the correct server names
  4. Check if mcpAutoApprove needs to be enabled
  5. Verify MCP servers are properly configured

Example:

// Ensure MCP is properly configured
const response = await sendChatMessage(
  accessToken,
  agentId,
  'List files in current directory',
  {
    enableMcp: true,
    mcpServerNames: ['filesystem'], // Correct server name
    mcpAutoApprove: true // Auto-approve tool calls
  }
);

Debugging Tips

  1. Log Request/Response: Log full request and response for debugging
  2. Check Token Usage: Monitor token counts to identify issues
  3. Validate JSON: Ensure request body is valid JSON
  4. Test with Minimal Request: Start with the simplest possible request

Example Debugging:

async function debugChat(accessToken, agentId, message) {
  const request = {
    agentId: agentId,
    messages: [{ role: 'user', content: message }]
  };
  
  console.log('Request:', JSON.stringify(request, null, 2));
  
  try {
    const response = await sendChatMessage(accessToken, agentId, message);
    console.log('Response:', JSON.stringify(response, null, 2));
    return response;
  } catch (error) {
    console.error('Error:', error);
    console.error('Error details:', error.response?.data);
    throw error;
  }
}

Related Documentation

Support

For chat-related issues or questions:

Last Updated: June 2026
API Version: 1.1.0

Updated about 1 month ago

Did this page help you?