Skip to content
Prompty

Agentic Concepts

Prompty agents are still Prompty prompts: a .prompty file renders and parses into messages. The agentic layer starts when you run a conversational turn with tools or runtime controls.

This section is for application developers who need to build, debug, or govern tool-using agents. After reading it, you should be able to answer:

  • where the boundary is between a .prompty file and host runtime code;
  • how a single turn() differs from a full chat session;
  • how memory is represented by Prompty and persisted by your host;
  • when messages are prepared, appended, trimmed, compacted, or steered;
  • where to enforce policy with guardrails instead of prompt instructions;
  • how to observe and stop a long-running tool loop.

Mental model

Section titled “Mental model”
flowchart TD
    A[".prompty file"] --> B["prepare()\nrender + parse + thread expansion"]
    B --> C["turn()\nagentic runtime"]
    C --> D["LLM call"]
    D --> E{"tool calls?"}
    E -- yes --> F["dispatch tools"]
    F --> G["append tool result messages"]
    G --> C
    E -- no --> H["process final response"]

    C -. "optional controls" .-> I["events"]
    C -. "optional controls" .-> J["cancellation"]
    C -. "optional controls" .-> K["context budget + compaction"]
    C -. "optional controls" .-> L["guardrails"]
    C -. "optional controls" .-> M["steering"]
    C -. "host-provided context" .-> N["memory store"]

The key distinction is:

  • prepare() renders the template and parses role-marked text into messages.
  • turn() runs one user turn and, if needed, loops internally for tool calls.
  • Tool-loop iterations do not re-render the template. They mutate the prepared message array by appending assistant/tool messages.
  • Memory is a host boundary. Prompty defines the portable memory model and deterministic behavior; your application decides where the memory store lives and when it is loaded or saved.
  • External user turns call turn() again. If you pass conversation history as a thread input, that thread is expanded during the next prepare() call.

What belongs here

Section titled “What belongs here”
Concept What it controls Start here
Agent loop How tool calls are executed and fed back to the model Agent Loop
Memory Portable memory semantics, recall, formatting, and host persistence boundaries Memory
Runtime controls The per-iteration order for cancellation, steering, context, guardrails, model calls, and tools Runtime Controls
Guardrails Validate or rewrite inputs, outputs, and tool arguments Guardrails
Context budget Trim messages before model calls Context & Compaction
Compaction Replace dropped-message summaries with a custom summary Context & Compaction
Steering Inject messages between loop iterations Steering
Events Observe status, tool calls, message updates, completion, errors Events & Cancellation
Cancellation Stop a running loop cooperatively Events & Cancellation
Parallel tools Run multiple tool calls concurrently Tool Execution
Retries Retry transient LLM failures inside the loop Tool Execution

Runtime coverage

Section titled “Runtime coverage”

The agentic controls are runtime API options, not frontmatter fields. They are available in the v2 runtimes:

Runtime Agent loop Guardrails Compaction Steering
Python Yes Yes Yes Yes
TypeScript Yes Yes Yes Yes
C# Yes Yes Yes Yes
Rust Yes Yes Yes Yes

Memory helpers and conformance vectors are available across the generated model and runtime surface. The host still owns persistence by implementing the runtime’s memory port or equivalent load/save adapter.

Section titled “Related docs”