Evaluate continuations
A transition model predicts an action’s effects. A value model estimates the utility of an unfinished state. Exact terminal values score completed outcomes and take precedence over learned estimates. Keep all values in one perspective. For opposing decisions, maximizing nodes choose the highest continuation value and minimizing nodes choose the lowest. Use maximizing nodes throughout for a task with no opponent;/planning/adversarial supports this single-agent setup.
Record which evaluator supplies the values: an installed model, a selected candidate, or a caller checkpoint. A fixed adapter can carry another model’s scores into search; record both identities. For each choice, identify the terminal scores or learned frontier estimates that determined the ranking.
The request-level evaluator_source defaults to domain_model; value_model selects the installed value learner and value_candidate selects its candidate. Check evaluator readiness before sending the first request, including requests with exact terminal values. An installed sequential_q_mlp can be selected through domain_model. Use expected_model_sha256 where supported, inspect the returned evaluator identity, and align the value objective. See value learning for acquiring a separate state-value evaluator.
HTTP requests
POST /domains/{id}/planning/adversarial accepts a finite set of states and action edges, with a root descriptor and nodes. Each child edge identifies an action and refers to its successor through target:
policy field identifies the policy or value binding. It is distinct from the executable action on an edge.
For value_model and value_candidate, keep the request’s relation and policy consistent with the value learner configuration. Observed domain_model requests accepted a declared action policy and returned a sequential evaluator. Preserve the requested relation and policy with the returned model identity. Confirm the source-specific resolution of policy for frontier estimates against your deployment’s contract.
The HTTP planning reference supplies the complete documented GraphPlanningRequest schema. It requires session_id, relation, policy, and root. A state requires id and maximizing; graph nodes add children. The schema allows up to 4096 supplied nodes and 256 children per node. Objects, relations, conditions, context, numeric features, and exact terminal values describe the evaluator input.
Set search depth, width, budgets, extensions, and exploration in options. Native planning options lists the documented fields, its default and range, and the optional behaviors that still need semantic confirmation.
Define the unit of one transition before setting depth. A transition can represent a primitive action, an action block, or a complete skill. The application constructs valid successors, including any accounting or uncertainty propagation needed by its task.
The Core callback interface plan_adversarial(...) provides a separate integration through action, transition, actor-role, terminal-value, and evaluator callbacks.
Represent rewards and costs
An HTTPGraphEdge carries action and target. Search scores the terminal values and evaluator estimates supplied through the node representation. Encode accumulated rewards and costs in those state and value inputs; the edge schema has no reward or cost field.
Make the intended return explicit in the state and value representation. If two paths reach the same physical state with different accumulated costs, preserve the information needed to distinguish their values. Reusing a node that omits those costs can discard a distinction that matters to the decision.
A learned frontier estimate can account for effects represented in its training target. When search reaches a terminal node, its exact score takes precedence, so that score must preserve the same objective. Folding accumulated rewards into terminal scores also requires a consistent discount and horizon convention. Check this value alignment before interpreting a change with search depth as a change in model quality.
Keep the planner’s numeric fields and object representation consistent with those used for fitting. For a projected value learner, follow the input mapping checks before relying on numeric state features.
Streaming expansion
WebSocket/domains/{id}/planning/adversarial/stream lets the server request successors as search proceeds. The recorded initial request includes session_id, relation, policy, root, options, evaluator_source, and expected_model_sha256.
An expand message identifies a state_id and request_id. The client generates legal successors and returns children with full state descriptors. This abbreviated response shows the message shape:
target; streamed children use state. Check that the final result identifies the requested evaluator and returns a legal action.
The HTTP interface also exposes a GET stream-protocol route at the same path. That GET description is distinct from the WebSocket connection and does not define its complete message schema.
The HTTP request schema describes schema version 5. The streaming shapes above are abbreviated examples, not a complete WebSocket message contract. Use HTTP and contracts for authentication, scope, compatibility, and request validation.
Search diagnostics
Recorded HTTP responses place action and search counters under
plan and evaluator identity under evaluator. Preserve both sections when comparing a candidate with an installed model. The schema leaves the success body untyped, so validate the fields your integration consumes.
Use completed_depth for completed ordinary search depth and the extension counters for extension work. These counters use different units, so report them separately. The separate transition_plan response uses search.depth and horizon_complete; preserve those field names.
Validate the selected action and record what the executor performed. Use decision boundaries for first-action replanning, retained sequence selection for complete skills, and frozen-use rules for the surrounding learning loop.