Agent Coaching Contract
The schemas live in magma_core.protocol.agent_coaching. They define transport and validation; the agent implements its own diagnosis/repair strategy and correction payload semantics.
Session routes
| Route | Contract |
|---|---|
PUT /v1/coaching/sessions/{run_id} | CoachingSessionConfig; shared helper returns 204 |
POST /v1/coaching | SpecializedCoachingRequest → SpecializedCoachingResponse |
DELETE /v1/coaching/sessions/{run_id} | Close workers after active requests; shared helper returns 204 |
CoachingSessionConfig carries a nonempty backends mapping and capture_logs (boolean, default true). Backend definitions require type, endpoint, and default_model; optional fields are headers (default {}), positive timeout (default 30 seconds), and nonnegative max_retry (default 3). GEN supplies effective settings. The shared session helper rejects conflicting reconfiguration with 409 and unknown/closing sessions with 404 on acquisition.
Inference and coaching share protocol_version="2.0" in /v1/info; there is no separate coaching version field. Advertise supported kinds through specialized_coaching and capabilities.coaching. Human interventions use the GEN viewer, not provider, endpoint, or connect_timeout fields in a coaching session.
Request and proposal
A request contains run_id, request_id, kind (failure, suboptimal, format), stage, target_step_id, trajectory, and reinjection_points. Optional context includes active_errors, diagnosis, and additional_info.
Trajectory steps contain their integer ID, original AgentInput, optional decision/error, internal records, and execution information. The target must occur in the trajectory. A reinjection point contains a unique string ID and exactly one of an explicit input or an input_step_id referring to that trajectory.
A corrected response contains proposals, each with reinjection_point_id and a JSON-object extra_keys. The point must be one supplied by GEN. GEN wraps the payload as AgentInput.extra_keys.coaching and invokes the response endpoint. Payload contents belong to the agent's implementation.
status="corrected" requires proposals. abandoned and error require a reason and no proposals. Match the request ID and call response.validate_request(request). Optional logs contain coaching_type and Markdown/text content for GEN to persist.
Generic text resume and internal records
coaching_resume=True advertises support for generic text replacement through the inference path. ReplaceSay defines {kind: "replace_say", text: nonempty string}. Specialized payloads, such as full-history's replace_decision, are agent-specific.
InternalStep provides a common record shape used by the supplied exporters: id, component, origin (model or coaching), full_prompt, input_elements, and output_raw. The base inference wire contract remains a list of JSON objects; document any more specific record schema your coaching/export implementation requires.
magma_core.workers.coaching_sessions supplies CoachingSessions and mount_coaching_routes(app, sessions, service_factory, ...). A service factory receives the session worker; its service implements process(request). These helpers manage sessions and logs, not the agent's repair algorithm.
Guide: Define your coaching logic. Concept: Correction lifecycle.