Overview
Reindeer agents store working data for each case in a JSON object called case state. The external API lets teams read and update that state, define the expected schema, and configure which state fields appear in case views.
This article explains how case state, case state schemas, output schemas, and display settings work together for API-managed agents.
Questions This Article Answers
- What is case state?
- How is case state different from an output schema?
- How do display settings control what users see in case views?
- Which fields should be included in a case state schema?
- When should a case update trigger reprocessing?
Core Concepts
| Concept | Description | Common use |
|---|---|---|
| Case state | JSON data stored on a case and returned by the external API. | Store extracted fields, validation results, review status, and corrected values. |
| Case state schema | JSON Schema describing expected case state. | Keep API clients, case views, and keyword mappings aligned. |
| Output model schema | JSON Schema describing structured run output. | Define the result returned by an agent run. |
| Display settings | Agent configuration that controls which state fields appear in case views. | Show important case values without custom UI work. |
| Update mask | A list of state. paths to update through the case PATCH endpoint. |
Safely patch only the fields that changed. |
How the Pieces Work Together
The external API exposes case state as part of the case resource. The case state schema describes the persistent case data. The output model schema describes the structured output produced by a run.
Case views read case state and use the agent display settings to decide which fields to surface. Display settings should point to stable fields in the case state. If a field path changes in the schema, update the display settings at the same time.
Case state is mutable through the external API. Schema and display changes affect how future API responses and case views are structured.
Common Configuration Pattern
- Design the case state schema around the data operators need to inspect or correct.
- Add stable field paths for high-value values such as customer name, document type, status, amount, due date, validation result, or routing decision.
- Configure display settings to show those fields in the UI.
- Test cases and verify that the fields populate consistently.
- Use the external case PATCH endpoint with optimistic locking when making human corrections.
- Reprocess only when the correction should change downstream agent decisions.
Design Considerations
- Keep case state focused on values that need to persist after a run.
- Use clear business names for schema fields.
- Prefer short scalar values for fields shown in case lists.
- Keep sensitive values masked, summarized, or omitted from display settings unless access controls are designed for them.
- Update display settings whenever schema paths change.
- Use optimistic locking when updating case state through the API.
Related Articles
- Configure Case Display Settings
- Manage Case State Schemas
- Update Case State Safely
Comments
0 comments
Please sign in to leave a comment.