Skip to content
ALTAIRA LABS
DocsBlog
PromptPackPromptPackPromptPack

Architecture Patterns

v1.3.1 · stable

Archived Version

This is the v1.3.1 documentation. For the latest features, see v1.4 docs →

PromptPack has grown from a simple prompt-packaging format into a full-stack specification for conversational AI systems. This page explains how the major building blocks relate to each other and when to use each one.

How the Pieces Fit Together

A PromptPack is organized in layers. Lower layers are simpler and more universal; higher layers are optional and compose on top of the lower ones.

┌─────────────────────────────────────────────┐
│ Skills Progressive knowledge loading │ v1.3.1
├─────────────────────────────────────────────┤
│ Agents Inter-system discovery (A2A) │ v1.3
├─────────────────────────────────────────────┤
│ Workflow Intra-pack state machine │ v1.3
├─────────────────────────────────────────────┤
│ Evals Async quality measurement │ v1.2
├─────────────────────────────────────────────┤
│ Validators Inline guardrails │ v1.0
├─────────────────────────────────────────────┤
│ Tools & Fragments Shared resources │ v1.0
├─────────────────────────────────────────────┤
│ Prompts Core behavior definitions │ v1.0
└─────────────────────────────────────────────┘

Prompts define what the LLM does. Tools & Fragments provide shared resources that prompts reference. Validators add inline guardrails that block bad output. Evals add async quality measurement that scores and reports. Workflow orchestrates transitions between prompts via a state machine. Agents expose prompts as discoverable services via the A2A protocol. Skills provide progressive-disclosure knowledge that agents load on demand.

Each layer is optional — a valid PromptPack only requires id, name, version, template_engine, and at least one prompt. You adopt higher layers only when you need them.

Workflows vs Agents

These two v1.3 features solve different problems and can be used independently or together.

Aspect Workflow Agents
Purpose Orchestrate transitions within a pack Make prompts discoverable across systems
Mechanism State machine with event-driven transitions A2A Agent Cards with metadata and tags
Scope Intra-pack (states reference prompt keys) Inter-system (external services discover agents)
Requires workflow top-level field agents top-level field
Entry point workflow.entry — first state in the machine agents.entry — default agent for incoming requests
Key benefit Automated routing without caller logic Multi-agent discovery and interoperability

Decision Matrix

Scenario Use Workflow? Use Agents?
Single prompt, no routing needed — —
Multiple prompts, caller chooses which to invoke — —
Automated routing between prompts based on events Yes —
Prompts need to be discoverable by external systems — Yes
Automated routing and external discovery Yes Yes
Standalone agents communicating via A2A (no internal state machine) — Yes

Workflow and agents are orthogonal. A prompt can participate in a workflow state and be an agent member simultaneously. The workflow manages intra-pack state; agents manage inter-system discovery.

Validators vs Evals

Both assess LLM output quality, but they operate at different points in the pipeline and serve different purposes.

Aspect Validators Evals
Runs when? Inline, every response Async, on schedule or trigger
Blocks output? Yes (when fail_on_violation: true) No — scores and reports
Scope Prompt-level only Prompt-level or pack-level
Type system Enum with custom escape hatch Free string (runtimes define types)
Metrics None Prometheus-style metric declarations
Version introduced v1.0 v1.2

Decision Matrix

Scenario Use Validators? Use Evals?
Block toxic or unsafe content before it reaches users Yes —
Monitor tone quality over time with dashboards — Yes
Enforce character limits on social media responses Yes —
Measure brand voice consistency across all prompts — Yes
PII detection that must never leak Yes —
Sample 10% of responses for LLM-judge quality scoring — Yes
Both block bad output and track quality trends Yes Yes

Validators and evals are complementary, not competitive. Use validators for hard safety guardrails and evals for continuous quality monitoring. The same prompt engineer typically authors both.

Orchestration Patterns

The workflow state machine supports several common multi-prompt patterns. Choose based on your use case.

Router + Specialists

A triage prompt classifies requests and routes to specialized prompts.

 ┌─ billing ─────┐
triage ──┤ ├── closing
 └─ technical ───┘

When to use: Customer support, help desks, any system where incoming requests need classification before handling.

Pipeline

Prompts execute in sequence, each processing the output of the previous one.

intake ── analyze ── draft ── review

When to use: Document processing, content generation pipelines, multi-step analysis.

Agent Mesh

Multiple agents communicate via A2A without a central workflow. Each agent discovers and invokes others through tool references.

researcher ←→ fact_checker ←→ writer

When to use: Loosely coupled agents that need to collaborate without rigid sequencing. Use the agents section without workflow.

Hybrid

Combine workflow orchestration internally with agent discovery externally.

[Workflow: triage → specialist → closing]
 ↕ A2A
[External systems discover and invoke agents]

When to use: Systems that need both internal routing logic and external interoperability.

Multimodal Integration

The media configuration (v1.1+) composes with all other features:

  • With Prompts: Each prompt can declare its own media config — supported types, format restrictions, size limits, and multimodal examples with parts arrays
  • With Validators: Validators run on the text output regardless of whether the input was multimodal
  • With Evals: Evals can assess multimodal interactions (e.g., an LLM judge evaluating whether the response correctly interpreted an image)
  • With Workflow: A workflow state can route to a prompt that accepts images, while another state routes to a text-only prompt
  • With Agents: Agent input/output modes (input_modes, output_modes) declare which MIME types the agent supports, complementing the prompt-level media config

Multimodal and text-only prompts can coexist in the same pack. A pack might have an image-aware product_lookup prompt and a text-only catalog_writer prompt — the media config is per-prompt, not per-pack.

Skills Integration (v1.3.1+)

Skills provide progressive-disclosure knowledge loading — modular expertise that agents activate on demand rather than embedding everything in system templates.

Skills vs Fragments

Aspect Fragments Skills
Resolved when? Compile time (template substitution) Runtime (on demand)
Content Static text strings Instructions, knowledge, behavioral patterns
Loading Always included in rendered template Loaded progressively when relevant
Scoping Referenced explicitly in templates Available to all prompts, filterable per workflow state
Version introduced v1.0 v1.3.1

When to Use Skills

Scenario Use Fragments? Use Skills?
Shared text like company intro or disclaimers Yes —
Domain expertise loaded on demand — Yes
Static template sections Yes —
Context-specific behavioral instructions — Yes
Small reusable text blocks Yes —
Large knowledge bases scoped per workflow state — Yes

Fragments and skills are complementary. Use fragments for compile-time text substitution and skills for runtime knowledge loading. A pack can use both.

Feature Compatibility Matrix

Feature Version Combines With
Prompts v1.0 Everything
Tools & Fragments v1.0 Prompts, Workflow, Agents
Validators v1.0 Prompts
Parameters v1.0 Prompts, Model Overrides
Tested Models v1.0 Prompts
Model Overrides v1.0 Prompts
Media (multimodal) v1.1 Prompts, Agents (MIME types)
Evals v1.2 Prompts (prompt-level), Pack (pack-level)
Workflow v1.3 Prompts (via prompt_task), Agents, Skills (state scoping)
Agents v1.3 Prompts (via members), Workflow
Skills v1.3.1 Workflow (state-scoped filtering), Agents

Next Steps