Как пользоваться Harness

Соберите версию

Перед созданием проверьте, нет ли подходящего определения. workspace_id — это project_id проекта Flownix.

harness.list({ workspace_id })
harness.create({ workspace_id, name: "architecture-review", description: "Оценка архитектурных вариантов", type: "review_board" })
harness.create_version({ harness_id, changelog: "первая версия", input_schema: { type: "object" }, default_budget: { max_run_duration_seconds: 3600, max_tokens: 200000 } })
harness.add_role({ harness_version_id, key: "reviewer", name: "Reviewer", objective: "Вернуть обоснованный вердикт", output_schema: { type: "object", required: ["summary"] } })
harness.add_workflow_node({ harness_version_id, type: "review", name: "review", config: { role_key: "reviewer", lease_seconds: 900 }, retry_policy: { max_attempts: 2 }, timeout_seconds: 1800 })
harness.add_workflow_node({ harness_version_id, type: "end", name: "done" })
harness.connect_workflow_nodes({ harness_version_id, from_node_id, to_node_id })
harness.set_context_policy({ harness_version_id, include: ["run_input", "role", "predecessors"], exclude: ["flow_nodes"], max_tokens: 16000 })
harness.set_output_schema({ harness_version_id, output_schema: { type: "object", required: ["summary"] } })
harness.validate({ harness_version_id })
harness.publish({ harness_version_id })

Схемы выхода исполняются. output_schema роли (JSON Schema 2020-12) проверяется на каждом work.complete этой роли, output_schema версии — на шагах, ведущих в end: несоответствие отвергается с output.schema_violation, аренда остаётся у агента, и он повторяет вызов с исправленным output. Некорректная JSON Schema отвергается с output.schema_invalid и блокирует публикацию.

harness.set_context_policy задаёт, что вернёт work.get_context: секции include — run_input, role, predecessors, all_steps; exclude — ключи верхнего уровня выходов; max_tokens — лимит на выходы шагов (байты JSON / 4, первыми отбрасываются самые ранние, признак — context_truncated). Без политики агент получает run_input, role и predecessors.

Опубликованная версия неизменяема. Изменения собираются в новой пустой версии либо через harness.clone, который копирует полное определение под новым именем.

Ветвление, циклы и советы

Условие ребра проверяет выход исходного шага. Для ветвления используйте явный outcome:

harness.connect_workflow_nodes({ harness_version_id, from_node_id: review_node_id, to_node_id: approved_node_id, condition: { field: "outcome", op: "eq", value: "approved" } })

condition, loop, create_flow_nodes и end работают без агента. У loop есть config.max_iterations, необязательный config.exit_condition и исходящие ветки continue / exit. Типы parallel_group и transform принимаются, но не исполняются; для параллельности используйте fan-out рёбер.

Нодам debate, vote и judge одного совета задайте общий config.deliberation_key. Правила голосования находятся в config ноды vote: method, quorum, threshold, allow_abstain, timeout_seconds. Лимит раундов debate задаётся config.max_rounds.

Запустите и наблюдайте

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

harness.start_run({ workspace_id, harness_id, harness_version_id, title: "Review AF-FEAT-10", input: { question: "Готов ли дизайн?" }, source_node_ids: [feature_node_id] })
harness.get_run({ run_id })
harness.list_runs({ workspace_id, source_node: "AF-FEAT-10" })

harness.get_run возвращает шаги, выходы, work items, расход и остаток бюджета. При превышении лимита длительности, числа work items, заявленных токенов или стоимости run завершается с budget.exceeded.

Участие внешнего агента

work.list_available({ run_id, role_key: "reviewer" })
work.claim({ work_item_id, agent_id: "reviewer-1" })
work.get_context({ work_item_id })
work.heartbeat({ work_item_id })
work.complete({ work_item_id, outcome: "approved", result_artifact_ids: ["AF-DOC-12"], output: { summary: "Готово" }, usage: { input_tokens: 12000, output_tokens: 1800, cost_usd: 0.15 } })

Для ноды vote возьмите ballot_id и варианты из work.get_context, затем вызовите council.cast_vote или council.abstain: голос сам закрывает work item, поэтому work.complete не нужен. Судья читает общее совещание через council.get_deliberation и закрывает шаг вызовом council.submit_judgement.

Подтверждение человеком и создание нод Flownix

harness.list_pending_approvals({ run_id }) объясняет, почему run находится в waiting_for_user; ответить может только человек в веб-приложении. На каждом пути к create_flow_nodes должна стоять нода human_gate. Предыдущий агент возвращает output.flow_nodes, а рантайм создаёт ноды через обычные проверки Flownix. Повтор идемпотентен по (run, key).

Исполняются только политики категории tools и только для вызовов work.* / council.*. Остальные категории сохраняются с предупреждением policy.not_enforced и не ограничивают shell, файлы или другие сервисы внешнего агента.