API агента

У каждого агента есть публичный HTTP API для интеграции в любые системы — мобильное приложение, Telegram-бот, ваша админка и т.п.

Endpoint

POST https://framix.app/api/agents/public/chat-stream

Ответ возвращается потоково (Server-Sent Events, text/event-stream). Каждое событие — JSON после префикса data:.

Авторизация

• Публичные агенты — без авторизации, по agentId.
• Приватные (если в будущем включите такой режим) — нужен API-ключ во вкладке «API-ключи».

API-ключи создаются на странице агента → вкладка «API-ключи» → кнопка «Сгенерировать ключ». До 5 ключей на агента. Ключ показывается только один раз при создании — сохраните сразу. Удалить можно через UI.

Тело запроса

{
  "agentId": "agent-id-here",
  "message": "Сообщение пользователя",
  "sessionId": "session-id-here",
  "apiKey": "fmx_..."
}

События потока

Пример: cURL

curl -N -X POST https://framix.app/api/agents/public/chat-stream \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your-agent-id",
    "message": "Привет!",
    "sessionId": null
  }'

Пример: JavaScript / fetch + SSE

const res = await fetch('https://framix.app/api/agents/public/chat-stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agentId: 'your-agent-id',
    message: 'Привет!',
    sessionId: null,
  }),
})

const reader = res.body.getReader()
const decoder = new TextDecoder()
let buffer = ''
let answer = ''
let sessionId = null

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('data: ')) continue
    const evt = JSON.parse(line.slice(6))
    if (evt.type === 'start') sessionId = evt.sessionId
    if (evt.type === 'chunk') answer += evt.content
    if (evt.type === 'done') {
      console.log('answer:', answer)
      console.log('usage:', evt.usage)
    }
  }
}

Пример: Python

import json
import requests

with requests.post(
    'https://framix.app/api/agents/public/chat-stream',
    json={
        'agentId': 'your-agent-id',
        'message': 'Привет!',
        'sessionId': None,
    },
    stream=True,
) as r:
    answer = ''
    session_id = None
    for line in r.iter_lines():
        if not line or not line.startswith(b'data: '):
            continue
        evt = json.loads(line[6:])
        if evt.get('type') == 'start':
            session_id = evt.get('sessionId')
        if evt.get('type') == 'chunk':
            answer += evt.get('content', '')
        if evt.get('type') == 'done':
            print('answer:', answer)
            print('usage:', evt.get('usage'))

Сохранение sessionId

Чтобы поддерживать многошаговый диалог, сохраняйте sessionId после первого ответа и передавайте в следующих запросах. Без него каждый запрос — новый разговор без памяти о предыдущем.

В web-виджете это работает автоматически через localStorage. В приложениях — храните в базе/AsyncStorage/SharedPreferences.

HTTP-коды ошибок

Ограничения

• CORS — открыт для всех (Access-Control-Allow-Origin: *), поэтому работает с веба напрямую.
• Размер сообщения — до 10 000 символов.
• Скорость — стриминг поддерживается до самого конца ответа. Никаких полл-эндпоинтов нет.
• Списания — каждый запрос списывает рубли с баланса владельца агента (того, кто его создал в Framix). Конечный пользователь ничего не платит.

Use cases

• Telegram-бот — оборачиваете API в python-telegram-bot, сохраняете sessionId на chat_id.
• Мобильное приложение — нативно через URLSession/OkHttp, сохраняете sessionId в Keychain/SharedPreferences.
• Discord/Slack-бот — то же самое, sessionId на user_id в канале.
• Backend-сервис — внутри ваших микросервисов как «AI Helper».
• Voice assistant — STT → API → TTS, дайте боту голос.