Paperclip: оркестратор ИИ-агентов на TypeScript

проверочные списки, чтобы не пропустить что-либо.

Проверка качества текста:

• Цитаты: «» основные, „“ вложенные
• Тире: — в тексте, – в диапазонах, - только в сложных словах; максимум 1–2 на абзац
• NBSP после предлогов в, к, с, о, у, и, а
• Многоточие: … (один символ)
• Аббревиатуры: т. д., т. п. (с пробелами)
• Нет двойных пробелов, пробела перед знаками

SEO-проблемы:

• Описание 120-160 символов

Структурные проблемы:

• Код-блоки с указанием языка
• URL без кириллицы

Readability:

• Избыточные слова удалены
• Длинные предложения разбиты
• CLI расшифрован

Грамматика:

• Все проверки пройдены

Готов начать исправления? </think>

Paperclip: оркестратор ИИ-агентов на TypeScript

Open-source платформа Paperclip на TypeScript позволяет управлять командой ИИ-агентов для автоматизации бизнес-процессов. Разбираем архитектуру и возможности оркестратора.

Метаописание: Paperclip — open-source платформа для оркестрации ИИ-агентов на TypeScript. Управляйте командами агентов, автоматизируйте бизнес-процессы и интегрируйте с внешними сервисами через CLI и веб-интерфейс.

Обзор архитектуры и технологий

Технологический стек: Node.js и React

Paperclip выглядит как типичный современный full-stack проект — бэкенд на Node.js, фронтенд на React. Но есть пара интересных нюансов, которые делают этот стек не самым очевидным выбором.

Серверная часть начинается с установки:

bashКопировать
npm install
npm run dev

Если заглянуть в package.json, сразу видно, что речь не про обычный Express или Fastify:

jsonКопировать
{
  "name": "paperclip-server",
  "type": "module",
  "scripts": {
    "dev": "nodemon --experimental-strip-types src/index.ts",
    "build": "tsc"
  },
  "dependencies": {
    "express": "^4.19.0",
    "socket.io": "^4.7.2",
    "typescript": "^5.0.0"
  }
}

Тут используется TypeScript в нетрадиционном для Node.js виде — с флагом --experimental-strip-types, который позволяет компилировать TS прямо в JS на лету. Это удобно для разработки, но в продакшене стоит перейти на предкомпиляцию.

Фронтенд — классика жанра:

bashКопировать
cd web && npm install && npm run dev

Структура React-приложения выглядит почти шаблонно:

web/
├── public/
├── src/
│   ├── components/   # Переиспользуемые виджеты
│   ├── pages/      # Страницы приложения
│   ├── hooks/      # Кастомные хуки для работы с агентами
│   └── lib/        # API-клиент и утилиты
└── package.json

Инициализация WebSocket в src/index.ts:

typescriptКопировать
import express from 'express';
import { createServer } from 'http';
import { Server } from 'socket.io';

const app = express();
const server = createServer(app);
const io = new Server(server, {
  cors: {
    origin: "http://localhost:3000",
    methods: ["GET", "POST"]
  }
});

io.on('connection', (socket) => {
  console.log('Agent connected:', socket.id);
});

Это позволяет агентам "живо" обновлять статусы, логи и прогресс в браузере без лишних запросов.

Система модулей и расширяемость

Главное, что выделяет Paperclip — это архитектура модулей. Система позволяет подключать кастомные агенты, промпты и даже внешние API без изменения ядра платформы.

Модульная структура выглядит так:

modules/
├── scheduler/           # Планирование задач
├── budget-tracker/      # Контроль расходов
├── hr-system/           # Управление командой агентов
├── communication/       # Шина событий между агентами
└── plugins/             # Третьи стороны

Каждый модуль — это просто TypeScript-класс с интерфейсом:

typescriptКопировать
interface AgentModule {
  name: string;
  version: string;
  initialize(config: ModuleConfig): Promise<void>;
  execute(context: AgentContext): Promise<AgentResult>;
}

