# Build a Cited Football Match Research Agent in Python

A research agent is credible when every factual sentence can be traced back to a retained match record and retrieval time.

By Stats API Editorial · Reviewed by Claude automated editorial review · Published 2026-09-05 · Last reviewed 2026-10-27

Canonical URL: https://stats-api.com/blog/python-football-match-research-agent

## Create the evidence record before the narrative

The Python workflow should first resolve stable competition and team IDs, query a bounded match set, and save the structured response with its parameters, request ID, and retrieval timestamp. Assign an internal evidence reference to each retained record. Only then should the model receive the subset needed to answer the research question.

This order matters because citations created after prose tend to become decorative. When the evidence records exist first, the model can attach a reference to each factual claim and the application can verify that reference. A citation should identify the match or collection record and the retrieval, not point vaguely to a homepage.

## Keep match facts separate from analysis

Scores, kickoff times, statuses, teams, and competition membership can be source facts when present in the retained JSON. Statements about momentum, tactical strength, expected performance, or likely outcomes are interpretations unless backed by another explicit source. Store and render them in separate sections so readers understand the difference.

The current contract includes per-match team and player statistics, lineups, timelines and injury observations where covered. The match statistics schema includes nullable expected_goals; that field is not a prediction endpoint or a guarantee that every match has an observed value. Odds are available only through the dedicated odds endpoints, whose responses carry their own availability and expiry fields. There is no prediction endpoint. A research agent must preserve provenance and keep its conclusions separate from the returned football observations.

**Research record shape**

```text
evidence_id
query_parameters
request_id
retrieved_at
resource_ids
source_facts[]
inferences[]
citations[]
limitations[]
```

## 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.

**Agent instruction**

```text
Use Python server-side and read STATS_API_KEY from the environment.
Store each retrieved response with request parameters and retrieved_at.
Generate citations that point to the retained evidence record.
Place any comparison or interpretation in a separate inferences section.
```

## 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, keep available ingestion observations separate from the time the agent retrieved the response. Match updated_at records a normalized change observed by Stats API; it is not an upstream event timestamp or a freshness guarantee. Inspect coverage and nullable fields for each requested capability. Do not substitute fixtures or results for missing detail data, and do not invent odds or predictions.

- 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.
- Open every generated citation and confirm the cited record supports the exact sentence, not merely the general topic.

## 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.

- [Read the football API documentation](https://stats-api.com/docs)
- [Review the football API product contract](https://stats-api.com/football-api)
- [Read the related agent-first guide](https://stats-api.com/blog/strict-json-football-agent-handoffs)