A Hands-On Introduction to Agentic AI

Chatbots vs. Agentic Tools

Chatbots

Agentic Tools

Codex

Claude Code

They may look similar on the surface, but the capabilities underneath are very different.

A Concrete Comparison: ChatGPT vs. Codex

Same prompt, different result:

"What is the unemployment rate for African Americans in Santa Barbara County?"

ChatGPT

It could not verify the county-level rate directly.

It could not call the Census ACS API.

"I couldn't verify a current official county unemployment rate for African Americans specifically in Santa Barbara County. The standard local unemployment series for Santa Barbara County is published overall, not by race..."

Follow-up in same ChatGPT session

can you actually call the Census API here please to get the data please?

"I tried, but I can't complete a live direct Census API fetch from this environment: the direct outbound call is blocked here."

View the exact ChatGPT exchange I used ↗

Codex

Agent workflow

Searched ACS variable catalog → found S2301_C04_013

Queried ACS 1-year → 16.0% (±9.7 MOE)

Queried ACS 5-year → 13.5% (±3.4 MOE)

Compared margins of error → recommended 5-year estimate

Result

16.0%

2024 ACS 1-year

±9.7 MOE

13.5%

2020-2024 ACS 5-year

±3.4 MOE

Recommendation: use the 5-year estimate for a more stable county-level figure.

The key difference is the loop: try something, inspect what came back, then adjust.

Codex workflow transcriptDownload .md

Full assistant updates, tool calls, and raw outputs from the session that produced the answer.

User

What is the unemployment rate for African Americans in Santa Barbara County?

You’re asking for a county-by-race unemployment figure, which usually is not in the official monthly BLS county series. I’m checking the economic-data workflow first so I can give you the right measure and label it correctly.

Explored 1 file

Command

sed -n '1,220p' /Users/christopherlee/.codex/skills/econ-raw-apis/SKILL.md

Invocation metadata

{
  "yield_time_ms": 1000,
  "max_output_tokens": 4000
}

Raw tool result

Command: /bin/zsh -lc "sed -n '1,220p' /Users/christopherlee/.codex/skills/econ-raw-apis/SKILL.md"
Chunk ID: 0bdcea
Wall time: 0.0000 seconds
Process exited with code 0
Original token count: 1094
Output:
---
name: econ-raw-apis
description: Raw access to BEA, BLS, FRED, and Census ACS public economic data APIs. Use when the user asks to explore, query, or download economic time series, demographic data, or metadata from these sources, or needs help constructing API requests for them.
---

# Econ Raw APIs

## Overview
Provide direct, high-freedom API access to BEA, BLS, FRED, and Census ACS without prescribing a specific client or tooling. Use any HTTP client and write just-in-time code as needed.

## Authentication
Read API keys from the shell environment. Keys are typically stored in `~/.zshenv`:
- `BEA_API_KEY`
- `BLS_API_KEY`
- `FRED_API_KEY`
- `CENSUS_API_KEY`

If a key is unavailable in the current shell, source `~/.zshenv` before making requests.

## API Endpoints And Key Usage
- BEA base endpoint: `https://apps.bea.gov/api/data/` (include `UserID` in query parameters).
- BLS API v2 expects `registrationkey` in the request payload or query parameters.
- FRED API v1 expects `api_key` as a query parameter; FRED API v2 expects `Authorization: Bearer <api_key>` in the request header.
- Census ACS base endpoint: `https://api.census.gov/data/` (include `key` in query parameters). Common datasets: ACS 5-Year (`/acs/acs5`), ACS 1-Year (`/acs/acs1`).

## Usage Guidelines
- Prefer raw HTTP requests (`curl`, Python `requests`/`httpx`, or JavaScript `fetch`).
- Avoid hard-coding secrets; pull keys from env vars.
- If a request fails with 4xx/5xx, capture and show the response body.
- Use light caching and exponential backoff when rate-limited.
- When uncertain about parameters or dataset/series IDs, query metadata endpoints first.

## Network Escalation Policy (Required)
- For any command that calls BEA, BLS, FRED, or Census endpoints, run with `sandbox_permissions: "require_escalated"` on the first attempt.
- Do not try a non-escalated network call first.
- Always include a short `justification` tied to the user task.
- Provide a scoped `prefix_rule` for repeat API access when appropriate (for example, `["curl","-sS","-X","POST","https://api.bls.gov/publicAPI/v2/timeseries/data/"]`).
- Keep non-network steps (local parsing, formatting, file reads) in normal sandbox mode.
- Treat inability to resolve host/connect as expected in sandboxed mode; default to escalated network execution for API requests.

