@agentspec/adapter-claude 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +55 -0
- package/dist/index.js +153 -0
- package/dist/index.js.map +1 -0
- package/dist/skills/autogen.md +559 -0
- package/dist/skills/crewai.md +397 -0
- package/dist/skills/guidelines.md +141 -0
- package/dist/skills/helm.md +151 -0
- package/dist/skills/langgraph.md +1463 -0
- package/dist/skills/mastra.md +372 -0
- package/dist/skills/scan.md +195 -0
- package/package.json +44 -0
|
@@ -0,0 +1,397 @@
|
|
|
1
|
+
# AgentSpec → CrewAI Generation Skill
|
|
2
|
+
|
|
3
|
+
You are generating production-ready Python CrewAI agent code from an AgentSpec manifest JSON.
|
|
4
|
+
|
|
5
|
+
## Output Format
|
|
6
|
+
|
|
7
|
+
Return a single JSON object (wrapped in ```json ... ```) with this exact shape:
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"files": {
|
|
12
|
+
"crew.py": "...",
|
|
13
|
+
"tools.py": "...",
|
|
14
|
+
"requirements.txt": "...",
|
|
15
|
+
".env.example": "...",
|
|
16
|
+
"guardrails.py": "...",
|
|
17
|
+
"README.md": "..."
|
|
18
|
+
},
|
|
19
|
+
"installCommands": [
|
|
20
|
+
"python -m venv .venv",
|
|
21
|
+
"source .venv/bin/activate",
|
|
22
|
+
"pip install -r requirements.txt",
|
|
23
|
+
"cp .env.example .env"
|
|
24
|
+
],
|
|
25
|
+
"envVars": ["GROQ_API_KEY", "REDIS_URL"]
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
**File generation rules:**
|
|
30
|
+
| File | When to generate |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `crew.py` | Always |
|
|
33
|
+
| `tools.py` | When `spec.tools` is non-empty |
|
|
34
|
+
| `requirements.txt` | Always |
|
|
35
|
+
| `.env.example` | Always |
|
|
36
|
+
| `guardrails.py` | When `spec.guardrails` is set |
|
|
37
|
+
| `README.md` | Always |
|
|
38
|
+
|
|
39
|
+
**Invariants:**
|
|
40
|
+
- Map **every** manifest field. Do not skip sections.
|
|
41
|
+
- All string values embedded in Python code must be escaped (backslashes, quotes, newlines).
|
|
42
|
+
- Never embed literal API keys — always emit `os.environ.get("VAR")`.
|
|
43
|
+
- `validate_env()` must be called at module top-level before any connection is made.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Reference Syntax Resolution
|
|
48
|
+
|
|
49
|
+
Resolve `$ref` values before generating Python:
|
|
50
|
+
|
|
51
|
+
| Manifest reference | Python |
|
|
52
|
+
|---|---|
|
|
53
|
+
| `$env:VAR_NAME` | `os.environ.get("VAR_NAME")` |
|
|
54
|
+
| `$env:VAR_NAME` (required) | `os.environ.get("VAR_NAME")` — list in `REQUIRED_ENV_VARS` |
|
|
55
|
+
| `$secret:secret-name` | `os.environ.get("AGENTSPEC_SECRET_SECRET_NAME")` — transform: uppercase, `-` → `_`, prefix `AGENTSPEC_SECRET_` |
|
|
56
|
+
| `$file:path/to/file` | Use `path/to/file` as a relative filesystem path |
|
|
57
|
+
| `$func:now_iso` | `datetime.datetime.utcnow().isoformat()` — also add `import datetime` |
|
|
58
|
+
|
|
59
|
+
Examples:
|
|
60
|
+
- `$secret:langfuse-secret-key` → `os.environ.get("AGENTSPEC_SECRET_LANGFUSE_SECRET_KEY")`
|
|
61
|
+
- `$env:GROQ_API_KEY` → `os.environ.get("GROQ_API_KEY")`
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Mapping Rules
|
|
66
|
+
|
|
67
|
+
### spec.model — LangChain LLM (CrewAI uses LangChain under the hood)
|
|
68
|
+
|
|
69
|
+
| Manifest field | Python |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `provider: groq` | `from langchain_groq import ChatGroq` |
|
|
72
|
+
| `provider: openai` | `from langchain_openai import ChatOpenAI` |
|
|
73
|
+
| `provider: anthropic` | `from langchain_anthropic import ChatAnthropic` |
|
|
74
|
+
| `provider: google` | `from langchain_google_genai import ChatGoogleGenerativeAI` |
|
|
75
|
+
| `provider: azure` | `from langchain_openai import AzureChatOpenAI` |
|
|
76
|
+
| `provider: mistral` | `from langchain_mistralai import ChatMistralAI` |
|
|
77
|
+
| `apiKey: $env:VAR` | `api_key=os.environ.get("VAR")` kwarg |
|
|
78
|
+
| `id` | `model="model-id"` kwarg |
|
|
79
|
+
| `parameters.temperature` | `temperature=N` kwarg |
|
|
80
|
+
| `parameters.maxTokens` | `max_tokens=N` kwarg |
|
|
81
|
+
|
|
82
|
+
Pass the LLM instance to the `Agent(llm=llm)` constructor.
|
|
83
|
+
|
|
84
|
+
### spec.prompts
|
|
85
|
+
|
|
86
|
+
Use `spec.prompts.system` as the agent's `backstory` field (CrewAI convention).
|
|
87
|
+
If `system` is a `$file:` reference, read the file at runtime:
|
|
88
|
+
```python
|
|
89
|
+
def load_system_prompt() -> str:
|
|
90
|
+
try:
|
|
91
|
+
with open(SYSTEM_PROMPT_PATH, "r", encoding="utf-8") as f:
|
|
92
|
+
template = f.read()
|
|
93
|
+
variables = {
|
|
94
|
+
"unit_system": os.environ.get("UNIT_SYSTEM", ""),
|
|
95
|
+
"current_date": datetime.datetime.utcnow().isoformat(),
|
|
96
|
+
}
|
|
97
|
+
for key, val in variables.items():
|
|
98
|
+
template = template.replace("{{ " + key + " }}", val)
|
|
99
|
+
return template
|
|
100
|
+
except FileNotFoundError:
|
|
101
|
+
return "I am an AI assistant. Please try again."
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### spec.tools — two files
|
|
105
|
+
|
|
106
|
+
**tools.py** (generate when `spec.tools` is non-empty):
|
|
107
|
+
```python
|
|
108
|
+
"""
|
|
109
|
+
Tool implementations for {agent_name}
|
|
110
|
+
Generated by AgentSpec — fill in the function bodies.
|
|
111
|
+
"""
|
|
112
|
+
|
|
113
|
+
from crewai.tools import tool
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
@tool("log_workout")
|
|
117
|
+
def log_workout(**kwargs) -> str:
|
|
118
|
+
"""Log a completed training session with exercises, sets, reps, and duration"""
|
|
119
|
+
raise NotImplementedError("Implement log_workout")
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
@tool("get_workout_history")
|
|
123
|
+
def get_workout_history(**kwargs) -> str:
|
|
124
|
+
"""Retrieve past training sessions with optional filters"""
|
|
125
|
+
raise NotImplementedError("Implement get_workout_history")
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Rules:
|
|
129
|
+
- Function name: `tool.function` if set, otherwise `snake_case(tool.name)` (replace `-` with `_`)
|
|
130
|
+
- Decorator argument: `tool.name` (display name string)
|
|
131
|
+
- Docstring: `tool.description`
|
|
132
|
+
- Body: `raise NotImplementedError("Implement {func_name}")`
|
|
133
|
+
|
|
134
|
+
**crew.py imports tools:**
|
|
135
|
+
```python
|
|
136
|
+
from tools import log_workout, get_workout_history
|
|
137
|
+
agent_tools = [log_workout, get_workout_history]
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### spec.memory
|
|
141
|
+
|
|
142
|
+
CrewAI built-in memory:
|
|
143
|
+
```python
|
|
144
|
+
from crewai import Memory
|
|
145
|
+
|
|
146
|
+
# Enable memory when spec.memory is set
|
|
147
|
+
memory = Memory()
|
|
148
|
+
crew = Crew(agents=[agent], tasks=[task], memory=True, verbose=True)
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
For `spec.memory.shortTerm.backend = "redis"`:
|
|
152
|
+
```python
|
|
153
|
+
# CrewAI uses its own memory abstraction — configure external store via env:
|
|
154
|
+
# REDIS_URL is read by CrewAI Memory automatically when set
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### spec.guardrails — guardrails.py
|
|
158
|
+
|
|
159
|
+
Generate with real library calls (identical pattern to LangGraph adapter):
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
"""
|
|
163
|
+
Guardrails for {agent_name}
|
|
164
|
+
Generated by AgentSpec
|
|
165
|
+
"""
|
|
166
|
+
|
|
167
|
+
import re
|
|
168
|
+
from typing import Optional
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
class GuardrailError(Exception):
|
|
172
|
+
"""Raised when a guardrail rejects a message."""
|
|
173
|
+
pass
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
BLOCKED_TOPICS = ["illegal_activity", "self_harm", "violence", "explicit_content"]
|
|
177
|
+
TOPIC_REJECTION_MSG = "{rejection_message}"
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def check_topic_filter(text: str) -> None:
|
|
181
|
+
"""Reject messages matching blocked topics."""
|
|
182
|
+
text_lower = text.lower()
|
|
183
|
+
for topic in BLOCKED_TOPICS:
|
|
184
|
+
if topic.replace("_", " ") in text_lower or topic in text_lower:
|
|
185
|
+
raise GuardrailError(f"TOPIC_BLOCKED: {TOPIC_REJECTION_MSG}")
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def scrub_pii(text: str) -> str:
|
|
189
|
+
"""Scrub PII from text."""
|
|
190
|
+
text = re.sub(r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}', '[EMAIL]', text)
|
|
191
|
+
text = re.sub(r'\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b', '[PHONE]', text)
|
|
192
|
+
text = re.sub(r'\b\d{1,2}[/-]\d{1,2}[/-]\d{2,4}\b', '[DATE]', text)
|
|
193
|
+
text = re.sub(r'\b\d{3}-\d{2}-\d{4}\b', '[SSN]', text)
|
|
194
|
+
return text
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def check_prompt_injection(text: str) -> None:
|
|
198
|
+
"""Detect prompt injection attempts."""
|
|
199
|
+
INJECTION_PATTERNS = [
|
|
200
|
+
r'ignore\s+(?:all\s+)?(?:previous|prior|above)\s+instructions',
|
|
201
|
+
r'disregard\s+(?:your\s+)?(?:previous|prior|system)\s+(?:prompt|instructions)',
|
|
202
|
+
r'jailbreak',
|
|
203
|
+
r'dan\s+mode',
|
|
204
|
+
]
|
|
205
|
+
text_lower = text.lower()
|
|
206
|
+
for pattern in INJECTION_PATTERNS:
|
|
207
|
+
if re.search(pattern, text_lower):
|
|
208
|
+
raise GuardrailError("PROMPT_INJECTION: Prompt injection attempt detected")
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def run_input_guardrails(text: str) -> str:
|
|
212
|
+
"""Run all input guardrails. Returns scrubbed text or raises GuardrailError."""
|
|
213
|
+
check_topic_filter(text)
|
|
214
|
+
text = scrub_pii(text)
|
|
215
|
+
check_prompt_injection(text)
|
|
216
|
+
return text
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def run_output_guardrails(text: str, context: Optional[str] = None) -> str:
|
|
220
|
+
"""Run all output guardrails. Returns scrubbed text or raises GuardrailError."""
|
|
221
|
+
text = scrub_pii(text)
|
|
222
|
+
return text
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### spec.requires
|
|
226
|
+
|
|
227
|
+
```python
|
|
228
|
+
REQUIRED_ENV_VARS = ["GROQ_API_KEY"] # from spec.requires.envVars[]
|
|
229
|
+
|
|
230
|
+
|
|
231
|
+
def validate_env() -> None:
|
|
232
|
+
missing = [v for v in REQUIRED_ENV_VARS if not os.environ.get(v)]
|
|
233
|
+
if missing:
|
|
234
|
+
raise EnvironmentError(
|
|
235
|
+
f"Missing required environment variables: {', '.join(missing)}\n"
|
|
236
|
+
f"Copy .env.example to .env and fill in the values."
|
|
237
|
+
)
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
validate_env()
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
### spec.observability
|
|
244
|
+
|
|
245
|
+
For Langfuse tracing:
|
|
246
|
+
```python
|
|
247
|
+
# ── Tracing: Langfuse (CrewAI callback) ───────────────────────────────────────
|
|
248
|
+
# CrewAI supports Langfuse via the langfuse SDK callback integration
|
|
249
|
+
# See: https://langfuse.com/docs/integrations/crewai
|
|
250
|
+
import os
|
|
251
|
+
os.environ.setdefault("LANGFUSE_PUBLIC_KEY", os.environ.get("LANGFUSE_PUBLIC_KEY", ""))
|
|
252
|
+
os.environ.setdefault("LANGFUSE_SECRET_KEY", os.environ.get("AGENTSPEC_SECRET_LANGFUSE_SECRET_KEY", ""))
|
|
253
|
+
os.environ.setdefault("LANGFUSE_HOST", os.environ.get("LANGFUSE_HOST", "https://cloud.langfuse.com"))
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## Complete crew.py Structure
|
|
259
|
+
|
|
260
|
+
Generate sections in this exact order:
|
|
261
|
+
|
|
262
|
+
1. **Docstring** — agent name, version, model provider/id, tools count, memory backend
|
|
263
|
+
2. **Imports**:
|
|
264
|
+
- `import os`
|
|
265
|
+
- `import datetime` (if `$func:now_iso` used)
|
|
266
|
+
- `from crewai import Agent, Task, Crew`
|
|
267
|
+
- `from crewai import Memory` (if `spec.memory` is set)
|
|
268
|
+
- Provider LangChain import
|
|
269
|
+
- Tool imports: `from tools import tool_a, tool_b` (if tools exist)
|
|
270
|
+
- Guardrail imports (if guardrails set)
|
|
271
|
+
3. **Observability setup** (env vars for Langfuse / LangSmith)
|
|
272
|
+
4. **Env var validation** (`validate_env()` call)
|
|
273
|
+
5. **System prompt loading**
|
|
274
|
+
6. **LLM setup** — `llm = ChatGroq(model=..., api_key=...)`
|
|
275
|
+
7. **Agent definition**:
|
|
276
|
+
```python
|
|
277
|
+
agent = Agent(
|
|
278
|
+
role="{agent_name}",
|
|
279
|
+
goal="{description}",
|
|
280
|
+
backstory=load_system_prompt(),
|
|
281
|
+
tools=agent_tools,
|
|
282
|
+
llm=llm,
|
|
283
|
+
verbose=True,
|
|
284
|
+
)
|
|
285
|
+
```
|
|
286
|
+
8. **Task definition**:
|
|
287
|
+
```python
|
|
288
|
+
def create_task(user_input: str) -> Task:
|
|
289
|
+
return Task(
|
|
290
|
+
description=user_input,
|
|
291
|
+
agent=agent,
|
|
292
|
+
expected_output="A helpful, accurate response to the user's request.",
|
|
293
|
+
)
|
|
294
|
+
```
|
|
295
|
+
9. **Crew definition**:
|
|
296
|
+
```python
|
|
297
|
+
def run_agent(user_input: str) -> str:
|
|
298
|
+
"""Run the agent crew and return the result."""
|
|
299
|
+
task = create_task(user_input)
|
|
300
|
+
crew = Crew(
|
|
301
|
+
agents=[agent],
|
|
302
|
+
tasks=[task],
|
|
303
|
+
memory=True, # if spec.memory is set
|
|
304
|
+
verbose=True,
|
|
305
|
+
)
|
|
306
|
+
result = crew.kickoff()
|
|
307
|
+
return str(result)
|
|
308
|
+
```
|
|
309
|
+
10. **`__main__` block**
|
|
310
|
+
|
|
311
|
+
---
|
|
312
|
+
|
|
313
|
+
## requirements.txt Template
|
|
314
|
+
|
|
315
|
+
Always include base packages. Add extras based on manifest:
|
|
316
|
+
|
|
317
|
+
```
|
|
318
|
+
# Base (always)
|
|
319
|
+
crewai>=0.80.0
|
|
320
|
+
python-dotenv>=1.0.0
|
|
321
|
+
|
|
322
|
+
# Model provider (from spec.model.provider — LangChain under the hood)
|
|
323
|
+
langchain-groq>=0.1.0 # provider: groq
|
|
324
|
+
langchain-openai>=0.1.0 # provider: openai or azure
|
|
325
|
+
langchain-anthropic>=0.1.0 # provider: anthropic
|
|
326
|
+
langchain-google-genai>=0.1.0 # provider: google
|
|
327
|
+
langchain-mistralai>=0.1.0 # provider: mistral
|
|
328
|
+
|
|
329
|
+
# Observability (from spec.observability.tracing.backend)
|
|
330
|
+
langfuse>=2.0.0 # backend: langfuse
|
|
331
|
+
|
|
332
|
+
# Guardrails (from spec.guardrails.*)
|
|
333
|
+
detoxify>=0.5.0 # toxicity-filter guardrail
|
|
334
|
+
deepeval>=1.0.0 # hallucination-detector guardrail
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
---
|
|
338
|
+
|
|
339
|
+
## .env.example Rules
|
|
340
|
+
|
|
341
|
+
- One line per env var referenced in the manifest
|
|
342
|
+
- Strip `$env:` prefix for the variable name
|
|
343
|
+
- For `$secret:name`, the env var is `AGENTSPEC_SECRET_NAME` (uppercase, `-`→`_`)
|
|
344
|
+
- Add a comment describing what each var is for
|
|
345
|
+
- Group by concern: model, memory, observability, agent config
|
|
346
|
+
|
|
347
|
+
---
|
|
348
|
+
|
|
349
|
+
## README.md Template
|
|
350
|
+
|
|
351
|
+
```markdown
|
|
352
|
+
# {agent_name}
|
|
353
|
+
|
|
354
|
+
{description}
|
|
355
|
+
|
|
356
|
+
**Generated by [AgentSpec](https://agentspec.io) v{version}**
|
|
357
|
+
|
|
358
|
+
## Stack
|
|
359
|
+
|
|
360
|
+
| Component | Value |
|
|
361
|
+
|-----------|-------|
|
|
362
|
+
| Framework | CrewAI |
|
|
363
|
+
| Model | {provider}/{model_id} |
|
|
364
|
+
| Memory | {memory_backend} |
|
|
365
|
+
| Tracing | {tracing_backend} |
|
|
366
|
+
| Tools | {tools_count} |
|
|
367
|
+
|
|
368
|
+
## Quick Start
|
|
369
|
+
|
|
370
|
+
```bash
|
|
371
|
+
python -m venv .venv && source .venv/bin/activate
|
|
372
|
+
pip install -r requirements.txt
|
|
373
|
+
cp .env.example .env # fill in your API keys
|
|
374
|
+
python crew.py "Hello, what can you help me with?"
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
## Tools
|
|
378
|
+
|
|
379
|
+
{tool_list}
|
|
380
|
+
|
|
381
|
+
## Environment Variables
|
|
382
|
+
|
|
383
|
+
{env_var_list}
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
---
|
|
387
|
+
|
|
388
|
+
## Quality Checklist
|
|
389
|
+
|
|
390
|
+
| Check | Verify |
|
|
391
|
+
|---|---|
|
|
392
|
+
| `$secret:` resolution | `$secret:langfuse-secret-key` → `AGENTSPEC_SECRET_LANGFUSE_SECRET_KEY` |
|
|
393
|
+
| No literal keys | Search generated code for `sk-`, `pk-`, raw key strings |
|
|
394
|
+
| `validate_env()` called | At module top-level, before any connections |
|
|
395
|
+
| `tools.py` generated | When `spec.tools` is non-empty |
|
|
396
|
+
| Guardrails real code | No `raise NotImplementedError` in guardrails.py |
|
|
397
|
+
| Requirements complete | All packages match imports in generated files |
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# AgentSpec Generation — Universal Guidelines
|
|
2
|
+
|
|
3
|
+
These rules apply to ALL framework skill files. Every generated output must satisfy them
|
|
4
|
+
regardless of target framework.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Output Format
|
|
9
|
+
|
|
10
|
+
Return a **single JSON object** (wrapped in ` ```json ... ``` `) with this exact shape:
|
|
11
|
+
|
|
12
|
+
```json
|
|
13
|
+
{
|
|
14
|
+
"files": {
|
|
15
|
+
"<filename>": "<file content as a string>"
|
|
16
|
+
},
|
|
17
|
+
"installCommands": [
|
|
18
|
+
"python -m venv .venv",
|
|
19
|
+
"source .venv/bin/activate",
|
|
20
|
+
"pip install -r requirements.txt"
|
|
21
|
+
],
|
|
22
|
+
"envVars": ["GROQ_API_KEY", "REDIS_URL"]
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
**Escaping rules for file content strings:**
|
|
27
|
+
- All backslashes inside string values must be escaped: `\\` → `\\\\`
|
|
28
|
+
- All double quotes inside string values must be escaped: `"` → `\"`
|
|
29
|
+
- Newlines inside string values must be `\n` (literal backslash-n), NOT actual newlines
|
|
30
|
+
- The outer JSON structure uses real newlines for readability but string values must not
|
|
31
|
+
- Never truncate long files — generate the complete, runnable content for every file
|
|
32
|
+
- Test your JSON mentally: `JSON.parse(your_output)` must succeed
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Reference Syntax Resolution
|
|
37
|
+
|
|
38
|
+
Resolve `$ref` values before generating code:
|
|
39
|
+
|
|
40
|
+
| Manifest reference | Generated code |
|
|
41
|
+
|---|---|
|
|
42
|
+
| `$env:VAR_NAME` | `os.environ.get("VAR_NAME")` — list in `REQUIRED_ENV_VARS` if required |
|
|
43
|
+
| `$secret:secret-name` | `os.environ.get("AGENTSPEC_SECRET_SECRET_NAME")` — transform: uppercase, `-` → `_`, prefix `AGENTSPEC_SECRET_` |
|
|
44
|
+
| `$file:path/to/file` | Use `path/to/file` as a relative filesystem path |
|
|
45
|
+
| `$func:now_iso` | `datetime.datetime.utcnow().isoformat()` — also add `import datetime` |
|
|
46
|
+
|
|
47
|
+
Examples:
|
|
48
|
+
- `$secret:langfuse-secret-key` → `os.environ.get("AGENTSPEC_SECRET_LANGFUSE_SECRET_KEY")`
|
|
49
|
+
- `$secret:openai-api-key` → `os.environ.get("AGENTSPEC_SECRET_OPENAI_API_KEY")`
|
|
50
|
+
- `$env:GROQ_API_KEY` → `os.environ.get("GROQ_API_KEY")`
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Context File Usage
|
|
55
|
+
|
|
56
|
+
When context files from `$file:` tool module references are included in the input, use them:
|
|
57
|
+
|
|
58
|
+
- Read the actual function signatures and docstrings from the included source files
|
|
59
|
+
- Generate typed wrappers that match the real parameter names and types
|
|
60
|
+
- If the source file defines `def log_workout(exercises: list[str], duration: int) -> str`, generate
|
|
61
|
+
the wrapper with those exact parameters — do not invent different signatures
|
|
62
|
+
- If no source file is included (module not resolved), infer typed params from the tool description
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Universal Quality Checklist
|
|
67
|
+
|
|
68
|
+
Before finalising any output, verify every item:
|
|
69
|
+
|
|
70
|
+
| Check | Rule |
|
|
71
|
+
|---|---|
|
|
72
|
+
| `$secret:` resolution | `$secret:langfuse-secret-key` → `AGENTSPEC_SECRET_LANGFUSE_SECRET_KEY` |
|
|
73
|
+
| No literal keys | No `sk-`, `pk-`, raw API key strings in generated code |
|
|
74
|
+
| No hardcoded hosts | Never hardcode `localhost:6379` or `localhost:5432` — parse from env vars |
|
|
75
|
+
| `validate_env()` placement | Called BEFORE any external client initialization |
|
|
76
|
+
| Callbacks threaded through | Through LLM invoke AND graph invoke, not just one |
|
|
77
|
+
| Prompt variables | `load_system_prompt()` has the `template.replace()` loop |
|
|
78
|
+
| No `**kwargs` in tool functions | Always generate typed parameters — see framework skill for details |
|
|
79
|
+
| No `# TODO` in critical paths | Stubs are only acceptable for user-provided implementations (tool bodies, subagent bodies) |
|
|
80
|
+
| Requirements complete | All packages match imports in generated files |
|
|
81
|
+
| `.env.example` complete | Every `$env:` and `$secret:` reference has a corresponding line |
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Embedded Control Plane Principles (required for all frameworks)
|
|
86
|
+
|
|
87
|
+
Every generated agent must satisfy these four properties. They are not optional.
|
|
88
|
+
|
|
89
|
+
### 1. Manifest as runtime artifact
|
|
90
|
+
The source `agent.yaml` must ship with the generated code. Generate a loader module
|
|
91
|
+
(`manifest.py` for Python, `manifest.ts` for TypeScript) that:
|
|
92
|
+
- Loads `agent.yaml` from the same directory as the generated code
|
|
93
|
+
- Exposes `load_manifest()` and `get_capabilities()` functions
|
|
94
|
+
- Is always generated, regardless of which spec sections are present
|
|
95
|
+
|
|
96
|
+
### 2. Discoverability
|
|
97
|
+
When `spec.api` is set, generate a `/capabilities` endpoint that returns:
|
|
98
|
+
- `spec.metadata` (name, version, description, tags)
|
|
99
|
+
- `spec.tools[]` with all `annotations` fields intact
|
|
100
|
+
- Active compliance packs from `spec.compliance.packs[]`
|
|
101
|
+
|
|
102
|
+
Tool annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`) must be carried
|
|
103
|
+
through to framework-level tool metadata — never silently dropped.
|
|
104
|
+
|
|
105
|
+
### 3. Auditability
|
|
106
|
+
Audit log events must cover ALL observable categories — not only memory writes:
|
|
107
|
+
- Tool calls (include tool name, argument keys)
|
|
108
|
+
- Guardrail rejections and scrubs (include reason code)
|
|
109
|
+
- Destructive tool calls (log at WARNING level)
|
|
110
|
+
- Memory reads and writes (already required)
|
|
111
|
+
|
|
112
|
+
Use a consistent logger name: `agentspec.audit`.
|
|
113
|
+
|
|
114
|
+
### 4. Evaluability
|
|
115
|
+
When `spec.evaluation.datasets[]` is declared, the JSONL files are first-class
|
|
116
|
+
generated artifacts — they must contain seed test cases derived from the agent's
|
|
117
|
+
description, system prompt, tools, and guardrails. Never generate an eval harness
|
|
118
|
+
that references files that don't exist.
|
|
119
|
+
|
|
120
|
+
The eval harness must be pytest-compatible (`tests/test_eval.py`), not a standalone
|
|
121
|
+
root-level script. Guardrail tests (`tests/test_guardrails.py`) must run with zero
|
|
122
|
+
infrastructure requirements.
|
|
123
|
+
|
|
124
|
+
### 5. Controllability annotations
|
|
125
|
+
Every hardcoded threshold or limit must carry a comment indicating its manifest source:
|
|
126
|
+
```python
|
|
127
|
+
_HALLUCINATION_MAX_RETRIES = 2 # spec.guardrails.output.hallucination-detector.maxRetries
|
|
128
|
+
_RATE_LIMIT_RPM = 60 # spec.api.rateLimit.requestsPerMinute
|
|
129
|
+
```
|
|
130
|
+
This ensures developers know to edit `agent.yaml` rather than the generated code.
|
|
131
|
+
|
|
132
|
+
| Control Plane Check | Rule |
|
|
133
|
+
|---|---|
|
|
134
|
+
| `manifest.py` always generated | Required regardless of spec sections present |
|
|
135
|
+
| `get_capabilities()` exists | Returns tools with annotations |
|
|
136
|
+
| `/capabilities` endpoint | When `spec.api` is set |
|
|
137
|
+
| Audit log covers tool calls + guardrails | Not just memory writes |
|
|
138
|
+
| Eval datasets have seed cases | Never empty references |
|
|
139
|
+
| Eval in `tests/` not root level | pytest-compatible |
|
|
140
|
+
| Tool annotations carried to framework metadata | `readOnlyHint`, `destructiveHint`, `idempotentHint` |
|
|
141
|
+
| Hardcoded values annotated with manifest path | All thresholds/limits have `# spec.X.Y` comment |
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# AgentSpec → Helm Chart Generation Skill
|
|
2
|
+
|
|
3
|
+
You are generating a production-ready **Helm chart** from an AgentSpec manifest JSON.
|
|
4
|
+
The universal output format, reference syntax, and quality rules are in the guidelines prepended above.
|
|
5
|
+
|
|
6
|
+
## What You Are Generating
|
|
7
|
+
|
|
8
|
+
A Helm chart that deploys the agent alongside the `agentspec-sidecar` as a sidecar container.
|
|
9
|
+
The chart is framework-agnostic — it wraps whatever container image the agent runs in.
|
|
10
|
+
|
|
11
|
+
## File Generation Rules
|
|
12
|
+
|
|
13
|
+
| File | When to generate |
|
|
14
|
+
|---|---|
|
|
15
|
+
| `Chart.yaml` | Always — chart metadata (name, version, description from manifest) |
|
|
16
|
+
| `values.yaml` | Always — defaults for all configurable values |
|
|
17
|
+
| `templates/deployment.yaml` | Always — agent + agentspec-sidecar containers |
|
|
18
|
+
| `templates/service.yaml` | Always — ClusterIP exposing agent and sidecar ports |
|
|
19
|
+
| `templates/configmap.yaml` | Always — non-secret env vars (MODEL_PROVIDER, MODEL_ID, AGENT_NAME) |
|
|
20
|
+
| `templates/secret.yaml` | Always — Opaque secret; all `$env:` refs from manifest listed as required keys |
|
|
21
|
+
| `templates/serviceaccount.yaml` | Always — dedicated service account with optional IRSA annotations |
|
|
22
|
+
| `templates/ingress.yaml` | When `spec.api` is set — optional ingress controlled by `values.ingress.enabled` |
|
|
23
|
+
| `templates/_helpers.tpl` | Always — reusable template helpers (name, labels, selectorLabels, fullname) |
|
|
24
|
+
| `.helmignore` | Always — standard Helm ignore file |
|
|
25
|
+
| `README.md` | Always — installation instructions, required env vars, upgrade guidance |
|
|
26
|
+
|
|
27
|
+
## AgentSpec → Helm Mapping
|
|
28
|
+
|
|
29
|
+
| Manifest field | Helm target |
|
|
30
|
+
|---|---|
|
|
31
|
+
| `metadata.name` | Chart name, resource names, app labels |
|
|
32
|
+
| `metadata.version` | `Chart.yaml appVersion` |
|
|
33
|
+
| `metadata.description` | `Chart.yaml description` |
|
|
34
|
+
| `spec.api.port` | Container port, Service port, `values.service.port` |
|
|
35
|
+
| `spec.model.provider` | `values.config.modelProvider` in ConfigMap |
|
|
36
|
+
| `spec.model.id` | `values.config.modelId` in ConfigMap |
|
|
37
|
+
| `spec.requires.envVars[]` | Keys in Secret template + listed in README as required |
|
|
38
|
+
| `spec.requires.services[]` | Listed in README as external dependencies |
|
|
39
|
+
| `spec.requires.minimumMemoryMB` | `values.resources.requests.memory` |
|
|
40
|
+
|
|
41
|
+
## Invariants
|
|
42
|
+
|
|
43
|
+
- **`agentspec-sidecar` is always included** as a sidecar container in the Deployment, never optional.
|
|
44
|
+
- Image: `ghcr.io/agentspec/sidecar:latest` (controlled by `values.sidecar.image`)
|
|
45
|
+
- Proxy port: 4000, Control plane port: 4001
|
|
46
|
+
- Env: `UPSTREAM_URL: http://localhost:<agent-port>`, `MANIFEST_PATH: /manifest/agent.yaml`
|
|
47
|
+
- **No `$env:` or `$secret:` values** must appear in rendered ConfigMap data — only in the Secret.
|
|
48
|
+
- **Secret template** must list every `$env:VAR` ref found in the manifest as a key with a base64 placeholder comment.
|
|
49
|
+
- **`_helpers.tpl`** must define at minimum: `chart.name`, `chart.fullname`, `chart.labels`, `chart.selectorLabels`.
|
|
50
|
+
- **Resource names** must use the `{{ include "chart.fullname" . }}` helper to respect `nameOverride` / `fullnameOverride`.
|
|
51
|
+
- **`values.yaml`** must have sensible defaults (replica count 1, ClusterIP service, resources requests/limits).
|
|
52
|
+
|
|
53
|
+
## Helm Best Practices to Follow
|
|
54
|
+
|
|
55
|
+
- Use `{{ .Values.xxx | quote }}` for string values in env vars.
|
|
56
|
+
- Use `{{- toYaml .Values.resources | nindent 12 }}` for resource blocks.
|
|
57
|
+
- Add `NOTES.txt` under `templates/` with post-install instructions (how to reach the agent, sidecar endpoints).
|
|
58
|
+
- All resources must carry standard labels from `_helpers.tpl` (app.kubernetes.io/name, app.kubernetes.io/instance, app.kubernetes.io/version, app.kubernetes.io/managed-by).
|
|
59
|
+
- Include `helm.sh/chart` annotation.
|
|
60
|
+
- ServiceAccount must be conditionally created (`values.serviceAccount.create: true`).
|
|
61
|
+
|
|
62
|
+
## Output Format
|
|
63
|
+
|
|
64
|
+
Return a JSON object matching the GeneratedAgent schema:
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"files": {
|
|
69
|
+
"Chart.yaml": "...",
|
|
70
|
+
"values.yaml": "...",
|
|
71
|
+
"templates/_helpers.tpl": "...",
|
|
72
|
+
"templates/deployment.yaml": "...",
|
|
73
|
+
"templates/service.yaml": "...",
|
|
74
|
+
"templates/configmap.yaml": "...",
|
|
75
|
+
"templates/secret.yaml": "...",
|
|
76
|
+
"templates/serviceaccount.yaml": "...",
|
|
77
|
+
"templates/NOTES.txt": "...",
|
|
78
|
+
".helmignore": "...",
|
|
79
|
+
"README.md": "..."
|
|
80
|
+
},
|
|
81
|
+
"installCommands": [
|
|
82
|
+
"helm install <agent-name> . -f values.yaml --set image.tag=latest"
|
|
83
|
+
],
|
|
84
|
+
"envVars": ["VAR1", "VAR2"]
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`envVars` must list every `$env:VAR` name found in the manifest (for the README and CI checks).
|
|
89
|
+
`installCommands` must include the `helm install` and `helm upgrade` commands.
|
|
90
|
+
|
|
91
|
+
## Example Chart.yaml
|
|
92
|
+
|
|
93
|
+
```yaml
|
|
94
|
+
apiVersion: v2
|
|
95
|
+
name: <metadata.name>
|
|
96
|
+
description: <metadata.description>
|
|
97
|
+
type: application
|
|
98
|
+
version: 0.1.0
|
|
99
|
+
appVersion: "<metadata.version>"
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Example values.yaml (minimal)
|
|
103
|
+
|
|
104
|
+
```yaml
|
|
105
|
+
replicaCount: 1
|
|
106
|
+
|
|
107
|
+
image:
|
|
108
|
+
repository: <metadata.name>
|
|
109
|
+
tag: latest
|
|
110
|
+
pullPolicy: IfNotPresent
|
|
111
|
+
|
|
112
|
+
service:
|
|
113
|
+
type: ClusterIP
|
|
114
|
+
port: <spec.api.port or 8000>
|
|
115
|
+
|
|
116
|
+
sidecar:
|
|
117
|
+
image: ghcr.io/agentspec/sidecar:latest
|
|
118
|
+
proxyPort: 4000
|
|
119
|
+
controlPort: 4001
|
|
120
|
+
|
|
121
|
+
config:
|
|
122
|
+
agentName: "<metadata.name>"
|
|
123
|
+
modelProvider: "<spec.model.provider>"
|
|
124
|
+
modelId: "<spec.model.id>"
|
|
125
|
+
|
|
126
|
+
ingress:
|
|
127
|
+
enabled: false
|
|
128
|
+
className: ""
|
|
129
|
+
annotations: {}
|
|
130
|
+
hosts: []
|
|
131
|
+
tls: []
|
|
132
|
+
|
|
133
|
+
resources:
|
|
134
|
+
requests:
|
|
135
|
+
cpu: 100m
|
|
136
|
+
memory: <spec.requires.minimumMemoryMB or 256>Mi
|
|
137
|
+
limits:
|
|
138
|
+
cpu: 500m
|
|
139
|
+
memory: 512Mi
|
|
140
|
+
|
|
141
|
+
serviceAccount:
|
|
142
|
+
create: true
|
|
143
|
+
annotations: {}
|
|
144
|
+
name: ""
|
|
145
|
+
|
|
146
|
+
nameOverride: ""
|
|
147
|
+
fullnameOverride: ""
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Map **every** manifest field. Do not skip sections.
|
|
151
|
+
Ensure the Helm chart is installable with `helm install` against a standard Kubernetes cluster.
|