PtcRunner.SubAgent.Loop.JsonMode (PtcRunner v0.7.0)

Copy Markdown View Source

Execution loop for JSON output mode.

JSON mode is a simpler alternative to PTC-Lisp execution where the LLM returns structured JSON directly, validated against the agent's signature.

Flow

  1. Build prompt using JSON templates (no PTC-Lisp spec)
  2. Call LLM with %{output: :json, schema: ...} in input
  3. Parse JSON from response
  4. Validate against signature
  5. If invalid and turns remaining → retry with error feedback
  6. Return Step struct with parsed JSON (atom keys)

Differences from PTC-Lisp Mode

AspectPTC-LispJSON Mode
System promptFull spec + tool docsMinimal (json-system.md)
Response parsingResponseHandler.parseJason.decode
ExecutionLisp.run/2None (direct validation)
Return valueFrom (return ...)Parsed JSON
MemoryAccumulatedAlways %{}
RetriesOn execution errorOn validation error

This is an internal module called by SubAgent.run/2 when output: :json.

Summary

Functions

preview_prompt(agent, context)

Generate a preview of the JSON mode prompts.

run(agent, llm, state)

Execute a SubAgent in JSON mode.

Functions

preview_prompt(agent, context)

@spec preview_prompt(PtcRunner.SubAgent.t(), map()) :: %{
  system: String.t(),
  user: String.t(),
  schema: map() | nil
}

Generate a preview of the JSON mode prompts.

Returns the system and user messages that would be sent to the LLM, plus the JSON schema used for validation.

run(agent, llm, state)

@spec run(PtcRunner.SubAgent.t(), term(), map()) ::
  {:ok, PtcRunner.Step.t()} | {:error, PtcRunner.Step.t()}

Execute a SubAgent in JSON mode.

Parameters

  • agent - A %SubAgent{} struct with output: :json
  • llm - LLM callback function
  • state - Initial loop state from Loop.run/2

Returns

  • {:ok, Step.t()} on success
  • {:error, Step.t()} on failure