Parseable Actions

ReAct is a format constraint. The action line is the product. Prefer JSON over ‘I will now Get-Job :)’.

intermediate20 min21 / 24Mark complete

ReAct (reason + act) is a format for a loop, not a religion:

Thought — optional scratchpad
Action — a tool name
Action Input — arguments
Your code runs the tool (runtime track — not this lesson)
Observation — stuffed back in as data
Repeat until Final Answer (or a stop tool)

The thought is not the product. The action line is what your parser must get right 100% of the time. Prefer JSON:

{"thought": "...", "tool": "get_job", "args": {"job_id": 17}}

over free-form “I will now Get-Job with id seventeen :)” which will break on Tuesday.

ReAct is a loop

The action line is the product. Thought is optional scratch.

The LLM structured-output lesson is the validator. This lesson is the prompt: ask for that object, show one legal example, refuse prose. Unknown tools stop the loop. Format in text, enforcement in code.

Classic ReAct lines (Action: / Action Input:) still exist in blogs. If you still use them, parse them once, then convert to JSON internally. Do not regex the live site on Tuesday. Do not accept both dialects in production — that is two contracts.

What the prompt must teach

One object per turn (or one object per parallel call, each validated)
tool is an enum from the enabled list
args is an object, not a sentence
finish / handoff are tools too, not vibes in the thought
Thoughts that say “I called get_job” without a tool message are lies. The transcript is the truth

Partial application is how you refund and fail to log: one valid object and one prose line in the same completion. Reject the turn. Retry once. Then handoff.

Parallel tool calls: validate each object against the allowlist. “The batch was mostly fine” is how a forbidden name sneaks through.

One legal example, two evals

Put one legal JSON example in the spec if the format is picky. Put a legal example last if you few-shot. Evals: valid JSON parses; unknown tool fails closed; prose fails closed. That is enough to catch most Tuesday breaks.

Do not few-shot a thought that claims a tool ran. That trains lies.

Live PythonOpen full playgroundpython

import json

TOOLS = {
    "get_job": lambda job_id: {"id": job_id, "status": "failed", "error": "vendor timeout"},
    "finish": lambda answer: {"final": answer},
    "handoff": lambda reason: {"handoff": reason},
}

def parse_action(text):
    obj = json.loads(text)
    if obj.get("tool") not in TOOLS:
        raise ValueError("unknown tool")
    if not isinstance(obj.get("args"), dict):
        raise ValueError("args")
    return obj

def run_loop(script, max_steps=4):
    for step, blob in enumerate(script, start=1):
        if step > max_steps:
            return "STOP: budget"
        turn = parse_action(blob)
        result = TOOLS[turn["tool"]](**turn["args"])
        print("step", step, turn["tool"], result)
        if turn["tool"] in {"finish", "handoff"}:
            return result
    return "STOP: no finish"

script = [
    '{"thought": "need the job", "tool": "get_job", "args": {"job_id": 17}}',
    '{"thought": "report it", "tool": "finish", "args": {"answer": "Job 17 failed: vendor timeout"}}',
]
print("OUT:", run_loop(script))
print("prose fails")
try:
    parse_action("I will now Get-Job :)")
except Exception as e:
    print(type(e).__name__, e)

Output

Run to execute this in your browser. Nothing is sent to a server.

What printed: step 1 runs get_job, step 2 finishes, OUT is the final dict. Prose raises JSONDecodeError. Unknown tools would raise ValueError. The prompt must teach this shape. The parser must not accept a smile.

This toy calls functions so you can see a loop. The lesson is still the format. How you implement get_job in production is a later track.

Walkthrough: the smile that broke Tuesday

The prompt allowed “JSON or a short plan.” Tuesday’s completion is “I will now Get-Job with id seventeen :)”. The parser has no object. You add regex. Wednesday it is XML. Two dialects are two contracts. The prompt that works asks for one object, shows one legal example last, and refuses prose. Evals: valid JSON; unknown tool fails; prose fails. Thoughts that claim a tool ran without a tool message are graded as lies against the transcript.

Parallel calls: validate each object. “Mostly fine” is how a forbidden name sneaks through.

What goes wrong if you skip this

You regex production. Partial batches refund and fail to log. Thoughts become the API. Classic ReAct blogs leak a second dialect into the live site. The runtime track cannot help if you cannot parse an action.

ReAct is a format constraint. Thought is optional. The action name and arguments are the product. Prefer one JSON object per turn with keys the parser already knows. Show one legal example. Refuse prose. Unknown tools fail closed. Thoughts that say “I called get_job” without a tool message are lies; the transcript is the truth.

If you still like Action: lines from a blog, parse them once and convert to JSON internally. Do not accept two dialects in production. Parallel calls: validate each object against the allowlist. “The batch was mostly fine” is an incident.

Evals for this lesson are small: valid JSON parses; unknown tool fails; smile-prose fails. That catches most Tuesdays.

Common mistakes

Mistake	Tuesday symptom	Fix
JSON or a plan	Smile prose	One object
Two dialects	Regex farm	One dialect
Thought as API	Lies in the tape	Parse tool, not poetry
Unvalidated parallel	One forbidden name	Validate each
Few-shot fake calls	Hallucinated tools	Never show a fake tool message

Write two golden completions: one legal object the parser accepts, one smile the parser rejects, one unknown tool name the parser rejects. That is the format suite. If those three are not in CI, you will learn the dialect drift from production. The prompt can show one legal example. The suite must show the illegal ones. Format in text, enforcement in code, proof in evals.

How agents use this

One legal example in the spec. Two evals: valid JSON, unknown tool. Parallel calls: validate each object. Thoughts are optional logs. The action name and arguments are the API. If a completion contains two objects, validate both or reject the turn. If it contains a smile, reject. Retry once with “return only the object.” Then handoff. Do not grow a second parser for “almost JSON.” Tuesday’s dialect is not your product. The format is. Keep the parser boring: loads, enum, args object, stop. Anything else is a fail. That boring parser is the product. Fancy recovery is how you accept a smile on Thursday.

Watch out:Thoughts that say “I called get_job” without a tool message are lies. The transcript is the truth.

Check your understanding

What must the parser get right 100% of the time in ReAct?

The poetry of the thought
The action name and arguments (preferably as JSON)
The font
The vendor’s blog

Prompts for Agents

Up next

Tool Docs in the Prompt