Tool Contract Testing в 2026: как проверять tools до того, как агент сломает workflow

Короткая версия

Хороший tool contract testing в 2026 обычно проверяет:

1. Schema validity
2. Argument normalization
3. Failure behavior
4. Side-effect safety
5. Agent-visible output shape

Что особенно важно

• tool tests должны проверять не только JSON Schema, но и semantics;
• error responses должны быть предсказуемыми и machine-readable;
• side effects лучше тестировать отдельно от read-only paths;
• изменение tool schema без regression tests почти гарантированно сломает agent loop.

Почему агент может выглядеть плохо, даже если reasoning модели хороший?

1. Tool contract шире, чем просто schema

Даже идеальная JSON Schema не отвечает на все вопросы:

• что значит semantically valid input;
• какие значения допустимы по бизнес-логике;
• какие поля mutually exclusive;
• какие ошибки recoverable;
• что считается safe retry.

Поэтому contract test должен проверять и структуру, и operational semantics.

2. Какие слои стоит тестировать

Schema layer

• required fields;
• enums;
• ranges;
• string formats;
• nested object shapes.

Semantic layer

• существует ли entity;
• допустимо ли действие для текущего state;
• соответствует ли запрос policy.

Output layer

• стабильные поля ответа;
• machine-readable status;
• понятные error codes;
• evidence or ids для следующего шага.

Side-effect layer

• идемпотентность;
• deduplication;
• retry safety;
• partial write handling.

3. Failure paths важнее happy path

Особенно полезно тестировать:

• missing required field;
• wrong enum;
• stale object id;
• permission denied;
• timeout;
• partial success;
• duplicate request.

Именно на них агент принимает самые дорогие и самые нестабильные решения.

4. Error surface должна быть проектируемой

Плохой tool error:

• длинный prose-текст без кода;
• разные формулировки одного и того же сбоя;
• отсутствует retry hint;
• непонятно, был ли side effect.

Хороший tool error помогает агенту выбрать следующее действие, а не только человеку понять, что "что-то пошло не так".

5. Contract tests особенно важны при schema evolution

Когда tool меняется, часто ломаются:

• field names;
• enum values;
• optional vs required;
• output keys;
• error codes.

Именно поэтому schema versioning и contract tests должны идти вместе.

6. Что команды ломают чаще всего

Prose-only outputs

Агенту трудно стабильно парсить результат.

Hidden side effects

Tool выглядит безопасной, но при ошибке уже успевает изменить state.

No invalid-input fixtures

Команда тестирует только идеальный payload.

Unclear retry semantics

Агент не понимает, можно ли повторять вызов.

Schema changes without downstream tests

Agent loop quietly degrades после маленького API change.

7. Какие метрики полезны

Минимальный tool contract dashboard обычно включает:

• schema validation failure rate;
• semantic rejection rate;
• ambiguous error rate;
• duplicate side-effect rate;
• retry success rate;
• downstream agent recovery rate.

Пример tool result envelope

{
  "status": "retryable_error",
  "error_code": "RATE_LIMITED",
  "message": "Temporary rate limit",
  "side_effect_committed": false,
  "retry_after_seconds": 15
}

Практический checklist

1. Test schema, semantics and outputs separately
2. Add fixtures for invalid and partial-failure cases
3. Make error shapes machine-readable
4. Expose retry and side-effect semantics explicitly
5. Re-run contract tests on every schema change

Практический совет: если агент регулярно "ошибается" на одном и том же tool path, сначала смотрите не на модель, а на contract. Очень часто проблема живёт именно там.