## Shell-Safe Curl Patterns (`zsh`)
- Do not nest single-quoted JSON inside an outer single-quoted `zsh -lc '...'` command. This breaks quoting and can trigger `zsh` glob errors like `no matches found`.
- Prefer one of these safe patterns when sending JSON payloads:

```bash
# Never use this anti-pattern (outer single-quoted zsh -lc with inner single quotes):
/bin/zsh -lc 'curl ... --data '{"seriesid":["LAUCN060830000000003"]}' | jq -r '.status''
# Typical failures: unmatched '   OR   zsh: no matches found
```

```bash
# Canonical safe exec_command template (copy/paste)
source ~/.zshenv 2>/dev/null
payload="$(jq -nc --arg key "$BLS_API_KEY" \
  '{"seriesid":["LAUCN060830000000003"],"startyear":"2025","endyear":"2026","registrationkey":$key}')"
curl -sS -X POST "https://api.bls.gov/publicAPI/v2/timeseries/data/" \
  -H "Content-Type: application/json" \
  --data "$payload" \
| jq -r '.status, (.message|join("; ")), .Results.series[0].data[0].value'
```

```bash
# Pattern A: Build JSON with jq, then pass as --data "$payload"
payload="$(jq -nc --arg key "$BLS_API_KEY" \
  '{"seriesid":["LAUCN060830000000003"],"startyear":"2025","endyear":"2026","registrationkey":$key}')"
curl -sS -X POST "https://api.bls.gov/publicAPI/v2/timeseries/data/" \
  -H "Content-Type: application/json" \
  --data "$payload"
```

```bash
# Pattern B: Heredoc with quoted delimiter (no shell interpolation inside JSON body)
curl -sS -X POST "https://api.bls.gov/publicAPI/v2/timeseries/data/" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{"seriesid":["LAUCN060830000000003"],"startyear":"2025","endyear":"2026"}
JSON
```

- If you must run via `/bin/zsh -lc ...`, use outer double quotes and escape inner double quotes, or move JSON generation to `jq -nc` to avoid brittle manual escaping.
- Validate requests by piping to `jq` and checking `status`, `message`, and `Results`.

## Notes
- If a key is missing, ask the user to create it and add it to their env.
- Prefer source API documentation when endpoint behavior is unclear.

Searched web for Census ACS S2301B unemployment rate Black or African American alone county API

Search queries

- Census ACS S2301B unemployment rate Black or African American alone county API - ACS table B23025B Black or African American alone employment status county API

No separate result payload was captured in the local session log.

Opened web page https://api.census.gov/data/2021/acs/acs5/subject/groups/S2301.html

{
  "type": "web_search_call",
  "status": "completed",
  "action": {
    "type": "open_page",
    "url": "https://api.census.gov/data/2021/acs/acs5/subject/groups/S2301.html"
  }
}

I found the Census variable for “Black or African American alone” unemployment rate. Next I’m pulling the latest county estimate and checking whether the 1-year or 5-year ACS is the better basis for Santa Barbara County.

Background terminal finished with curl -sS "https://api.census.gov/data/2024/acs/acs1/subject?get=NAME,S2301_C04_013E,S2301_C04_013M&for=county:083&in=state:06"

Command

curl -sS "https://api.census.gov/data/2024/acs/acs1/subject?get=NAME,S2301_C04_013E,S2301_C04_013M&for=county:083&in=state:06"

Invocation metadata

{
  "yield_time_ms": 1000,
  "max_output_tokens": 1200
}

Raw tool result

Command: /bin/zsh -lc 'curl -sS "https://api.census.gov/data/2024/acs/acs1/subject?get=NAME,S2301_C04_013E,S2301_C04_013M&for=county:083&in=state:06"'
Chunk ID: 83fa0e
Wall time: 0.7398 seconds
Process exited with code 0
Original token count: 31
Output:
[["NAME","S2301_C04_013E","S2301_C04_013M","state","county"],
["Santa Barbara County, California","16.0","9.7","06","083"]]

Background terminal finished with curl -sS "https://api.census.gov/data/2024/acs/acs5/subject?get=NAME,S2301_C04_013E,S2301_C04_013M&for=county:083&in=state:06"

Command

curl -sS "https://api.census.gov/data/2024/acs/acs5/subject?get=NAME,S2301_C04_013E,S2301_C04_013M&for=county:083&in=state:06"

Invocation metadata

{
  "yield_time_ms": 1000,
  "max_output_tokens": 1200
}

Raw tool result

