View Source Agens.Prompt (agens v0.2.0)

Builds the system/user prompt pairs for a Agens.Message prior to LM inference.

build/3 assembles the structured fields of a Agens.Message (objective, description, input, previous result, resources, tool definitions/calls/results, retry reason, optional context) into two lists of {prefix, value} pairs - one for the system prompt and one for the user prompt. Each pair combines a header/detail tuple from Agens.Prefixes with the corresponding value.

Empty values are filtered out so that omitted fields produce no prompt section. The goal is to balance detail with token usage by populating only the fields that matter for a given Node — a Node without tools won't carry a Tool Definitions section, a Node without an objective won't carry a Node Objective section, and so on.

System vs User

Fields are partitioned between the system prompt and the user prompt:

  • System — description, objective, context, tool_defs, resources. Stable, workflow-defining context that doesn't change across retries of the same Node.
  • User — input, previous_result, tool_calls, tool_results, retry. Per-turn data that varies between Nodes and across retries.

Each section is rendered with the corresponding prefix's heading and detail from Agens.Prefixes.

Pipeline

For each request, Agens.Serving orchestrates roughly:

  1. Resolve any agent-specific context via Agens.Serving.load_context/2.
  2. Resolve Agens.Serving.load_resource/3 for every Agens.Resource declared on the Node.
  3. Build the JSON schema from the Router's declared outputs (via Agens.Router.Output.to_json_schema/1).
  4. Stitch the prompt with Agens.Prompt.build/3, applying the Serving's prefixes.
  5. Send to the LM via Agens.Serving.handle_message/3.
  6. Parse the structured response and route via the Router.

This module is part of the internal prompt pipeline; Servings normally call it indirectly via the default Agens.Serving.build_prompt/3 injected by use Agens.Serving. Override build_prompt/3 when you need full control over prompt construction (for example, emitting a chat-message format instead of system/user concatenation), or override Agens.Serving.Config.prefixes when you only need to customize the headings/detail of the existing sections.

Summary

Functions

build(message, prefixes, context)

Builds the system and user prompt pair for a Agens.Message.

Functions

Link to this function

build(message, prefixes, context)

View Source 
@spec build(Agens.Message.t(), Agens.Prefixes.t(), binary() | nil) :: {list(), list()}

Builds the system and user prompt pair for a Agens.Message.

Returns {system, user} where each is a list of {{heading, detail}, value} tuples — the heading/detail come from the supplied prefixes and value comes from the corresponding field on the message. Servings render these pairs into final strings (the default Agens.Serving.build_prompt/3 joins each tuple as ## heading\ndetail:\n\nvalue).

Fields with nil or empty values are filtered out — a Node without an :objective won't carry a Node Objective section, a Node without :tools won't carry Tool Definitions, and so on. See the moduledoc for the full system-vs-user partition.

Parameters

  • message - The Agens.Message whose fields drive the prompt sections.
  • prefixes - The Agens.Prefixes struct supplying {heading, detail} tuples for each section. Typically the Serving's Agens.Serving.Config.prefixes.
  • context - Optional string from Agens.Serving.load_context/2. When non-nil, surfaced under the Context prefix in the system prompt; when nil, the section is omitted.

Retries with no explicit retry_reason fall back to a generic validation-failure message under the Retry prefix.