Типизированный вызов сценария

CodeGraph экспортирует типизированный Python-контракт выполнения сценария с проверкой ответственного сотрудника. Он подходит для внутрипроцессной интеграции, уже связанной с управляемой задачей CodeGraph. Агентскому или удалённому клиенту следует использовать зарегистрированный интерфейс MCP или API; настройка описана в руководстве оператора MCP.

Типизированный запрос удобен, когда приложение повторяет одну операцию: например, готовит документацию интерфейса для каждой принятой задачи. Приложение задаёт сценарий и область работы, а CodeGraph проверяет выбранного сотрудника и возвращает результат со сведениями о выполнении. Эти сведения помогают связать ответ с задачей и разобрать отказ без повторного поиска контекста.

Минимальный запрос

Пример выполняется из корня локального репозитория CodeGraph в Python-окружении с установленными зависимостями; подготовка описана в руководстве CLI. Для рабочего сценария нужны зарегистрированный проект, принятая задача, настроенные сервисы контекста и провайдер LLM. Конфигурацию экземпляра описывает руководство настройки. Замените <project-key>, <namespace> и <task-id> значениями принятой задачи, а source://current-contract — ссылкой на текущий исходник. Перед вызовом проверьте настройки сервисов проекта и выбранного провайдера LLM.

Для сценария документации нужен актуальный CPG выбранного проекта. Проверьте ревизию графа и завершение его обновления по разделу «Подготовка проекта». Затем выполняйте запрос для принятой задачи: сценарий использует этот граф при получении контекста кода.

from src.digital_employees.runtime.scenarios import (
    RoleBoundScenarioInvocationRequest,
    invoke_role_bound_scenario_request,
)

request = RoleBoundScenarioInvocationRequest(
    query="Обнови документацию интерфейса для выбранной задачи.",
    context={
        "project_key": "<project-key>",
        "namespace": "<namespace>",
        "task_id": "<task-id>",
        "source_refs": ["source://current-contract"],
    },
    employee_id="codegraph_docs",
    scenario_id="scenario_03",
    event_type="docs_memory_sync_start",
    execution_source="customer_in_process_integration",
)

result = invoke_role_bound_scenario_request(request)

Пример намеренно связан с сотрудником документации и его сценарием. Другой сценарий допустим только тогда, когда это разрешено политикой сотрудника и правилами задачи.

Обязательный контекст управления

Перед выполнением функция вызова проверяет три поля context:

• project_key — зарегистрированный проект CodeGraph;
• namespace — его пространство имён;
• task_id — активная задача, к которой относится работа.

При неполной области вызов закрывается с ошибкой role_bound_scenario_contract_missing:<fields>. Затем runtime разрешает или проверяет ответственного employee_id, его право на сценарий, формирует свидетельства вызова и выполняет предварительную проверку.

При отказе восстановите область задачи, политику сотрудника, событие или указанные в сообщении свидетельства. Затем повторите тот же типизированный вызов.

Поля запроса

Если scenario_id не задан, runtime классифицирует запрос. Для воспроизводимой автоматизации обычно лучше явный идентификатор: так сохраняется выбранный сценарий и проще диагностируется отказ политики.

Контракт результата

Возвращается словарь выбранного сценария. Обёртка ролевого вызова добавляет общие поля:

• scenario_id — канонический выбранный сценарий;
• intent — связанное с ним намерение;
• classification_method — способ выбора;
• metadata.role_bound_scenario_invocation — сотрудник, событие, источник выполнения, workflow, ссылка evidence и статус preflight;
• metadata.scenario_invocation_evidence — полный объект evidence вызова.

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

Обработка ошибок

Считайте стабильный префикс категорией, но сохраняйте полное сообщение в диагностике:

• role_bound_scenario_contract_missing — нет обязательной области задачи;
• role_bound_scenario_preflight_blocked — предварительная проверка события или свидетельств не пройдена;
• role_bound_employee_has_no_policy — для сотрудника отсутствует политика;
• role_bound_scenario_manual_only — сценарий допускает только ручное выполнение;
• role_bound_employee_not_allowed_for_scenario — сотрудник и сценарий несовместимы;
• role_bound_scenario_retired — сценарий выведен из эксплуатации;
• role_bound_scenario_not_registered — обработчик сценария не зарегистрирован.

Пример обработки на границе интеграции:

class IntegrationError(RuntimeError):
    """Ошибка вызова CodeGraph на границе интеграции."""


try:
    result = invoke_role_bound_scenario_request(request)
except RuntimeError as exc:
    if str(exc).startswith("role_bound_"):
        raise IntegrationError(f"CodeGraph отклонил сценарий: {exc}") from exc
    raise

if result.get("error"):
    raise IntegrationError(f"CodeGraph не выполнил сценарий документации: {result['error']}")

Этот фрагмент заменяет последнюю строку вызова в первом примере и использует тот же request. Для проверки ошибки без запуска LLM создайте запрос с context={}: вызов выдаст role_bound_scenario_contract_missing до получения контекста и выполнения сценария. Сохраните полное сообщение: оно перечисляет недостающие поля. После восстановления условий повторите запрос с той же областью задачи и выбранным сотрудником.

Конкурентность и побочные эффекты

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

Редактирование файлов, публикация и изменение состояния выполняются через носитель задачи, ответственную роль и разрешения соответствующего контракта.