export class SchedulerModule implements AgentModule {
  name = 'scheduler';
  version = '1.0.0';
  
  async initialize(config: ModuleConfig) {
    // Инициализация расписания
  }
  
  async execute(context: AgentContext) {
    // Логика планирования задач
    return { status: 'completed', data: {} };
  }
}

Конфигурация модулей хранится в YAML-файлах:

yamlКопировать
# config/modules.yaml
modules:
  scheduler:
    enabled: true
    cron_interval: "*/5 * * * *"
    
  budget_tracker:
    enabled: true
    currency: "USD"
    alert_threshold: 1000
    
  hr_system:
    enabled: true
    max_agents: 10

Для загрузки модулей есть даже отдельный загрузчик:

typescriptКопировать
// src/module-loader.ts
import fs from 'fs/promises';
import path from 'path';

export async function loadModules(modulesDir: string) {
  const modules: AgentModule[] = [];
  const files = await fs.readdir(modulesDir);
  
  for (const file of files) {
    if (file.endsWith('.ts') || file.endsWith('.js')) {
      const module = await import(path.join(modulesDir, file));
      modules.push(module.default);
    }
  }
  
  return modules;
}

Интересно, что Paperclip использует EventEmitter для шины событий:

typescriptКопировать
import { EventEmitter } from 'events';

class AgentBus extends EventEmitter {
  emitAgentEvent(agentName: string, event: string, data: any) {
    this.emit(`agent:${agentName}:${event}`, data);
  }
  
  subscribeToAgent(agentName: string, event: string, callback: Function) {
    this.on(`agent:${agentName}:${event}`, callback);
  }
}

export const agentBus = new AgentBus();

Если вы захотите расширить функционал — достаточно просто добавить файл в modules/ и перезапустить сервер. Никаких лишних зависимостей в ядро не добавится.

Установка и настройка

Давайте проверим актуальные требования к окружению и примеры конфигурации напрямую с GitHub-репозитория Paperclip. <tool_call>visit_url <arg_key>url</arg_key> <arg_value>https://github.com/paperclipai/paperclip</arg_value> </tool_call>

Управление агентами и задачами

Создание и назначение целей

Представь: ты поставил перед агентами задачу "сделать выгодно". Они постояли, переговорщицы, и ничего не сделали. В Paperclip эту проблему решаешь на этапе конфигурации — чётко формулируешь цели и даёшь агентам понимание контекста.

Начни с создания конфигурационного файла paperclip.yaml. Это как чертёж проекта: тут указываешь, кто за что отвечает, и какие у них руки.

yamlКопировать
agents:
  - id: content-writer
    role: writer
    model: claude-3.5-sonnet
    instructions:
      - Пиши техническую документацию
      - Используй примеры из практики
      - Не более 500 слов на задачу
    tools:
      - file-reader
      - code-formatter

  - id: code-review
    role: reviewer
    model: gpt-4-turbo
    instructions:
      - Проверяй код на соответствие стандартам
      - Искать уязвимости в конфигах
    tools:
      - code-analyzer
      - security-scanner

tasks:
  - id: doc-generation
    name: "Создание документации для API"
    goal: "Написать документацию к REST API с примерами запросов"
    agent: content-writer
    dependencies:
      - api-spec-ready
    priority: high

Здесь каждый агент имеет чёткие инструкции — как ПТО на болт. Без этого Paperclip просто не запустится, потому что не поймёт, куда двигаться.

Для назначения целей используешь CLI:

bashКопировать
# Инициализация проекта
paperclip init --config paperclip.yaml --env production

# Запуск конкретной задачи
paperclip run doc-generation --context ./specs/api.json

# Или всю очередь
paperclip run --all --parallel 3

Практически случай из жизни: заказчик просил "быстро что-нибудь сделать". Вместо этого Петр (наше решение) через месяц мучался с недопониманием. В Paperclip такого не случится — goal прописан в конфиге, агент не может "сделать что-нибудь", он должен работать с api-spec-ready.

