Chat API

Send messages to agents and receive responses.

Send Message

POST /api/agents/:name/chat

Request

{
  "message": "What files are in my Downloads folder?",
  "stream": false,
  "context": {
    "source": "api",
    "user_id": "user123"
  }
}

Parameters

Field	Type	Required	Description
message	string	Yes	The message to send
stream	boolean	No	Enable streaming (default: false)
context	object	No	Additional context

Response (Non-Streaming)

{
  "success": true,
  "response": "I'll check your Downloads folder.\n\nFound 15 files:\n- report.pdf\n- image.png\n- ...",
  "metadata": {
    "model": "gpt-4o",
    "tokens_used": 150,
    "processing_time_ms": 2300,
    "skills_invoked": ["host_shell"]
  }
}

Stream Message

GET /api/agents/:name/chat/stream

Query Parameters

Parameter	Required	Description
message	Yes	URL-encoded message
context	No	JSON-encoded context

Server-Sent Events

event: token
data: {"content": "I'll check"}

event: token
data: {"content": " your Downloads"}

event: invoke_start
data: {"skill": "host_shell", "args": ["ls -la ~/Downloads"]}

event: invoke_end
data: {"result": "total 15\ndrwxr-xr-x..."}

event: token
data: {"content": "\n\nFound 15 files:"}

event: done
data: {"tokens_used": 150, "processing_time_ms": 2300}

JavaScript Example

function streamChat(agent, message, onToken, onDone) {
  const url = `/api/agents/${agent}/chat/stream?message=${encodeURIComponent(message)}`;
  const eventSource = new EventSource(url);
  
  eventSource.addEventListener('token', (event) => {
    const data = JSON.parse(event.data);
    onToken(data.content);
  });
  
  eventSource.addEventListener('done', (event) => {
    const data = JSON.parse(event.data);
    onDone(data);
    eventSource.close();
  });
  
  eventSource.addEventListener('error', () => {
    eventSource.close();
  });
}

// Usage
streamChat('default', 'Hello!', 
  (token) => process.stdout.write(token),
  (metadata) => console.log('\nDone!', metadata)
);

Python Example

import requests

def stream_chat(agent, message):
    url = f'http://localhost:17890/api/agents/{agent}/chat/stream'
    params = {'message': message}
    
    with requests.get(url, params=params, stream=True) as response:
        for line in response.iter_lines():
            if line.startswith(b'data: '):
                data = json.loads(line[6:])
                if 'content' in data:
                    yield data['content']

New Session

POST /api/agents/:name/session/new

Starts a fresh conversation session.

Response

{
  "success": true,
  "session_id": "sess_abc123",
  "message": "New session started"
}

Get Conversation History

GET /api/agents/:name/conversation

Query Parameters

Parameter	Default	Description
limit	50	Max messages to return
session	current	Session ID (optional)

Response

{
  "session_id": "sess_abc123",
  "messages": [
    {
      "role": "user",
      "content": "Hello!",
      "timestamp": "2024-01-15T12:00:00Z"
    },
    {
      "role": "assistant",
      "content": "Hi! How can I help you?",
      "timestamp": "2024-01-15T12:00:02Z"
    }
  ]
}

Clear Conversation

DELETE /api/agents/:name/conversation

Response

{
  "success": true,
  "message": "Conversation cleared"
}

WebSocket (Alternative)

For bidirectional communication:

const ws = new WebSocket('ws://localhost:17890/api/agents/default/chat/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({ message: 'Hello!' }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.content);
};