@agentspec/adapter-claude 0.2.3 → 0.4.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.
@@ -1,397 +0,0 @@
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 |
@@ -1,141 +0,0 @@
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 |
@@ -1,151 +0,0 @@
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.