Opening the book…
The renderer connection is what separates a productive AI workflow from a chatbot copy-paste trap. Without it, you are the middleman copying code between the agent and the browser. With it, the agent tests its own work and fixes problems before you ever see them. Think of the renderer as the agent's bench assay: it runs the experiment and reads the results without asking you to hold the pipette.
Prerequisites
Before connecting your agent to the renderer, confirm that you have the following in place:
- PG renderer running on localhost:3000 (see Setting Up the PG Renderer)
- Health check confirmed:
curl http://localhost:3000/healthreturns a response - Renderer API documentation included in your knowledge documents (see Knowledge Documents for AI Agents)
- Agent has permission to run terminal commands (Claude Code: approve when prompted; Codex: enabled by default in sandbox)
How the agent uses the renderer
Once connected, the agent follows a feedback loop that mirrors the way you would debug a problem by hand, just faster:
- Agent writes or edits a
.pgfile based on your prompt. - Agent sends the file to the renderer via HTTP POST to localhost:3000.
- Agent reads the JSON response and checks the
error_flagandpg_warnfields. - If errors are found, the agent reads the error messages and revises the code.
- Agent re-sends the revised file to the renderer.
- Steps 3 through 5 repeat until the response is clean (no errors, no warnings).
- Agent tests the problem with multiple random seeds to catch randomization bugs.
Most simple problems take three to eight iterations. The agent handles this loop automatically. You do not need to intervene unless the agent asks a clarifying question about the biology or the intended problem behavior.
What to tell the agent about the renderer
Include the following instructions in your prompt or knowledge documents so the agent knows how to interact with the renderer:
- The renderer URL is
http://localhost:3000. - Always include
_format=jsonin the POST request to get structured output. - Check the
error_flagfield in the response: 0 means success, 1 means errors. - Also check
pg_warnfor non-fatal warnings that may affect the problem. - Use a fixed seed (for example,
problemSeed=1234) during development for reproducible results. - After the problem works with one seed, test with at least three different seeds.
- Run the lint tool with the
-rflag for renderer-based lint checks (see Linting).
Typical timing
The table below shows approximate times from the video demonstration. These times are spent by the agent, not by you. While the agent works, you can review previous problems, prepare other materials, or take a break.
| Problem complexity | Expected time |
|---|---|
| Simple (one-part, fixed choices) | 3 to 5 minutes |
| Moderate (multi-part, basic randomization) | 5 to 10 minutes |
| Complex (multi-part, advanced randomization, color styling) | 15 to 20+ minutes |
In the video, the amino acid isoelectric point question took approximately 15 minutes including the color refinement pass. This is normal for a complex problem with multiple emphasis styles and randomized data.
For batch processing of many problems, see Scripting and Automation.
When the agent gets stuck
Agents occasionally hit a wall, especially with less common macros or unusual answer evaluators. When that happens, you can nudge the agent back on track without writing code yourself:
- Tell the agent to re-read its knowledge documents: "Read the skill again" or "Check the common mistakes document."
- Point the agent to a specific document when you can see what it is missing. For example: "The answer is in the RadioButtons section of the PG reference."
- Approve permission prompts promptly so the agent can continue its testing loop. A stalled permission dialog looks like a stuck agent, but the fix is just one click.
- If the agent starts searching your filesystem for example files, redirect it: "All the documents you need are in the skill. Do not search my hard drive."
For a full catalog of mistakes the agent may encounter, see Common Mistakes.
Apply it today
- Confirm your agent can reach the renderer: ask it to run
curl http://localhost:3000/healthand report the result. - Ask your agent to write and render a simple multiple-choice question and watch the feedback loop in action. A good first test: "Write a question that asks which monomer makes up cellulose, with four answer choices."
This page titled 8.3: Connecting AI Agents to the PG Renderer was last modified on Fri, 27 Feb 2026 14:55:20 GMT and is shared under a CC BY 4.0 license and was authored, remixed, and/or curated by Neil R. Voss.
The book could not be loaded just now.