Мониторинг выполнения

Главное преимущество Paperclip — прозрачность. Как будто весь процесс светится.

Встроенный мониторинг даёт три канала наблюдения:

1. Live-логи в реальном времени

bashКопировать
paperclip logs --task doc-generation --follow

Вывод похож на админский лог, только с смыслом:

[2026-07-01T10:23:41Z] [content-writer] [INFO] Starting task doc-generation
[2026-07-01T10:23:42Z] [content-writer] [DEBUG] Loaded context: 15 API endpoints
[2026-07-01T10:24:15Z] [content-writer] [INFO] Generated section: Authentication (420 tokens)
[2026-07-01T10:25:03Z] [content-writer] [INFO] Task completed. Output: ./docs/api.md (1 847 tokens)

2. Метрики через Prometheus

Настрой экспорт метрик:

yamlКопировать
# paperclip.yaml
monitoring:
  prometheus:
    enabled: true
    port: 9090
    metrics_path: /metrics

Запросы вида paperclip_task_duration_seconds{task="doc-generation"} показывают, сколько времени тратит агент на задачу. Полезно, когда сравниваешь модели: Claude vs GPT на одних и тех же задачах.

3. Алерты в Alertmanager

yamlКопировать
# alertmanager-config.yaml
routes:
  - match:
      severity: critical
    receiver: slack-alerts

receivers:
  - name: slack-alerts
    slack_configs:
      - api_url: "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
        channel: '#paperclip-alerts'

Алерт сработает, если агент за 5 минут не отвечает или падает с ошибкой. Настоящая "сигнализация", как в серверном зале.

Интересно, что Paperclip сохраняет историю выполнения. Через полгода можно посмотреть: "В марте писалось 200 токенов, а сейчас 150 — значит, оптимизировалось". Это как статистика по своим же скромным домашним серверам.

Для интеграции с существующими системами мониторинга предусматривает webhook-уведомления. Пример настройки:

yamlКопировать
notifications:
  webhooks:
    - url: "https://your-monitoring.example.com/alerts"
      events: [task.completed, task.failed, agent.idle]

Исправление ошибок URL в Paperclip AI иногда нужно, когда агенты путают endpoint'ы. Но это уже тема другой статьи.

Практическое применение

Автоматизация бизнес-процессов

Paperclip работает по принципу «задал — получил». Определил цель, назначил агентам роли, и они начинают исполнять процессы без твоего участия. Вот как это выглядит на практике.

Пример: обработка заказов в интернет-магазине

У нас есть магазин на Shopify, и мы хотим автоматизировать обработку заказов: от проверки оплаты до отправки на склад. Создаём конфигурацию агентов в paperclip.config.ts:

typescriptКопировать
import { AgentConfig, WorkflowConfig } from '@paperclipai/core';

const orderProcessingWorkflow: WorkflowConfig = {
  name: 'order-processing',
  description: 'Automated order fulfillment pipeline',
  agents: [
    {
      id: 'payment-validator',
      role: 'PaymentValidationAgent',
      model: 'gpt-4-turbo',
      instructions: `
        Verify payment status from webhook payload.
        Check for fraud indicators using provided signals.
        Return validation result with confidence score.
      `,
      tools: ['webhook-reader', 'fraud-checker'],
    },
    {
      id: 'inventory-manager',
      role: 'InventoryManagementAgent',
      model: 'gpt-4-turbo',
      instructions: `
        Check product availability in warehouse system.
        Reserve items for confirmed orders.
        Update inventory levels after shipment.
      `,
      tools: ['warehouse-api', 'inventory-db'],
    },
    {
      id: 'shipping-coordinator',
      role: 'ShippingCoordinationAgent',
      model: 'gpt-4-turbo',
      instructions: `
        Generate shipping labels via carrier API.
        Schedule pickup with logistics provider.
        Track shipment and update customer.
      `,
      tools: ['shipping-api', 'tracking-service'],
    },
  ],
  triggers: [
    {
      type: 'webhook',
      endpoint: '/webhooks/shopify/orders',
      filter: { event: 'orders/create' },
    },
  ],
};