Command: /bin/zsh -lc 'curl -sS "https://api.census.gov/data/2024/acs/acs5/subject?get=NAME,S2301_C04_013E,S2301_C04_013M&for=county:083&in=state:06"'
Chunk ID: cdaccf
Wall time: 0.7610 seconds
Process exited with code 0
Original token count: 31
Output:
[["NAME","S2301_C04_013E","S2301_C04_013M","state","county"],
["Santa Barbara County, California","13.5","3.4","06","083"]]

Background terminal still running with curl -sS "https://api.census.gov/data/2024/acs/acs1/subject/groups/S2301.html" | rg -n "S2301_C04_013(E|M)"

Command

curl -sS "https://api.census.gov/data/2024/acs/acs1/subject/groups/S2301.html" | rg -n "S2301_C04_013(E|M)"

Invocation metadata

{
  "yield_time_ms": 1000,
  "max_output_tokens": 1200
}

Raw tool result

Command: /bin/zsh -lc 'curl -sS "https://api.census.gov/data/2024/acs/acs1/subject/groups/S2301.html" | rg -n "S2301_C04_013(E|M)"'
Chunk ID: 09c22f
Wall time: 1.0008 seconds
Process running with session ID 70316
Original token count: 0
Output:

Session ID: `70316`

The latest ACS 1-year estimate exists, but it’s very noisy for this subgroup. I’m confirming the metadata and likely will report the 2024 5-year estimate as the more stable county-by-race figure, while noting the newer 1-year number.

Background terminal finished with curl -sS "https://api.census.gov/data/2024/acs/acs1/subject/groups/S2301.html" | rg -n "S2301_C04_013(E|M)"

Command

curl -sS "https://api.census.gov/data/2024/acs/acs1/subject/groups/S2301.html" | rg -n "S2301_C04_013(E|M)"

Invocation metadata

{
  "session_id": 70316,
  "chars": "",
  "yield_time_ms": 1000,
  "max_output_tokens": 1200
}

Raw tool result

Command: /bin/zsh -lc 'curl -sS "https://api.census.gov/data/2024/acs/acs1/subject/groups/S2301.html" | rg -n "S2301_C04_013(E|M)"'
Chunk ID: f4354b
Wall time: 0.0000 seconds
Process exited with code 0
Original token count: 482
Output:
1503:<td><a href="/data/2024/acs/acs1/subject/variables/S2301_C04_013E.json" name="S2301_C04_013E">S2301_C04_013E</a></td><td>Estimate!!Unemployment rate!!Population 16 years and over!!RACE AND HISPANIC OR LATINO ORIGIN!!Black or African American alone</td><td>Employment Status</td><td>predicate-only</td><td><a href="/data/2024/acs/acs1/subject/groups/.html"></a></td><td>0</td><td>float</td><td><a href="/data/2024/acs/acs1/subject/groups/S2301.html">S2301</a></td>
1506:<td><a href="/data/2024/acs/acs1/subject/variables/S2301_C04_013EA.json" name="S2301_C04_013EA">S2301_C04_013EA</a></td><td>Annotation of Estimate!!Unemployment rate!!Population 16 years and over!!RACE AND HISPANIC OR LATINO ORIGIN!!Black or African American alone</td><td>Employment Status</td><td>predicate-only</td><td><a href="/data/2024/acs/acs1/subject/groups/.html"></a></td><td>0</td><td>string</td><td><a href="/data/2024/acs/acs1/subject/groups/S2301.html">S2301</a></td>
1509:<td><a href="/data/2024/acs/acs1/subject/variables/S2301_C04_013M.json" name="S2301_C04_013M">S2301_C04_013M</a></td><td>Margin of Error!!Unemployment rate!!Population 16 years and over!!RACE AND HISPANIC OR LATINO ORIGIN!!Black or African American alone</td><td>Employment Status</td><td>predicate-only</td><td><a href="/data/2024/acs/acs1/subject/groups/.html"></a></td><td>0</td><td>float</td><td><a href="/data/2024/acs/acs1/subject/groups/S2301.html">S2301</a></td>
1512:<td><a href="/data/2024/acs/acs1/subject/variables/S2301_C04_013MA.json" name="S2301_C04_013MA">S2301_C04_013MA</a></td><td>Annotation of Margin of Error!!Unemployment rate!!Population 16 years and over!!RACE AND HISPANIC OR LATINO ORIGIN!!Black or African American alone</td><td>Employment Status</td><td>predicate-only</td><td><a href="/data/2024/acs/acs1/subject/groups/.html"></a></td><td>0</td><td>string</td><td><a href="/data/2024/acs/acs1/subject/groups/S2301.html">S2301</a></td>

