Add futures positioning to an energy research agent

An energy headline can explain what happened without explaining how market participants were positioned beforehand. An agent that reads both can ask a better question: does this new supply story challenge an already crowded view, or reinforce a view that was barely represented?

CFTC Commitments of Traders data adds that second perspective to deep.navy. The positioning_search and positioning_fetch tools expose contract discovery and weekly positioning reports. Combine them with EIA inventories, US weather and source reporting to produce a research brief. The result is a hypothesis to evaluate, not evidence that a trade will make money.

Start with one precisely identified market

Ask positioning_search for crude oil in the Disaggregated futures-only report. Select the contract using its returned code, market name, exchange and units. Several markets can mention the same commodity: a similarly named contract is not automatically the one you intended.

{
	"name": "positioning_search",
	"arguments": {
		"reportType": "REPORT_TYPE_DISAGGREGATED_FUTURES_ONLY",
		"query": "crude oil",
		"limit": 20
	}
}

Use positioning_fetch with that exact contract code and report type for a bounded history. Follow nextPageToken with the same filters if you need more observations. The positioning guide contains runnable examples and the request limits.

For example, CFTC code 067651 identifies WTI-PHYSICAL in the verified dataset. This request selects twelve available reports; it is an example request, not a captured response. Verify the returned market metadata before using it for your own instrument mapping.

{
	"name": "positioning_fetch",
	"arguments": {
		"reportType": "REPORT_TYPE_DISAGGREGATED_FUTURES_ONLY",
		"contractCode": "067651",
		"limit": 12
	}
}

For managed money, retain reported long, short and spreading positions. Net positions are long minus short. A rising net position could reflect more longs, fewer shorts, or both; show those components before offering an interpretation. The tool’s derived net and net change are arithmetic, not CFTC trading recommendations.

Compare a market with its own history. Raw contract counts are not dollar exposure, and different markets have different contract sizes. If you calculate net positions as a share of open interest, check that the denominator is present and positive, and record the formula. Label that ratio as your calculation. Calling it “crowded” requires a stated comparison window and criterion.

The CFTC explanatory notes explain trader groups and spreading. Groups describe classes of traders; they do not reveal an individual fund’s strategy or establish the motive behind every position.

Add an independent view of supply and demand

Use energy_search to discover the supported inventory series, then fetch observations through energy_fetch. This illustrative request retrieves twelve weekly US crude-oil stock observations:

{
	"name": "energy_fetch",
	"arguments": {
		"dataset": "petroleum/stoc/wstk",
		"column": "value",
		"frequency": "weekly",
		"filters": [{ "facet": "series", "values": ["WCESTUS1"] }],
		"limit": 12
	}
}

Keep the returned units and period. A stock change is not a surprise relative to market expectations unless you supply a separately sourced expectations series. The EIA API documentation explains periods and series selection; the energy guide describes the subset available here.

For a weather hypothesis, supply a verified list of relevant US facilities. Request weather_forecast and weather_alerts at those coordinates, then check operator notices and news. A forecast near a refinery is an exposure question, not proof of an outage. The weather-and-energy walkthrough shows how to connect physical locations to evidence without guessing from company headquarters.

Put the clocks next to the claims

COT generally describes Tuesday’s positions and is released on Friday at 3:30 p.m. US Eastern, with schedule exceptions. Use the official release schedule. A report date is not a publication timestamp, and retrievedAt records when the tool obtained the data.

Do not describe today’s weather alert as an explanation for positions measured before that alert. Write the actual sequence: positioning as of one date, inventory observation for another period, and the weather information available at the research cutoff. A mismatched clock should remain visible in the brief.

Give the agent a bounded assignment

Build a weekly crude-oil research brief. Discover and verify the exact futures-only CFTC contract. Retrieve managed-money longs, shorts, spreading, net positions and open interest for the stated comparison window. Add the supported EIA inventory series and weather evidence for my verified facilities. Record report dates, observation periods, source links and retrieval times. Show two competing explanations for the combination, the evidence that would distinguish them, and the next scheduled check. Separate calculations from interpretation. Do not infer named funds, market expectations or price reactions from these datasets.

Request a table with five columns: observation, source, relevant time, possible implication, and alternative explanation. Finish with one falsifiable question, such as whether a reported operational disruption is confirmed by an operator and followed by the specified inventory change. Define the threshold and horizon before observing the outcome.

Your agent application’s scheduler should refresh COT and EIA after relevant releases. Native monitors support news, EDGAR and supported geo searches; they do not watch COT releases. A news monitor can trigger an A2A research task that fetches positioning as context.

Connect an agent and start with one market and one brief. Supply licensed price data, instrument mappings and transaction-cost assumptions separately when evaluating a trading rule. A useful research artifact makes those dependencies and uncertainties inspectable.