What you'll learn

• Why validation belongs at action boundaries
• How defaults and required fields reduce caller ambiguity
• How to structure return tuples for success and failure
• How to keep actions composable and testable

Prerequisites

• You understand the agent schema and route concepts
• You can write simple ExUnit tests
• You are familiar with tuple-based success/error flow

Lesson Breakdown

1. Action contract design: define required fields and defaults clearly.
2. Validation flow: reject malformed input before touching state.
3. Return shape: standardize {:ok, state_delta} and {:error, reason}.
4. Domain errors: separate validation errors from business rule conflicts.
5. Testing strategy: test happy path, boundary values, and failure payloads.

Hands-on Exercise

Implement SetPriceAction for a listing agent:

1. Input schema: price_cents (required integer), currency (default "USD").
2. Reject prices below 100 or above 50_000_00.
3. Return structured errors: %{field: ..., message: ...}.
4. Apply a successful update and stamp last_updated_at.
5. Add tests for invalid type, missing field, and boundary values.

Validation Checklist

• [ ] Invalid payloads fail before action logic runs.
• [ ] Defaults are applied deterministically.
• [ ] Error payloads include field-level detail.
• [ ] Tests cover lower and upper boundary values.

Next Module

Continue with Signals, Routing, and Agent Communication.