export default orderProcessingWorkflow;

Запускаем workflow через CLI:

bashКопировать
# Загружаем конфиг и запускаем оркестратор
paperclip workflows deploy order-processing.yaml

# Мониторим выполнение
paperclip runs list --workflow order-processing --limit 10

# Смотрим логи конкретного run
paperclip runs logs run_7f3a2c1e --follow

Что происходит под капотом:

1. Webhook от Shopify приходит в Paperclip
2. Payment-validator проверяет платёж через Stripe API
3. При успехе — Inventory-manager резервирует товары
4. Shipping-coordinator создаёт Waybill и отправляет клиенту уведомление

Полный цикл занимает 2–5 секунд. За этим скрывается параллельное выполнение: агенты работают конкурентно, а не в очереди.

Мониторинг метрик:

yamlКопировать
# prometheus.yml — сбор метрик оркестратора
scrape_configs:
  - job_name: 'paperclip'
    static_configs:
      - targets: ['paperclip-server:3000']
    metrics_path: '/metrics'

В Grafana дашборд показывает:

• Время обработки задач
• Успешность выполнения
• Использование токенов
• Ошибки агентов

Интеграция с внешними сервисами

Paperclip работает по принципу «задал — получил». Определил цель, назначил агентам роли, и они начинают исполнять процессы без твоего участия. Вот как это выглядит на практике.

Пример: интеграция с Slack для управления проектами

Хотим, чтобы агенты отправляли обновления в канал #dev-updates. Настраиваем интеграцию:

typescriptКопировать
// integrations/slack.integration.ts
import { IntegrationConfig } from '@paperclipai/integrations';

const slackIntegration: IntegrationConfig = {
  name: 'slack-notifications',
  type: 'notification',
  credentials: {
    bot_token: process.env.SLACK_BOT_TOKEN,
    channel_id: '#dev-updates',
  },
  endpoints: {
    notify: async (message: string) => {
      const response = await fetch('https://slack.com/api/chat.postMessage', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.SLACK_BOT_TOKEN}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          channel: '#dev-updates',
          text: message,
          blocks: [
            {
              type: 'section',
              text: {
                type: 'mrkdwn',
                text: `*${message}*`,
              },
            },
          ],
        }),
      });
      return response.json();
    },
  },
};

export default slackIntegration;

Подключаем к агенту:

jsonКопировать
{
  "id": "project-updates-agent",
  "role": "ProjectManagementAgent",
  "integrations": ["slack-notifications"],
  "instructions": `
    Monitor project status changes.
    Post updates to #dev-updates channel.
    Include progress percentage and blockers.
  `
}

Webhook от внешних сервисов:

bashКопировать
# Принимаем вебхуки от GitHub
curl -X POST https://paperclip.yourdomain.com/webhooks/github \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: issues" \
  -d '{"action": "opened", "issue": {"title": "Fix auth bug", "url": "https://github.com/..."}}'

Работа с базами данных:

typescriptКопировать
// agents/data-analyst.agent.ts
import { createAgent } from '@paperclipai/core';

const dataAnalyst = createAgent({
  role: 'DataAnalysisAgent',
  model: 'gpt-4-turbo',
  tools: [
    {
      name: 'postgres-query',
      config: {
        connectionString: process.env.DATABASE_URL,
        ssl: true,
      },
    },
    {
      name: 'bigquery-reader',
      config: {
        projectId: 'your-project-id',
        dataset: 'analytics',
      },
    },
  ],
  instructions: `
    Analyze sales data from multiple sources.
    Generate insights and create visualizations.
    Store results in reporting database.
  `,
});

