SuperSpec unites Context Engineering and Behaviour-Driven Development (BDD) for the age of agentic AI. Learn how this declarative DSL bridges context, testing, and optimization for autonomous agents.
This page is a graphical edition of the blog post. For the full textual version, choose your preferred platform below.
Choose your preferred platform to dive deeper
Context Engineering represents the systematic approach to curating the optimal information environment for Large Language Models. As detailed in the Superagentic AI article, this discipline addresses the critical challenge of providing "just-right" context to AI agents.
The goal is delivering precisely calibrated information—enough to enable high-quality responses, but not so much that costs spiral or focus is lost. Read the latest survey paper.
Agent Engineering marks a seismic shift in how AI systems are built, deployed, and maintained. Read more about Agent Engineering.
SuperSpec is a Kubernetes-style specification language that makes agent building as simple as writing a YAML file. Think of it as "Kubernetes for AI agents" you describe what you want, and SuperOptiX builds the pipeline.
apiVersion: agent/v1
kind: AgentSpec
metadata:
name: "Developer Assistant"
id: "developer"
namespace: "software"
version: "1.0.0"
agent_type: "Supervised"
level: "oracles"
description: "An agent that helps write clean, efficient, and maintainable code"
spec:
language_model:
location: "local"
provider: "ollama"
model: "llama3.2:1b"
api_base: "http://localhost:11434"
persona:
name: "DevBot"
role: "Software Developer"
goal: "Write clean, efficient, and maintainable code"
traits: ["analytical", "detail-oriented", "problem-solver"]
tasks:
- name: "implement_feature"
instruction: "Implement the feature based on the provided requirement"
inputs:
- name: "feature_requirement"
type: "str"
description: "A detailed description of the feature to implement"
required: true
outputs:
- name: "implementation"
type: "str"
description: "The code implementation of the feature"
agentflow:
- name: "generate_code"
type: "Generate"
task: "implement_feature"
evaluation:
builtin_metrics:
- name: "answer_exact_match"
threshold: 1.0
feature_specifications:
scenarios:
- name: "developer_comprehensive_task"
description: "Given a complex software requirement, the agent should provide detailed analysis"
input:
feature_requirement: "Complex software scenario requiring comprehensive analysis"
expected_output:
implementation: "Detailed step-by-step analysis with software-specific recommendations"
| Aspect | RSpec/PHPSpec | SuperSpec |
|---|---|---|
| Subject | Code methods | Agent behaviors |
| Language | Ruby/PHP DSL | YAML DSL |
| Scenarios | GWT or custom DSL | feature_specifications |
| Assertions | Boolean tests | Semantic metrics |
| Feedback | Test failures | Optimization loops |
feature_specifications:
scenarios:
- name: "developer_problem_solving"
description: "When facing software challenges, the agent should demonstrate systematic problem-solving approach"
input:
feature_requirement: "Challenging software problem requiring creative solutions"
expected_output:
implementation: "Structured problem-solving approach with multiple solution options"
# Standard specification execution super agent evaluate developer # Detailed analysis with verbose output super agent evaluate developer --verbose # Auto-tuning for improved results super agent evaluate developer --auto-tune # JSON output for CI/CD integration super agent evaluate developer --format json
spec:
memory:
enabled: true
short_term:
enabled: true
max_tokens: 2000
window_size: 10
long_term:
enabled: true
storage_type: "local"
max_entries: 500
persistence: true
episodic:
enabled: true
max_episodes: 100
episode_retention: 30
context_manager:
enabled: true
max_context_length: 4000
context_strategy: "sliding_window"
retrieval:
enabled: true
retriever_type: "chroma"
config:
top_k: 5
chunk_size: 512
chunk_overlap: 50
vector_store:
embedding_model: "sentence-transformers/all-MiniLM-L6-v2"
collection_name: "agent_knowledge"
You can configure SuperSpec for advanced configurations. See the DSL reference.
spec:
optimization:
strategy: "few_shot_bootstrapping"
metric: "answer_correctness"
metric_threshold: 0.8
few_shot_bootstrapping_config:
max_bootstrapped_demos: 4
max_rounds: 1
evaluation:
builtin_metrics:
- name: "answer_correctness"
threshold: 0.8
weight: 2.0
- name: "response_quality"
threshold: 0.7
- name: "safety_compliance"
threshold: 1.0
weight: 3.0
class DeveloperSignature(dspy.Signature):
"""
Software Developer: Write clean, efficient, and maintainable code
Role: Software Developer Traits: analytical, detail-oriented, problem-solver
Instruction: You are a Software Developer. Your goal is to write clean, efficient, and maintainable code. Implement the feature based on the provided requirement. """
# Input Fields
feature_requirement: str = dspy.InputField(desc="A detailed description of the feature to implement.")
# Output Fields
reasoning: str = dspy.OutputField(desc="The step-by-step reasoning process to arrive at the answer.")
implementation: str = dspy.OutputField(desc="The code implementation of the feature.")
This auto-generated DSPy signature can be further tuned by DSPy experts for advanced prompt and context optimization.
agentflow steps to SequentialChain nodes.language_model only.optimization section.As AI systems become increasingly complex, SuperSpec provides the foundation for maintainable, reliable, and auditable intelligent systems. It's not just a specification language—it's the future of how we build AI that works.
SuperSpec fuses context engineering and BDD into a coherent workflow: write YAML, validate, run scenarios, optimise, and deploy.
By elevating context to a first-class, testable artefact, it turns agent engineering into an engineering discipline with the same rigour developers expect from software pipelines. Start with a simple Oracles playbook, evolve into a Genies with tools, RAG, and memory, and let SuperSpec guide the journey—all without touching Python.
SuperSpec is available as part of the SuperOptiX framework. Learn more at the official documentation or DSL reference and start building your production-worthy AI agents.
Discover the principles and practices of context engineering for creating more intelligent, reliable, and effective AI agents.
Explore the latest advancements in AI agent development with DSPy 3.0 and related frameworks.