temporality
Изменить страницу↗
Инженерные документы

ТЗ: межагентное взаимодействие и обнаружение участников Saga

#1. Цель

Добавить возможность агентам обнаруживать участников совместной работы в рамках текущей Saga и напрямую взаимодействовать с агентами-коллегами.

Реализация должна опираться на существующие механизмы Temporality --- Saga, delegation, Journal и steering. Не создавать отдельную универсальную messaging-подсистему и не унифицировать взаимодействие человека и агента.

#2. Область работ

Добавить инструмент get_collaborators() и инструмент ask_agent() с поддержкой синхронного и асинхронного режимов.

Существующий ask_human() сохраняется как отдельный механизм HITL. Его модель форм, валидации, каналов коммуникации и получения ответов не изменяется.

#Разделение механизмов

Механизм Назначение

get_collaborators() Обнаружение участников текущей Saga --- людей и агентов

ask_agent() Взаимодействие агента с другим агентом

#ask_human() Взаимодействие агента с человеком через HITL

get_collaborators() только предоставляет информацию об участниках. Он не маршрутизирует сообщения и не заменяет ask_human() или ask_agent().

#3. get_collaborators()

#Назначение

Возвращать список людей и агентов, участвующих в текущей Saga, чтобы агент мог определить, к кому обратиться.

#Состав результата

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

Пример:

{
  "collaborators": [
    {
      "id": "agent:coder-01",
      "kind": "agent",
      "role": "Coder",
      "task": "Implement API",
      "status": "running",
      "run_id": "run-123"
    },
    {
      "id": "human:analyst-01",
      "kind": "human",
      "role": "Business Analyst",
      "task": "Requirements analysis"
    }
  ]
}

#Правила

#4. ask_agent()

#Назначение

Позволить агенту отправить другому агенту запрос, поручение или структурированные данные без обязательного участия Lead.

Инструмент должен поддерживать два режима:

#Предлагаемый интерфейс

ask_agent({
  to: "agent:coder-01",
  type: "compatibility.check",
  payload: {
    api_change: "..."
  },
  mode: "async"
})

Параметры:

Параметр Обязательный Назначение

to Да Идентификатор агента из доступной области Saga

type Да Тип запроса/сообщения

payload Да Текстовые или структурированные данные

#mode Нет wait или async; значение по умолчанию определить при проектировании

Не ограничивать payload обычным текстом. Предусмотреть передачу структурированных данных и ссылок на доступные артефакты с соблюдением существующих правил доступа.

#Синхронный режим (wait)

  1. Создать запрос и передать его адресату.
  2. Получатель обрабатывает запрос в рамках своего агентского выполнения.
  3. Отправитель ожидает ответ.
  4. Ответ возвращается непосредственно как результат вызова ask_agent().

Ожидание должно иметь timeout. Истечение timeout не должно приводить к потере уже зарегистрированного запроса.

#Асинхронный режим (async)

  1. Создать устойчиво идентифицируемый запрос.
  2. Передать его адресату.
  3. Вернуть отправителю request_id и состояние pending, не ожидая ответа.
  4. Получатель принимает запрос через существующий механизм steering.
  5. Ответ получателя сохраняется и связывается с исходным запросом.
  6. Ответ доставляется отправителю через steering и включается во входной контекст следующего хода.
  7. Отправителю не требуется опрашивать адресата или самостоятельно проверять готовность ответа.

Пример немедленного результата:

{
  "request_id": "req-456",
  "status": "pending"
}

Пример ответа:

{
  "request_id": "req-456",
  "status": "completed",
  "from": "agent:coder-01",
  "payload": {
    "compatible": false,
    "reason": "The API change breaks backward compatibility."
  }
}

#Требования к асинхронному взаимодействию

#5. Внутренняя реализация

Использовать существующие механизмы:

Запрос должен иметь устойчивую идентичность и сохраняемое состояние. Конкретную схему хранения и механизм восстановления выбрать после изучения текущих реализаций Journal, Saga и steering.

Не вводить отдельный брокер сообщений, самостоятельную mailbox-подсистему, presence, комнаты, подписки и универсальный чат-протокол без доказанной необходимости.

Temporal Signals могут использоваться как внутренний механизм пробуждения workflow, но не должны быть единственным хранилищем запроса или ответа.

#6. Границы доступа и безопасность

#7. Тестирование

Добавить unit- и интеграционные тесты.

Сценарий Ожидаемый результат

Вызов get_collaborators() Возвращаются доступные участники текущей Saga, включая вложенные делегации

В Saga есть люди и агенты Оба типа присутствуют с корректным kind

Агент обращается к агенту в режиме Ответ возвращается в текущем вызове wait

Агент обращается к агенту в режиме Возвращается request_id, async отправитель продолжает работу

Получатель отвечает позднее Ответ поступает отправителю через steering в следующем ходе

Несколько параллельных запросов Ответы сопоставляются по request_id

Worker/kernel перезапускается до Запрос и связь с ответом ответа восстанавливаются

Получатель завершился или Отправитель получает явное недоступен терминальное состояние

Повторная доставка запроса Не вызывает неконтролируемого повторного выполнения

Попытка обратиться к чужому агенту Запрос отклоняется проверкой доступа

Получатель занят другой работой Запрос ставится в steering и не прерывает текущий ход

#ask_human() Продолжает работать независимо, без регрессий HITL

#8. Критерии готовности

#9. Что не входит в задачу

Итог: реализовать минимальный механизм Human-Agent Collaboration на уровне Saga: обнаружение участников через get_collaborators() и межагентное взаимодействие через ask_agent(), используя существующие delegation, Journal и steering.