I have the rate. I’m pulling the underlying Black labor-force counts as a sanity check so I can tell you whether this is based on a small denominator and avoid overstating precision.

Background terminal finished with curl -sS "https://api.census.gov/data/2024/acs/acs5?get=NAME,B23025B_001E,B23025B_002E,B23025B_004E,B23025B_005E&for=county:083&in=state:06"

Command

curl -sS "https://api.census.gov/data/2024/acs/acs5?get=NAME,B23025B_001E,B23025B_002E,B23025B_004E,B23025B_005E&for=county:083&in=state:06"

Invocation metadata

{
  "yield_time_ms": 1000,
  "max_output_tokens": 1200
}

Raw tool result

Command: /bin/zsh -lc 'curl -sS "https://api.census.gov/data/2024/acs/acs5?get=NAME,B23025B_001E,B23025B_002E,B23025B_004E,B23025B_005E&for=county:083&in=state:06"'
Chunk ID: a36986
Wall time: 0.3040 seconds
Process exited with code 0
Original token count: 10
Output:
error: unknown variable 'B23025B_001E'

Background terminal finished with curl -sS "https://api.census.gov/data/2024/acs/acs1?get=NAME,B23025B_001E,B23025B_002E,B23025B_004E,B23025B_005E&for=county:083&in=state:06"

Command

curl -sS "https://api.census.gov/data/2024/acs/acs1?get=NAME,B23025B_001E,B23025B_002E,B23025B_004E,B23025B_005E&for=county:083&in=state:06"

Invocation metadata

{
  "yield_time_ms": 1000,
  "max_output_tokens": 1200
}

Raw tool result

Command: /bin/zsh -lc 'curl -sS "https://api.census.gov/data/2024/acs/acs1?get=NAME,B23025B_001E,B23025B_002E,B23025B_004E,B23025B_005E&for=county:083&in=state:06"'
Chunk ID: 40b389
Wall time: 0.2755 seconds
Process exited with code 0
Original token count: 10
Output:
error: unknown variable 'B23025B_001E'

Background terminal finished with curl -sS "https://api.census.gov/data/2024/acs/acs5/groups/B23025B.html" | rg -n "B23025B_00[1245]E"

Command

curl -sS "https://api.census.gov/data/2024/acs/acs5/groups/B23025B.html" | rg -n "B23025B_00[1245]E"

Invocation metadata

{
  "yield_time_ms": 1000,
  "max_output_tokens": 1400
}

Raw tool result

Command: /bin/zsh -lc 'curl -sS "https://api.census.gov/data/2024/acs/acs5/groups/B23025B.html" | rg -n "B23025B_00[1245]E"'
Chunk ID: 078532
Wall time: 0.2601 seconds
Process exited with code 1
Original token count: 0
Output:

Background terminal still running with curl -sS "https://api.census.gov/data/2024/acs/acs5/variables.html" | rg -n "B23025|C23002B|B23025B|C23002"

Command

curl -sS "https://api.census.gov/data/2024/acs/acs5/variables.html" | rg -n "B23025|C23002B|B23025B|C23002"

Invocation metadata

{
  "session_id": 71148,
  "chars": "",
  "yield_time_ms": 1000,
  "max_output_tokens": 2000
}

Raw tool result

Command: /bin/zsh -lc 'curl -sS "https://api.census.gov/data/2024/acs/acs5/variables.html" | rg -n "B23025|C23002B|B23025B|C23002"'
Chunk ID: 273248
Wall time: 5.0023 seconds
Process running with session ID 71148
Original token count: 0
Output:

Session ID: `71148`

Background terminal still running with curl -sS "https://api.census.gov/data/2024/acs/acs1/variables.html" | rg -n "B23025|C23002B|B23025B|C23002"

Command

curl -sS "https://api.census.gov/data/2024/acs/acs1/variables.html" | rg -n "B23025|C23002B|B23025B|C23002"

Invocation metadata

{
  "session_id": 38215,
  "chars": "",
  "yield_time_ms": 1000,
  "max_output_tokens": 2000
}

Raw tool result

Command: /bin/zsh -lc 'curl -sS "https://api.census.gov/data/2024/acs/acs1/variables.html" | rg -n "B23025|C23002B|B23025B|C23002"'
Chunk ID: 7cd54f
Wall time: 5.0016 seconds
Process running with session ID 38215
Original token count: 0
Output:

Session ID: `38215`

Opened web page https://api.census.gov/data/2024/acs/acs1/subject?for=county%3A083&get=NAME%2CS2301_C04_013E%2CS2301_C04_013M&in=state%3A06

