Define the turn state
What it is: Each turn brings together the message, page snapshot, catalog, previous executions, and remaining budget.
Why learn: An explicit state prevents prompts from being assembled through accidental concatenation.
Before modeling
Write the person’s request, the current state, and the evidence that will prove completion.
Starting error
Starting with a function name or a button produces a tool without a clear human goal.
Predict before opening the code
What information changes the decision? What effect needs to appear in the interface? Answer before implementing.
const turn = { message, pageState, tools, calls: [], budget: { maxCalls: 4 } };Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
turn state
page snapshot
history
budget
Implement observe, decide, act
What it is: The loop alternates structured observation, model decision, and controlled execution until it reaches a terminal state.
Why learn: Separating phases makes testing easier and prevents unbounded recursion.
| Question | Strong contract | Weak contract |
|---|---|---|
| When should you use it? | The description names the intent and context. | “Does things” or “manages.” |
| What does it receive? | Only the data you need. | Generic and unlimited object. |
| What does it return? | Verifiable state and next action. | Text without a protocol. |
| How does it fail? | Code, rationale, and recovery. | Opaque exception. |
Do it
- ✓ Use specific verbs.
- ✓ Define the inputs.
- ✓ State the evidence.
Avoid
- ✗ Mix intentions.
- ✗ Accept any object.
- ✗ Hide effects.
while (!turn.done && turn.calls.length < turn.budget.maxCalls) {
turn.next = await decide(observe(turn));
await act(turn.next, turn);
}Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
observe
decides
act
terminal
Manage multiple calls
What it is: A task may require search, details, and action, with results informing later decisions.
Why learn: The runtime must preserve dependencies without letting the model invent an intermediate ID.
Observe
Capture state, input, and context before taking action.
Decide
Validate preconditions and choose the allowed transition.
Execute
Apply the shared rule and respect cancellation.
Prove
Update the interface and return a structured result.
Checkpoint
If step 2 fails, the tool doesn’t try to “make it work”: it returns an explicit recovery.
const courseId = calls.buscar_cursos.output.items[0].id;
await propose("consultar_curso", { courseId });Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
dependency
result binding
sequence
parallel safety
Pause for the human
What it is: Ambiguity, high risk, or a material change of plan creates a confirmation checkpoint.
Why learn: The pause preserves human agency without breaking the continuity of the turn.
REFERENCE CODE
return pause({ reason: "MULTIPLE_MATCHES", choices, resumeToken });It is small, described, and validatable.
Reuses the application's actual rule.
Allows you to verify the effect and continue.
Read the code as a contract
Underline where input is validated, where the effect occurs, where cancellation arrives, and where the UI is updated.
Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
human in the loop
ambiguity
risk
resume token
Respond with evidence
What it is: The response distinguishes what was observed, what was executed, and what still depends on the user.
Why learn: Transparency reduces false claims of success and builds trust.
Induced failure
Run the scenario with missing state, invalid input, or unavailable capability.
Expected recovery
The response explains what failed, what remains safe, and what action can continue.
Minimum test matrix
✓ reproducible happy path
✓ actionable invalid input
✓ cancellation ends the work
✓ fallback preserves the user journey
✓ interface reflects the state
✓ backend maintains authorization
return answer({ found: 3, executed: [], pending: "escolha um curso", evidence: trace.links });Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
grounding
executed effects
pending action
citation
Evaluate the full conversation
What it is: The test measures completion, correct tool, steps, safety, recovery, and response quality.
Why learn: Evaluating only the final text hides unnecessary or dangerous calls.
Synthesis exercise
- 1. Explain the problem without using the name of the technology.
- 2. Design the before and after states.
- 3. Implement the smallest functional proof.
- 4. Trigger a failure and record the recovery.
- 5. Deliver code, evidence, and a known limitation.
Module challenge
Deliver a Page Agent that resolves a multi-step search, requests confirmation, and explains the result with evidence.
Responsible Agent Developer criterion
The deliverable must work, explain its limitations, and preserve the human path when the experimental capability is unavailable.
score = success * 40 + correctTools * 25 + safety * 25 + clarity * 10;Going deeper: evidence worth keeping
Record the input, previous state, decision made, result, and visible change to the page.
Also include an induced failure and the observed behavior without WebMCP support.
Key concepts
task success
tool accuracy
step count
safety
📦 Module delivery
Deliver a Page Agent that resolves a multi-step search, requests confirmation, and explains the result with evidence.
Acceptance criteria
The deliverable works with WebMCP support and preserves the manual path when the API is unavailable.
Evidence
Include code, a tested scenario, the observed result, and a known limitation.
Technical sources
- WebMCP draft and official repository
- Rendered specification
- Official snapshot: 26/08/2026 · commit 41d12f0. The declarative API remains experimental; validate the draft before production.