Use a type system for agent outputs

When an AI result enters a ticket, CRM, ERP, or message workflow, prose instructions alone leave too much responsibility to the model. A type contract gives the surrounding application a stable interface.

Define the input contract

Name the fields the model may receive and their meaning. Include:

• source identifier and version;
• language and data class;
• task type;
• allowed context and maximum size;
• user or service identity;
• required source references;
• fields that must be removed before inference.

Validate the input before calling the model. Reject an unknown task, missing source, expired document, or disallowed data class with an actionable error. Keep the original source outside the prompt when the task can use a reference and retrieval step instead.

Define the output contract

Use a schema that names each field, type, allowed value, optionality, and relationship. A ticket route might require a queue identifier, priority enum, evidence references, review flag, and explanation for a missing field. A draft message might require recipient, purpose, body, source references, and a send status that remains pending until a person approves it.

JSON Schema is a widely used vocabulary for describing JSON data. Use the schema feature supported by your model provider or runtime, then validate the returned JSON in your application. A valid JSON object can still contain a wrong queue or unsupported claim, so semantic checks belong beside the shape check.

Treat failure as a typed result

The model call should return a result that the workflow understands:

Accepted   { value, sources, modelVersion }
Review     { value, reasons, sources, reviewer }
Rejected   { code, field, message, source }
Unavailable { dependency, retryAfter, owner }

The exact representation can use your language's types or a schema registry. The important part is that a failure has an owner and a route. Do not turn a parse error into an empty value that looks like a successful answer.

Put validation before side effects

The application should check:

1. JSON shape and required fields;
2. enums, ranges, identifiers, and references;
3. source availability and freshness;
4. tenant and permission scope;
5. duplicate or conflicting actions;
6. approval requirement and expiry;
7. idempotency key before a write or message.

Only then should the workflow call a tool. Give the tool a typed request with the minimum fields and identity needed for the action. Record the request, validation result, policy decision, and adapter response.

Keep prompts inside the contract

Prompt text still defines task intent, examples, and review guidance. Store it with the schema version and model configuration. Use examples that teach format and edge handling while keeping sensitive data out of the repository. A changed field name or enum should trigger a compile-time or CI failure in every consumer.

Avoid hiding business rules in a long prompt. Put permissions, numeric limits, required sources, and approval rules in code or policy that the application can test. Give the model a clear instruction for uncertainty, then let validation route the result.

Test the interface

Build a regression set with accepted, malformed, incomplete, ambiguous, and adversarial inputs. Check:

• schema validity;
• field and enum correctness;
• source reference accuracy;
• refusal or review routing;
• idempotency and duplicate handling;
• error message quality;
• permission and tenant isolation.

Run the set after a model, prompt, schema, retrieval, or tool change. Keep failed cases with the reason for failure and the approved expected result.

When the type system pays off

Use a typed interface when a model result crosses a system boundary, affects a record, or must be reviewed consistently by several people. A free-form answer may be enough for a private drafting task that never leaves a workspace. The decision follows from the next consumer and the cost of an invalid value.

Bring one real workflow, its current payload, and its failure cases to an AI process scan. The useful output is a contract, validator, owner, and test set that can survive the next model change.