Skip to content

Types and validation ​

Codemode checks values at the two places the model's program meets your code.

WhereWhat is checkedOn a mismatch
Each codemode.execute(name, input)input against the capability's input shapethe call fails before your handler runs; the error names the field, and the model repairs the program
The program's return value, with agent.RunAs[T]the value against Tthe model is told what was wrong and repairs the program

Every check that fails is also a program.failed event, carrying the run ID; see Observability. A program that already ran a write is never repaired, so a write cannot happen twice. See Writes and retries.

Input ​

Every source declares an input shape, and every call is validated against it:

  • an unknown field is rejected, naming the fields that exist;
  • each value must have its declared kind: string, bool, number, integer (no fraction), lists, maps, nested shapes and enums;
  • a field the shape marks required must be present and not null;
  • at most one field of a oneof group may be set.

Errors carry the path, for example items[2].id: want integer, got "2". Nothing that fails validation is recorded as a call, so it never counts as a write.

What counts as required depends on the source:

SourceRequiredOptional
gosourceevery field without omitempty, omitzero or a pointerthe rest
mcpsourcethe JSON Schema's requiredthe rest
protobufnothing: proto3 fields default to zerooptional fields are shown as optional

Go structs ​

gosource and RunAs read Go types the way encoding/json writes them:

GoShape
string, boolstring, bool
int, int64, uint32, ...integer
float64, float32number
[]T, [N]Tlist of T
map[string]T, map[int]Tmap
[]bytebase64 string
time.TimeRFC 3339 string
json.RawMessage, anyanything
a structa named shape, declared once
a string type with Enum() []stringone of those values
,string tag optionstring

Embedded structs are flattened. A desc:"..." tag describes a field to the model. A type whose JSON shape reflection cannot know — a custom json.Marshaler, a channel, a function — is an error when the source is built, never a silent any.

A nil slice or map in a response is sent as [] or {}, because the prompt promised the model a list.

Typed answers ​

go
type Revenue struct {
	Total       float64 `json:"total"`
	TopCustomer string  `json:"top_customer"`
}

revenue, result, err := agent.RunAs[Revenue](ctx, mode, model, request, options)

The model is told the shape in a sentence every engine reads alike, the return value is checked and decoded into T, and a mismatch is repaired like any other failure, within Options.Attempts. RunAs[string] asks for a string. The shape is part of the cache key, so a cached program is reused only for the same T.