Инструменты: агент вызывает ваши HTTP-эндпоинты

Всё, что агент делает помимо разговора, идёт через инструменты: чтение календаря, запись, проверка заказа, создание тикета. Инструмент — это GET- или POST-эндпоинт на вашей стороне, описанный для модели JSON-схемой. Модель решает, когда его вызвать и с какими аргументами; платформа выполняет запрос.

Определение инструмента

У инструмента есть имя, описание для модели, JSON-схема аргументов и часть для выполнения: URL, метод, заголовки и необязательный шаблон тела. Пишите плейсхолдеры {{name}} в URL, в значениях заголовков или в теле; каждый плейсхолдер должен быть объявлен в схеме с описанием. Модель заполняет его из разговора, а среда выполнения подставляет: с URL-кодированием в URL и с экранированием в JSON-теле.

{
  "name": "book_appointment",
  "description": "Записывает на приём. Вызывать только после того, как звонящий подтвердил день, время и имя.",
  "method": "POST",
  "url": "https://api.example.ch/clinics/{{clinic}}/appointments",
  "headers": { "Authorization": "Bearer sk_…" },
  "body": "{ \"start\": \"{{start}}\", \"name\": \"{{name}}\", \"phone\": \"{{phone}}\" }",
  "schema": { "type": "object", "properties": {
    "clinic": { "type": "string", "description": "Код клиники: всегда 'zurich'" },
    "start":  { "type": "string", "description": "Начало, yyyy-MM-dd HH:mm" },
    "name":   { "type": "string", "description": "Имя и фамилия звонящего" },
    "phone":  { "type": "string", "description": "Телефон звонящего, только цифры" }
  }, "required": ["clinic", "start", "name", "phone"] }
}

Что получает ваш эндпоинт и что должен ответить

Каждый запрос несёт заголовок token с tool-токеном агента: проверяйте его первым. Отвечайте 200 с JSON-телом. При успехе { "success": true, "message": "…" } плюс любые данные: сообщение предназначено для передачи звонящему. При бизнес-ошибке { "success": false, "error": "…" } с ошибкой в виде фразы для модели, например что предложить вместо этого. При 401 или 500 агент извиняется и предлагает перезвонить. Держите ответы в пределах нескольких секунд: звонящий ждёт на линии.

app.post('/clinics/:clinic/appointments', express.json(), async (req, res) => {
  if (req.get('token') !== process.env.SWISSAI_TOOL_TOKEN) return res.status(401).end();
  const { start, name, phone } = req.body;
  if (!(await isFree(req.params.clinic, start)))
    return res.json({ success: false, error: 'Это время занято. Предложи 11:00 или 14:30 в тот же день.' });
  await book(req.params.clinic, start, name, phone);
  res.json({ success: true, message: 'Запись создана на ' + start + '.' });
});

Один список инструментов, общий для агентов

Инструменты живут в разделе Инструменты панели, и агенты используют их по ссылке: измените инструмент один раз, и каждый агент, который им пользуется, обновится. Инструмент, закреплённый за клиентом, могут использовать только агенты этого клиента. Перед сохранением панель проверяет определение с помощью Claude и строит схему из плейсхолдеров.

Попробовать, ничего не размещая

Песочница — это набор работающих примеров эндпоинтов с отдельными тестовыми данными для каждого аккаунта: календарь, столики ресторана, склад, обратные звонки, контакты, заказы. Её 22 инструмента уже есть в разделе Инструменты; у каждого есть руководство с параметрами, разобранный пример запроса и ответа и код эндпоинта, который можно скачать и использовать как основу.

Похожие страницы

• Запись на приём по телефону силами ИИ-агента
• SIP URI для каждого голосового агента
• Кнопка звонка на вашем сайте, на которую отвечает агент