Agent configuration mapping prompts to A2A-compatible agent definitions. (v1.3+)
:::info Collections are keyed maps, not arrays
prompts, fragments, and tools are all objects (keyed maps), not arrays. Each key serves as the identifier for the entry. For example, prompts maps task type strings like "support" or "billing" to their Prompt definitions.
:::
A single prompt configuration within a pack. Each prompt represents a specific task type (e.g., "support", "sales") with its own template, variables, tools, and validation rules. Prompts can evolve independently with their own version numbers.
Field
Type
Required
Description
id
string
Yes
Unique identifier, typically matching the map key. Pattern: ^[a-z][a-z0-9_-]*$.
name
string
Yes
Human-readable name.
version
string
Yes
Prompt version following Semantic Versioning, independent from the pack version.
system_template
string
Yes
The system prompt template. Use template syntax (e.g., {{variable}}) for variable substitution.
description
string
No
Detailed description of the prompt’s purpose and behavior.
Validation rules applied to the variable value at runtime.
Validation
Rules applied to variable values at runtime.
Field
Type
Description
pattern
string
Regular expression pattern (for string types).
min_length
integer
Minimum string length. Minimum value: 0.
max_length
integer
Maximum string length. Minimum value: 1.
minimum
number
Minimum numeric value (for number types).
maximum
number
Maximum numeric value (for number types).
enum
any[]
List of allowed values.
{
"name": "priority",
"type": "string",
"required": true,
"description": "Support ticket priority level",
"validation": {
"enum": ["low", "medium", "high", "urgent"]
}
}
Tool
A tool definition following the function calling convention. Tools enable the LLM to call external functions. Tools are defined at the pack level and referenced by name in each prompt’s tools array.
Field
Type
Required
Description
name
string
Yes
Tool name. Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$.
description
string
Yes
What the tool does. The LLM uses this to decide when to call it.
parameters
object
No
JSON Schema object defining the tool’s input parameters (see below).
Tool Parameters (JSON Schema Format)
Tool parameters use standard JSON Schema format. The parameters object must have type: "object" with a properties map and an optional required array.
Field
Type
Required
Description
type
string
Yes
Must be "object".
properties
object
Yes
Map of parameter names to their JSON Schema definitions.
required
string[]
No
List of required parameter names.
"tools": {
"create_ticket": {
"name": "create_ticket",
"description": "Create a support ticket with title, description, and priority",
"parameters": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Ticket title"
},
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "urgent"]
}
},
"required": ["title"]
}
}
}
Tool Policy
Governance policy for tool usage. Controls when and how tools can be called by the LLM.
Field
Type
Required
Description
tool_choice
string
No
"auto" (LLM decides), "required" (must use tools), or "none" (tools disabled). Default: "auto".
max_rounds
integer
No
Maximum number of LLM-tool-LLM cycles per turn. Minimum: 1. Default: 5.
max_tool_calls_per_turn
integer
No
Maximum tool calls allowed in a single turn. Minimum: 1. Default: 10.
blocklist
string[]
No
Tool names that are not allowed for this prompt (overrides the tools list).
Parameters
LLM generation parameters controlling the model’s behavior and output characteristics.
Field
Type
Required
Description
temperature
number
No
Sampling temperature (0—2). Higher values increase randomness.
max_tokens
integer
No
Maximum number of tokens to generate. Minimum: 1.
top_p
number
No
Nucleus sampling parameter (0—1). Alternative to temperature.
top_k
integer or null
No
Top-k sampling. null means no limit. Minimum: 1.
frequency_penalty
number
No
Penalty for token frequency (-2 to 2). Positive values reduce repetition.
presence_penalty
number
No
Penalty for token presence (-2 to 2). Positive values encourage new topics.
"parameters": {
"temperature": 0.7,
"max_tokens": 1500,
"top_p": 0.9
}
Validator
A validation rule (guardrail) applied to LLM responses.
Middleware type identifier (e.g., "template", "provider", "validator").
config
object
No
Type-specific configuration.
Metadata
Optional pack-level metadata for categorization and discovery.
Field
Type
Required
Description
domain
string
No
Domain or category (e.g., "customer-service", "healthcare").
language
string
No
Primary language code (ISO 639-1, e.g., "en"). Pattern: ^[a-z]{2}$.
tags
string[]
No
Tags for categorization and discovery.
cost_estimate
object
No
Cost estimation with min_cost_usd, max_cost_usd, and avg_cost_usd.
Compilation
Compiler-generated information about when and how the pack was built.
Field
Type
Required
Description
compiled_with
string
Yes
Version of the packc compiler (e.g., "packc-v0.1.0").
created_at
string
Yes
ISO 8601 timestamp when the pack was compiled.
schema
string
Yes
Pack format schema version (e.g., "v1").
source
string
No
Source configuration file path.
Evals (v1.2+)
Evals are automated quality checks on LLM outputs. Unlike validators (which run inline and can block responses), evals run asynchronously and produce scores or metrics. Evals can be defined at both pack level (cross-cutting) and prompt level (prompt-specific). Prompt-level evals with the same id override pack-level evals.
Eval
Field
Type
Required
Description
id
string
Yes
Unique identifier for this eval within its scope.
type
string
Yes
Assertion type determining how the eval runs. Not an enum — runtimes register their own types (e.g., "contains", "regex", "json_valid", "llm_judge").
trigger
string
Yes
When this eval fires. One of: "every_turn", "on_session_complete", "sample_turns", "sample_sessions".
description
string
No
Human-readable description of what this eval measures.
enabled
boolean
No
Whether this eval is active. Default: true.
sample_percentage
number
No
Percentage of turns/sessions to sample (0–100). Only used with sample_turns and sample_sessions triggers. Default: 5.
params
object
No
Type-specific configuration. Structure depends on the eval type.
Prometheus-style metric declaration for exposing eval results.
Metric Def
Field
Type
Required
Description
name
string
Yes
Metric name following Prometheus conventions (snake_case). Pattern: ^[a-zA-Z_:][a-zA-Z0-9_:]*$.
type
string
Yes
Metric type. One of: "gauge", "counter", "histogram", "boolean".
range
object
No
Optional value bounds with min and/or max fields.
The metric object uses additionalProperties: true, so runtimes can attach extra fields (e.g., labels, help, buckets).
"evals": [
{
"id": "json_format",
"type": "json_valid",
"trigger": "every_turn",
"description": "Verify the assistant always returns valid JSON",
"metric": {
"name": "promptpack_json_valid",
"type": "boolean"
}
},
{
"id": "tone-check",
"type": "llm_judge",
"trigger": "sample_turns",
"sample_percentage": 10,
"params": {
"judge_prompt": "Rate the response tone on a 1-5 scale for professionalism.",
"model": "gpt-4o",
"passing_score": 4
},
"metric": {
"name": "promptpack_tone_score",
"type": "gauge",
"range": { "min": 1, "max": 5 }
}
}
]
:::info Validators vs Evals
Both sit on the quality spectrum: validators run inline on every response and can block output (fail_on_violation), while evals run asynchronously and produce scores/metrics without blocking. Use validators for hard guardrails, evals for quality measurement and monitoring.
:::
Fragments
Fragments are shared, reusable template text blocks defined at the pack level. They are simple string values keyed by name.
Detail level for images: "low", "high", or "auto".
caption
string
No
Caption or description for the media.
"media": {
"enabled": true,
"supported_types": ["image"],
"image": {
"max_size_mb": 20,
"allowed_formats": ["jpeg", "png", "webp"],
"default_detail": "high",
"max_images_per_msg": 5
}
}
Workflow (v1.3+)
PromptPack v1.3 adds a state-machine workflow over the pack’s prompts. Each state references a prompt key and declares event-driven transitions to other states.
WorkflowConfig
Field
Type
Required
Description
version
integer
Yes
Workflow schema version. Use 1 for the current stable format.
entry
string
Yes
Name of the initial state. Must match a key in the states object.
PromptPack v1.3 adds agent definitions that map prompts to A2A (Agent-to-Agent) compatible agent cards. This enables multi-agent orchestration via the A2A protocol.
AgentsConfig
Field
Type
Required
Description
entry
string
Yes
Prompt key of the entry agent — the default agent that receives incoming requests.
:::info Workflow + Agents
workflow and agents are independent features — you can use either or both. When used together, the workflow drives state transitions while agent definitions provide A2A discoverability metadata for each prompt.
:::
Data Types
Supported Variable Types
string — Text data
number — Numeric values (integers and floats)
boolean — True/false values
array — Ordered lists of values
object — Key-value maps
Template Variables
Variables in templates use the syntax defined in template_engine.syntax. With the default {{variable}} syntax:
