From a first agent demo to an inspectable workflow

A Korean-first reference implementation that makes evidence, authority, approval, and evaluation visible after a developer's first successful OpenAI agent run.

Live replay demo ↗ · GitHub repository ↗

Problem

A first model output is easy to produce. A real team immediately faces harder questions: What data did the agent read? Which tool can act? Is the evidence sufficient? How does an observed failure become a durable improvement? This project prioritizes those inspectable control points over feature count.

System

• A Korean policy-support agent built with the OpenAI Agents SDK
• One model-visible tool that reads only synthetic approved documents
• Structured outputs for answer, citations, confidence, review reason, and proposed action
• Zero external action tools; every proposal remains review_required
• Question-specific recorded replay, a live OpenAI API path, and a public Vercel deployment
• Korean and English quickstarts, threat model, limitations, and GitHub Actions verification

Engineering judgment

I did not add agents to make the diagram look sophisticated. This workflow needs one reasoning owner and one read-only retrieval boundary. Stable policy lives in AGENTS.md, conditional procedures live in four focused skills, and deterministic mechanics live in scripts and tests.

A failure that changed the workflow

The first offline run returned a data-handling section for an unknown parental-leave question. The only shared token was the generic Korean verb meaning ‘to use.’ The unit test had also drifted from the natural user sentence. I preserved the failed report, moved the exact fixture into a regression test, filtered generic query tokens, and reran every case.

What the simulated usability review changed

Three independent 15-minute Korean developer persona simulations found that changing the visible question still replayed the same remote-work answer. I label these as simulations, not real-user research. I fixed the contract with three question-specific replays, blocked arbitrary replay input, added a recorded-output banner, direct source links, feedback-storage copy, a narrow sensitive-input warning, and regression tests.

Verified today

• Repository, Python syntax, fixture format, and basic secret-pattern checks pass
• Eighteen offline unit tests pass
• All five transparent offline policy fixtures pass
• All five live gpt-5-mini agent fixtures pass with OpenAI Agents SDK 0.18.3
• The installed OpenAI Agents SDK imports the agent, tool, and structured output
• The public Vercel replay preserves question-to-evidence alignment and the local feedback path works

Not yet proven

One five-case live run and three AI persona simulations do not establish production reliability or successful onboarding by real Korean developers. Adversarial and held-out evaluation plus real clean-machine sessions remain separate validation steps. This sample is not presented as a privacy or security compliance implementation.

Developer Experience thesis

I do not want to make agents look more autonomous. I want developers to understand what they can trust, what they must review, and how to move from a first call to a repeatable workflow. I treat recurring developer friction as product input that should return to the right layer: code, documentation, examples, evaluation, or the product surface itself.