Separate the generated core from maintained behavior
A generated client is useful for request shapes, response types, and operation names. It should be reproducible from a pinned OpenAPI artifact and generator version. Keep those files in a dedicated directory and regenerate them as a unit. Hand edits create a fork that disappears the next time the generator runs.
Place authentication, timeout policy, request IDs, retries, logging, and domain-friendly methods in a small maintained wrapper. That layer can expose only the operations your product uses and translate HTTP failures into typed application errors. It also creates a stable seam for tests when the generated library changes.
Turn contract drift into a visible review
Store the exact OpenAPI file or its checksum with the project. In continuous integration, regenerate the client and fail if the output differs from the committed version. A maintainer then reviews the contract and generated diff together, updates fixtures, and approves the new version intentionally.
Do not ask an AI tool to resolve a large generated diff without constraints. First classify changes as additive, behavioral, or breaking. Verify that the server actually supports new operations and that coverage exists. Then regenerate tests and inspect error types, nullable fields, enum changes, and pagination behavior before allowing the wrapper to expose anything new.
- Pin the contract artifact and generator version.
- Regenerate deterministically in CI.
- Review contract, client, wrapper, and fixtures as one change.
- Keep secrets and runtime policy outside generated source.
A handoff your agent can actually follow
Treat an AI agent as a planner and transformer, not as the database. Give it a narrow task, the exact resources it may call, the response fields it may quote, and a stop condition for missing data. Keep bearer credentials in the server-side tool implementation rather than in the prompt, transcript, browser, or generated source file.
The handoff below is deliberately operational. It asks for evidence before prose, makes uncertainty visible, and keeps the model inside the current football API contract. Adapt the output format to your product, but preserve the rules about stable IDs, UTC timestamps, freshness, and error handling.
Generate the client from the pinned /openapi.json artifact.
Do not edit generated files by hand.
Add a small maintained wrapper for credentials, timeouts, error mapping, and telemetry.
Fail CI when regeneration produces an unreviewed diff.What the human reviewer still owns
Automation can verify schemas and repeatable checks, but publication and product decisions still need a person. Review the selected competition, season, team, and match IDs; confirm that the time window matches the user’s question; and read the final answer against the retrieved JSON. A fluent explanation is not evidence that the underlying call was correct.
For time-sensitive football AI, record when the source was ingested and when the agent retrieved it. If the workflow cannot establish those timestamps, qualify the result instead of presenting it as current. The same rule applies to unavailable capabilities: do not quietly substitute fixtures or results for lineups, player statistics, odds, expected goals, injuries, or live events.
- Confirm every quoted fact appears in the retained API response.
- Exercise the empty, 401, 404, 429, and 503 paths before launch.
- Keep model interpretation separate from source facts in logs and user-facing output.
- Review type changes and removed enum values as API changes, not as formatting noise from the generator.
Continue with the contract, not a guess
Start with the public contract and coverage ledger, then move into implementation only when the capability you need is marked available. The related guide gives your next agent-first pattern without requiring an undocumented endpoint.