Inspiration

Administrative notices can be intimidating when the reader is still learning Japanese and does not know which details matter first. Mado was inspired by the gap between receiving a notice and arriving at the right public counter with useful questions. We wanted an assistant that reduces uncertainty without pretending to replace an official or a qualified adviser. Scope: synthetic notices, no legal advice, no submission/payment, and no sensitive-identifier entry.

What it does

Mado reads a Japanese administrative notice, extracts its stated deadline and prerequisites, and pairs the proposed next action with allow-listed official evidence. It produces a bilingual checklist, a Japanese counter-question card, an RFC 5545 calendar file, and a citations/audit manifest. Cases with missing or conflicting facts stop for clarification, while ready cases require approval before any artifact is built. The current demo never submits a form, makes a payment, or fills an identifier.

How we built it

We modeled the workflow as a real Strands Graph with extraction and official-source research running in parallel before a reviewer joins their results. Conditional edges route incomplete cases to clarification and ready cases to a human-approval hook whose snapshot expires if the review changes. Specialized source-verifier and form-specialist agents are exposed through an agent-as-tool boundary, while deterministic offline services keep the committed evaluation reproducible. A safety hook blocks sensitive identifiers, submission tools, payment actions, and malformed action payloads. The model layer is explicit and pluggable: the live smoke runner completed all three samples through LiteLLM with Gemini 3.5 Flash Lite, while the retained Strands BedrockModel path remains fail-closed and never silently falls back to the mock provider.

Challenges

The hardest design problem was making the output useful while keeping a strict line between guidance and administrative action. We also had to preserve provenance through parallel branches and ensure the reviewer waited for both extraction and official research. Calendar bytes, approval expiry, URL allow-listing, and offline repeatability required precise tests rather than presentation-only demos. Bedrock validation is still blocked by account-region eligibility and model allow-listing, which are external account dependencies; we therefore report the successful LiteLLM/Gemini run separately instead of implying that Bedrock was exercised.

Accomplishments

We completed an offline end-to-end graph for three synthetic notice types and generated four reviewable artifacts for every ready case. The test suite verifies parallel overlap and join behavior, clarification routing, immutable approval, safety blocks, exact ICS serialization, and all three samples. Every cited source is restricted to a .go.jp or municipality domain. We also completed a live functional smoke run of all three samples through LiteLLM/Gemini; each audit manifest records provider=litellm, offline=false, and external_writes=false. The same runner retains a cost-gated Bedrock path that stops cleanly on missing credentials or model access.

What we learned

An administrative assistant becomes more trustworthy when uncertainty is a visible workflow state instead of hidden model behavior. Parallel agents help only when their evidence is joined explicitly and their outputs remain traceable. Human approval is most meaningful when it is tied to an immutable review snapshot rather than a generic confirmation button. Offline deterministic fixtures made safety and graph behavior much easier to inspect.

What's next

Next we will validate the retained Bedrock path when an eligible AWS account and model allow-listing are available. We plan to add more synthetic notice patterns, multilingual explanations, and user-tested clarification prompts without expanding into legal conclusions. A future offline evaluation will compare extracted deadlines and citations against a hand-reviewed synthetic benchmark. Submission, payment, and sensitive-identifier entry will remain outside Mado's scope.

Built With

• amazon-web-services
• gemini
• litellm
• python
• strands-agents