export default dataAnalyst;

Авторизация и безопасность:

yamlКопировать
# .paperclip/secrets.yaml
integrations:
  stripe:
    api_key: ${STRIPE_SECRET_KEY}
    webhook_secret: ${STRIPE_WEBHOOK_SECRET}
  sendgrid:
    api_key: ${SENDGRID_API_KEY}
  aws:
    access_key_id: ${AWS_ACCESS_KEY_ID}
    secret_access_key: ${AWS_SECRET_ACCESS_KEY}

# Шифруем секреты перед деплоем
paperclip secrets encrypt --config .paperclip/secrets.yaml

Интеграции работают как плагины. В Garry Tan's gstack можно найти аналогичные подходы к микросервисной архитектуре, где каждый сервис отвечает за одну интеграцию — так и здесь.

Диагностика проблем:

bashКопировать
# Тестим подключение
paperclip integrations test slack-notifications

# Проверяем статус
paperclip status --verbose

# Логируем ошибки
paperclip logs --level error --since 1h

Исправление ошибок URL в Paperclip AI на TypeScript — полезная статья, если агенты жалуются на недоступные эндпоинты.

Часто задаваемые вопросы

Как установить и запустить Paperclip локально для разработки?

Для локального запуска потребуется Node.js версии 18 или выше. Сначала клонируйте репозиторий, затем установите зависимости для серверной части командой npm install в корневой директории проекта, а затем — в подкаталоге web для фронтенда. Запустите бэкенд через npm run dev, а фронтенд — через npm run dev из директории web. Обе части должны работать параллельно, чтобы обеспечить полную функциональность платформы.

Какие технологии используется в стеке Paperclip и почему именно они выбраны?

Платформа построена на Node.js с TypeScript, что обеспечивает типобезопасность и скорость разработки на стороне сервера. Для реального времени используется Socket.io, который позволяет агентам и веб-интерфейсу обмениваться данными в режиме ожидания без необходимости постоянных запросов к API. Фронтенд реализован на React с использованием современных хуков и компонентов, что облегчает масштабируемость UI и интеграцию с потоками данных от агентов. Такой стек типичен для современных full-stack приложений, где требуется быстрая итерация и реактивность.

Как обеспечивается безопасность и изоляция между ИИ-агентами?

Paperclip позволяет подключать разные модели и провайдеров ИИ, но конфигурация каждого агента задаётся отдельно через JSON-схемы, что изолирует их поведение. В текущей версии платформа полагается на клиентскую валидацию и базовую аутентификацию через JWT-токены, выдаваемые сервером. Для продакшена рекомендуется добавить промежуточный слой сетевой изоляции (например, через reverse proxy с ограничением доступа) и ротацию ключей доступа к моделям. Также стоит обрабатывать все входящие данные от агентов на предмет валидации, чтобы предотвратить инъекции или некорректное поведение.

Можно ли использовать собственные ИИ-модели или провайдеров вместо встроенных?

Да, Paperclip рассчитан на гибкую интеграцию внешних провайдеров. В конфигурацию агента достаточно указать endpoint и заголовки для нужного API (OpenAI, Anthropic, локальные модели через Ollama и т. д.). Система не навязывает фиксированный набор моделей — вы самостоятельно задаёте параметры запроса, и агенты будут использовать указанный вами сервис. Это позволяет экспериментировать с разными моделями и оптимизировать стоимость запросов, выбирая самые подходящие решения для конкретных задач.

Как мониторится производительность и стоимость работы агентов?

Веб-интерфейс предоставляет дашборд с историей выполнения задач, временем ответа и использованием токенов. Для расчёта стоимости можно настроить отслеживание количества запросов и тарификацию через middleware на сервере. В текущей версии базового мониторинга больше, чем детальной аналитики по расходу ресурсов — если требуется продвинутый учёт, стоит интегрировать логирование в системы вроде Prometheus или просто собирать статистику из ответов API провайдеров.