---
name: sudoku-agent-api
description: Use the Sudoverse Agent API to help users solve Sudoku with verified human-style hints, candidate eliminations, explanations, and step-by-step traces. Apply when a user provides a Sudoku board, asks for a hint, wants to learn a solving technique, or requests an AI-assisted Sudoku solution.
---

# Sudoku Agent Api

Use the Sudoverse Agent API as the source of truth for Sudoku deductions. The API is deterministic and backed by the Rust human solver. The assistant should explain the returned action conversationally, but must not invent a technique, placement, candidate elimination, or proof that the API did not return.

## Configuration

Use this public API base URL, or an explicitly configured replacement from the host environment:

- Default: `https://sudoku-agent-api.playfulbit.com`
- Fallback during migration: `https://sudoverse-agent-api.dandanusa.workers.dev`
- Optional override: `SUDOKU_AGENT_API_URL`

The health and solver endpoints are public. Do not ask the user to provide an API key.

Read [references/api.md](references/api.md) when constructing requests or interpreting response fields.

## Core workflow

1. Obtain the board. Accept an 81-character grid using `0` for blank cells or a Sudoku image. For an image, use vision/OCR to transcribe the 9×9 grid, preserving givens and blanks. If any cell is ambiguous, show the suspected transcription or ask the user before calling the API.
2. Normalize the board to exactly 81 digits and call `POST /v1/solve/next` for a single hint.
3. Present the returned action and a lightweight visual in the user's preferred level of detail:
   - For a placement, state the cell and digit.
   - For an elimination, state which candidate can be removed and from which cell or cells. Do not turn an elimination into a placement.
   - Name the returned technique and paraphrase `explanationText` without changing its logical meaning.
   - Use `highlights`, `targetCells`, and `links` to describe the relevant pattern when useful.
   - Prefer an inline static SVG/HTML board that highlights the returned cells and links. Use a short animation only when it clarifies the sequence; use a GIF only if the chat cannot render HTML/SVG.
   - When the user supplied an image, annotate the current board rather than returning a reconstructed unhighlighted board.
   - When a hosted visual is useful, call `POST /v1/previews` with the same verified grid and link the returned `previewUrl` as “Open the visual explanation”. Mention that the link expires after 24 hours.
4. Ask whether the user wants to apply the move, see a more detailed explanation, or continue to the next hint. For a guided conversation, request a fresh board after the user applies a move or use the trace endpoint for a precomputed sequence.
5. Use `POST /v1/solve/trace` only when the user asks for multiple steps, a complete guided solution, or a lesson sequence. Respect the requested `maxSteps` and the API's maximum of 100.

## Response handling

- `progress`: explain the returned next action.
- `solved`: congratulate the user briefly and report that no further action is needed.
- `stalled`: explain that the human solver found no safe supported technique from the current state; do not guess.
- `max_steps`: explain that the trace was intentionally capped and offer to continue from the returned grid.
- `INVALID_GRID`, `INVALID_BOARD`, or `INVALID_MAX_STEPS`: explain the input problem and request a correction.
- `SOLVER_ERROR` or a network failure: say that the verified solver could not be reached. Do not silently replace it with an unverified manual solution.

The API's `candidates` map describes the solver's current candidate state. Treat it as supporting data, not as proof by itself; use the returned action, explanation, and proof fields when explaining why a move is valid.

## Conversational behavior

- Default to one hint at a time so the user can learn and remain in control.
- Give progressive explanations: start with the technique and action, then expand the links or candidate pattern if requested.
- Preserve the user's board state exactly. Do not alter givens or assume that a blank means an unknown digit from an earlier turn.
- For image boards, distinguish confidently recognized digits from uncertain cells. Never silently fill an unclear cell.
- If the user asks for a direct answer, provide the API-verified action concisely; if they ask to learn, explain the reasoning before revealing the action when the response supports that presentation.
- Do not claim that the API validates arbitrary proposed moves; the current public API exposes next-hint and trace analysis only.

## Agent/tool integration

When building an AI tool around this skill, expose two tools corresponding to the API endpoints:

- `solve_sudoku_next(grid)` for one verified action.
- `solve_sudoku_trace(grid, maxSteps)` for a bounded sequence.
- `create_sudoku_preview(grid)` for a short-lived visual explanation link.

Keep the raw structured response available to the model, but expose only the human-readable explanation and selected action to the end user unless they ask for technical details.

For image-based requests, the visualization is a presentation layer. The API remains the source of truth for the action and highlight coordinates; do not derive new logic from the rendered image.