USA CPI Checker - Lucid Agent

A Lucid Agent that retrieves the latest USA Consumer Price Index (CPI) data from the Bureau of Labor Statistics (BLS) API.

Overview

This agent provides real-time access to the US Consumer Price Index for All Urban Consumers (CPI-U), which is the primary measure of inflation used by the Federal Reserve and commonly reported in news media.

Features

Real-time CPI Data: Fetches the latest monthly CPI value from the BLS API
Health Monitoring: Check BLS API connectivity status
Type-Safe: Full TypeScript support with Zod schema validation
Comprehensive Testing: Unit tests for BLS client and integration tests for agent endpoints
Error Handling: Robust error handling for API failures, network issues, and invalid responses

Installation

# Install dependencies
bun install

Configuration

Copy the example environment file and configure as needed:

cp .env.example .env

Environment Variables

Variable	Description	Required
`AGENT_NAME`	Agent name (default: `usa-cpi-checker`)	No
`AGENT_VERSION`	Agent version (default: `1.0.0`)	No
`AGENT_DESCRIPTION`	Agent description	No
`PORT`	Server port (default: `3000`)	No
`BLS_API_KEY`	BLS API key (increases rate limits)	No

BLS API Key (Optional)

While the BLS API works without an API key, having one increases your rate limits and enables additional features. Register for a free API key at: https://data.bls.gov/registrationEngine/

Usage

Start the Agent

# Development mode with hot reload
bun run dev

# Production mode
bun run start

Available Endpoints

Agent Manifest

curl http://localhost:3000/.well-known/agent.json

List Entrypoints

curl http://localhost:3000/entrypoints

Get Latest CPI

curl -X POST http://localhost:3000/entrypoints/getLatestCPI/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": {}}'

Example response:

{
  "output": {
    "value": 315.605,
    "year": "2024",
    "month": "December",
    "period": "M12",
    "seriesId": "CUSR0000SA0",
    "description": "Consumer Price Index for All Urban Consumers (CPI-U): All Items in U.S. City Average",
    "formattedSummary": "CPI Index: 315.605 for December 2024"
  },
  "usage": {
    "total_tokens": 0
  }
}

Check BLS Connection Health

curl -X POST http://localhost:3000/entrypoints/checkBLSConnection/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": {}}'

Health Check

curl http://localhost:3000/health

API Reference

Entrypoints

`getLatestCPI`

Fetches the latest US Consumer Price Index (CPI) data.

Input: None required

Output:

Field	Type	Description
`value`	`number`	The CPI index value
`year`	`string`	The year of the data
`month`	`string`	The month name
`period`	`string`	BLS period code (e.g., M12 for December)
`seriesId`	`string`	BLS series ID
`description`	`string`	Description of the CPI series
`formattedSummary`	`string`	Human-readable summary

`checkBLSConnection`

Checks if the BLS API is accessible and returning valid data.