Chatting with Agents

Interact with your configured agents.

Endpoint

POST /api/v1/agent/chat

Request Format

{
  "agent_id": "agent-id",
  "message": "Your message here",
  "rag_collection": "optional-collection-name",
  "conversation_id": "optional-conversation-id"
}

Parameters

Parameter	Required	Description	Default
agent_id	Yes	ID of the agent configuration	-
message	Yes	User's message or query	-
rag_collection	No	RAG collection to use for context	Agent default
conversation_id	No	Track conversation across requests	Auto-generated

Response Format

{
  "response": "Agent's answer here",
  "conversation_id": "conv-abc123",
  "tool_calls": [
    {
      "tool_name": "rag_search",
      "parameters": {...},
      "result": {...}
    }
  ],
  "model": "gpt-4"
}

Response Fields

Field	Description
response	Agent's final answer
conversation_id	ID for conversation tracking
tool_calls	Array of tools used (if any)
rag_used	Whether RAG was used (boolean)
model	Model that generated response

Basic Chat

Using Python

import requests

response = requests.post(
    "http://localhost/api/v1/agent/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "agent_id": "your-agent-id",
        "message": "What is the capital of France?"
    }
)

result = response.json()
print(f"Response: {result['response']}")

Using JavaScript

const response = await fetch('http://localhost/api/v1/agent/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_id: 'your-agent-id',
    message: 'What is the capital of France?'
  })
});

const result = await response.json();
console.log('Response:', result.response);

Using cURL

curl -X POST http://localhost/api/v1/agent/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "message": "What is the capital of France?"
  }'

Multi-Turn Conversations

Maintain context across multiple messages.

Without Conversation ID

# First message
response1 = requests.post(
    "http://localhost/api/v1/agent/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "agent_id": "your-agent-id",
        "message": "My name is Alice."
    }
)

result1 = response1.json()

# Second message (no context)
response2 = requests.post(
    "http://localhost/api/v1/agent/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "agent_id": "your-agent-id",
        "message": "What is 2+2?"
    }
)

result2 = response2.json()

With Conversation ID

import requests

conversation_id = None

# First message
response1 = requests.post(
    "http://localhost/api/v1/agent/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "agent_id": "your-agent-id",
        "message": "My name is Alice."
    }
)

conversation_id = response1.json()["conversation_id"]

# Second message (with context)
response2 = requests.post(
    "http://localhost/api/v1/agent/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "agent_id": "your-agent-id",
        "message": "What do you do?",
        "conversation_id": conversation_id
    }
)

result2 = response2.json()

RAG-Enhanced Chat

Use RAG collection to provide context for the agent.

Using Default RAG

response = requests.post(
    "http://localhost/api/v1/agent/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "agent_id": "your-agent-id",
        "message": "How do I configure API keys?"
    }
)

Agent uses its configured RAG collection.

Specifying RAG Collection

response = requests.post(
    "http://localhost/api/v1/agent/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "agent_id": "your-agent-id",
        "message": "What is the refund policy?",
        "rag_collection": "documentation"
    }
)

Overwrites the agent's default RAG collection.

Streaming Responses

Get responses as they're generated for better UX.

Using Python

response = requests.post(
    "http://localhost/api/v1/agent/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "agent_id": "your-agent-id",
        "message": "Tell me a long story",
        "stream": True
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        data = line.decode('utf-8')
        if "response" in data:
            response_part = data.replace("response:", "").strip()
            print(response_part, end="", flush=True)

Using JavaScript

const response = await fetch('http://localhost/api/v1/agent/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_id: 'your-agent-id',
    message: 'Tell me a story',
    stream: true
  })
});

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

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('response:')) {
      const content = line.slice(9);
      process.stdout.write(content);
    }
  }
}

Tool Execution Traces

Review which tools were called and their results.

Checking Tool Calls

response = requests.post(
    "http://localhost/api/v1/agent/chat",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "agent_id": "your-agent-id",
        "message": "Analyze this dataset: 100 random numbers"
    }
)

result = response.json()

if result.get("tool_calls"):
    print("Tools used:")
    for tool_call in result["tool_calls"]:
        print(f"  - {tool_call['tool_name']}")
        print(f"    Parameters: {tool_call.get('parameters', {})}")
        print(f"    Status: {tool_call.get('status', 'unknown')}")
        if "result" in tool_call:
            print(f"    Result: {tool_call['result']}")

Tool Call Results

Responses include tool execution details:

{
  "tool_calls": [
    {
      "tool_name": "rag_search",
      "parameters": {
        "query": "API configuration",
        "top_k": 5
      },
      "result": {
        "found": 3,
        "results": [
          {
            "document_id": "doc-123",
            "score": 0.92,
            "content": "Step 1: Go to Settings..."
          }
        ]
      },
      "status": "success"
    }
  ]
}

Error Handling

Common Errors

Agent Not Found

{
  "error": "AGENT_NOT_FOUND",
  "message": "Agent with ID 'xxx' not found"
}

Solution: Verify the agent ID is correct.

Tool Execution Failed

{
  "error": "TOOL_EXECUTION_FAILED",
  "message": "Tool 'rag_search' failed to execute",
  "details": {
    "tool_name": "rag_search",
    "error": "Collection not found"
  }
}

Solution: Check tool configuration and parameters.

Max Iterations Exceeded

{
  "error": "MAX_ITERATIONS_EXCEEDED",
  "message": "Agent reached maximum tool iterations",
  "details": {
    "max_iterations": 5,
    "iterations_used": 5
  }
}

Solution: Increase max_iterations or simplify the task.

Best Practices

Conversation Management

1. Use Conversation IDs - Maintain context across requests
2. Match User IDs - Associate conversations with users
3. Handle Conversation Limits - Be aware of agent memory length

Error Handling

1. Retry Failed Tool Calls - Implement retry logic for transient failures
2. Timeout Management - Set appropriate timeouts for agent requests
3. Graceful Degradation - Fall back to LLM if tools fail
4. Log Errors - Track and monitor agent performance

Streaming

1. Display As You Go - Show chunks as they arrive
2. Buffer Display - Consider adding small delays for readability
3. Handle Errors - Show errors inline with partial responses
4. Stop Functionality - Allow users to cancel long generations

Next Steps

• Creating Agents - Configure new agents
• Managing Agents - Update and organize agents
• Tool Calling - Direct tool usage without agents
• Examples - See complete code samples