013: Агент/Области видимости

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

Ограничивая контекст, области видимости повышают безопасность, предотвращают случайные утечки данных и помогают ИИ-модели (LLM) сосредоточиться, что делает её работу более предсказуемой и экономичной. Этот контролируемый контекст также является ключом к модульности, позволяя таким компонентам, как Идеи и Действия, быть по-настоящему автономными и многоразовыми. Этот документ объясняет, как работает этот паттерн и как он взаимодействует с другими возможностями агента.

Предоставление и запрос контекста

Схема свойства _scopes определяет, как предоставляется контекст: статически (заранее) или динамически (по запросу) во время выполнения.

• Статические области видимости (Предоставление контекста): Схема _scopes может быть постоянным значением (const), что означает, что контекст предоставляется заранее. Разработчик жёстко прописал, какую именно информацию может видеть инструмент.

  {
    "_scopes": {
      "const": ["input"]
    }
  }
  

• Динамические области видимости (Запрос контекста): Схема _scopes может быть более гибкой, позволяя запрашивать контекст. ИИ-модель сама решает, какие из доступных областей ей нужны для создания Вызова.

  {
    "_scopes": {
      "type": "array",
      "items": {
        "enum": ["state", "input"]
      }
    }
  }
  

  Этот динамический подход особенно полезен, когда в процесс вовлечён человек для утверждения действий, что обеспечивает дополнительный уровень прозрачности и контроля.

Роль областей видимости в композиции вызовов

Свойство _scopes — это главный механизм управления контекстом, доступным для Вызова. Оно действует как «белый список», фильтруя родительскую среду и предоставляя для выполнения ограниченный и сфокусированный набор данных. Этот контролируемый контекст играет ключевую роль в обработке Вызова и адаптируется для поддержки модели композитного выполнения, где сочетаются разные возможности: явная логика, экземплирование и модульность.

• • 002: Агент/Инструмент.

  Скрытое выполнение: При стандартном скрытом выполнении _scopes служат «подсказкой», чтобы сфокусировать внимание ИИ-модели на нужных частях родительского контекста. Это скорее рекомендация, а не строгий фильтр, но она крайне важна для повышения надёжности и экономичности работы ИИ, так как убирает шум от лишних данных. См. пример Устранение неоднозначности с помощью областей видимости.

• • 003: Агент/Действие.

  Явное выполнение (_activity): Когда Вызов подкреплён детерминированным Действием, роль областей видимости становится более прямой. Контекст из области видимости целиком передаётся функции Действия как дополнительный параметр. Это даёт Действию полный доступ к нужным данным, даже если ИИ не использовал их напрямую для генерации основных параметров Вызова. См. пример Предоставление контекста для Действия.

• • 011: Агент/Экземплирование

  Экземплирование (_instance): При запросе с несколькими экземплярами, когда агент обрабатывает пакет однотипных объектов, области видимости начинают «знать» об экземплярах. Протокол гарантирует, что Вызов, нацеленный на конкретный экземпляр, получит контекст только для этого экземпляра. Это критически важно для сохранения целостности данных и предотвращения «утечки» контекста между параллельными выполнениями.

• • 012: Агент/Делегат

  Изолированное делегирование (_delegate): Когда Вызов делегируется внешнему Делегату, области видимости становятся стражами контекста. Они определяют, что из родительской среды будет добавлено к собственному внутреннему контексту делегата, создавая итоговый контекст для изолированного подзапроса. Ничто из родительской среды не будет доступно, если это явно не указано в области видимости, что обеспечивает полную инкапсуляцию. См. примеры Определение области видимости для контекста Делегата и Экземплирование с делегатами в областях видимости.

_scopesСвойство _scopes — это мост, по которому Вызов получает контекст. В этой главе мы показали, как этот единый механизм адаптируется к разным режимам выполнения — от мягкого направления скрытого вызова до строгого определения всего контекста для делегированного. Именно эта гибкость делает его основой для создания сложных, безопасных и модульных агентных систем.

Примеры

[
  {
    "type": "state",
    "currentUser": { "id": "user_A", "name": "Алиса" }
  },
  {
    "type": "input",
    "mentionedUser": { "id": "user_B", "name": "Борис" },
    "instruction": "Отправь приветственное сообщение упомянутому выше пользователю."
  }
]

{
  "_tool": "sendMessage",
  "_scopes": ["input"],
  "recipientId": "user_B",
  "message": "Добро пожаловать, Борис!"
}

{
  "_tool": "logEvent",
  "_scopes": ["state"],
  "eventName": "user_login"
}

// Параметры деструктурируются для прямого доступа к 'eventName'
// из вызова и 'state' из контекста области видимости.
Activity.register('logEvent', async ({ eventName }, { state }) => {
  const userId = state.userId;
  await analytics.track(eventName, { userId });
});

// Контекст и вызов Оркестратора
[
  {
    "type": "state",
    "articleText": "Длинная и сложная статья..."
  },
  {
    "_tool": "summarizeArticle",
    "_delegate": "SummarizerAgent",
    "_scopes": ["state"]
  }
]

// Контекст, созданный для подзапроса Summarizer
[
  // Внутренний контекст Summarizer
  {
    "type": "system",
    "message": "Ты — эксперт в составлении кратких summarizing."
  },
  // Добавляется контекст из родительской области видимости
  {
    "type": "state",
    "articleText": "Длинная и сложная статья..."
  }
]

// РОДИТЕЛЬСКИЙ КОНТЕКСТ
[
  { "type": "state", "_instance": "①", "text": "Привет" },
  { "type": "state", "_instance": "②", "text": "Bonjour" }
]

// РЕШЕНИЕ ИИ-МОДЕЛИ
{
  "calls": [
    {
      "_tool": "translate",
      "_delegate": "translatorDelegate",
      "_instance": "①",
      "_scopes": ["state"]
    },
    {
      "_tool": "translate",
      "_delegate": "translatorDelegate",
      "_instance": "②",
      "_scopes": ["state"]
    }
  ]
}

// КОНТЕКСТ ДЛЯ ДЕЛЕГАТА ①
[
  { "type": "system", "message": "Ты — переводчик." },
  { "type": "state", "text": "Привет" }
]

// КОНТЕКСТ ДЛЯ ДЕЛЕГАТА ②
[
  { "type": "system", "message": "Ты — переводчик." },
  { "type": "state", "text": "Bonjour" }
]