{
  "type": "web_search_call",
  "status": "completed",
  "action": {
    "type": "open_page",
    "url": "https://api.census.gov/data/2024/acs/acs1/subject?for=county%3A083&get=NAME%2CS2301_C04_013E%2CS2301_C04_013M&in=state%3A06"
  }
}

The Census metadata confirms this is the right variable. I’m pulling the subgroup size now; if the Black 16+ population is small, that explains why the 1-year estimate swings and why the 5-year number is the safer answer.

Background terminal finished with curl -sS "https://api.census.gov/data/2024/acs/acs1/subject?get=NAME,S2301_C01_013E,S2301_C02_013E,S2301_C03_013E,S2301_C04_013E,S2301_C01_013M,S2301_C02_013M,S2301_C03_013M,S2301_C04_013M&for=county:083&in=state:06"

Command

curl -sS "https://api.census.gov/data/2024/acs/acs1/subject?get=NAME,S2301_C01_013E,S2301_C02_013E,S2301_C03_013E,S2301_C04_013E,S2301_C01_013M,S2301_C02_013M,S2301_C03_013M,S2301_C04_013M&for=county:083&in=state:06"

Invocation metadata

{
  "yield_time_ms": 1000,
  "max_output_tokens": 1400
}

Raw tool result

Command: /bin/zsh -lc 'curl -sS "https://api.census.gov/data/2024/acs/acs1/subject?get=NAME,S2301_C01_013E,S2301_C02_013E,S2301_C03_013E,S2301_C04_013E,S2301_C01_013M,S2301_C02_013M,S2301_C03_013M,S2301_C04_013M&for=county:083&in=state:06"'
Chunk ID: b215fc
Wall time: 0.5145 seconds
Process exited with code 0
Original token count: 67
Output:
[["NAME","S2301_C01_013E","S2301_C02_013E","S2301_C03_013E","S2301_C04_013E","S2301_C01_013M","S2301_C02_013M","S2301_C03_013M","S2301_C04_013M","state","county"],
["Santa Barbara County, California","7216","59.6","46.2","16.0","1128","9.8","11.1","9.7","06","083"]]

Background terminal finished with curl -sS "https://api.census.gov/data/2024/acs/acs5/subject?get=NAME,S2301_C01_013E,S2301_C02_013E,S2301_C03_013E,S2301_C04_013E,S2301_C01_013M,S2301_C02_013M,S2301_C03_013M,S2301_C04_013M&for=county:083&in=state:06"

Command

curl -sS "https://api.census.gov/data/2024/acs/acs5/subject?get=NAME,S2301_C01_013E,S2301_C02_013E,S2301_C03_013E,S2301_C04_013E,S2301_C01_013M,S2301_C02_013M,S2301_C03_013M,S2301_C04_013M&for=county:083&in=state:06"

Invocation metadata

{
  "yield_time_ms": 1000,
  "max_output_tokens": 1400
}

Raw tool result

Command: /bin/zsh -lc 'curl -sS "https://api.census.gov/data/2024/acs/acs5/subject?get=NAME,S2301_C01_013E,S2301_C02_013E,S2301_C03_013E,S2301_C04_013E,S2301_C01_013M,S2301_C02_013M,S2301_C03_013M,S2301_C04_013M&for=county:083&in=state:06"'
Chunk ID: 611989
Wall time: 0.4901 seconds
Process exited with code 0
Original token count: 66
Output:
[["NAME","S2301_C01_013E","S2301_C02_013E","S2301_C03_013E","S2301_C04_013E","S2301_C01_013M","S2301_C02_013M","S2301_C03_013M","S2301_C04_013M","state","county"],
["Santa Barbara County, California","6952","64.6","51.0","13.5","475","5.2","5.7","3.4","06","083"]]

For Santa Barbara County, the latest available Census estimate for `Black or African American alone` is `16.0%` unemployed among people age 16+ in the labor force, from the `2024 ACS 1-year` data. That estimate has a large margin of error: `±9.7` percentage points. Source: [2024 ACS 1-year query](https://api.census.gov/data/2024/acs/acs1/subject?get=NAME,S2301_C04_013E,S2301_C04_013M&for=county:083&in=state:06), [variable definition](https://api.census.gov/data/2024/acs/acs1/subject/groups/S2301.html).

For a more stable county-level figure, the `2020-2024 ACS 5-year` estimate is `13.5%` with margin of error `±3.4` percentage points. Source: [2024 ACS 5-year query](https://api.census.gov/data/2024/acs/acs5/subject?get=NAME,S2301_C04_013E,S2301_C04_013M&for=county:083&in=state:06).

This is ACS survey data, not an official monthly BLS county unemployment rate by race.

3 / 12