@agentspec/codegen 0.2.4

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.
@@ -0,0 +1,559 @@
1
+ # AgentSpec → AutoGen Generation Skill
2
+
3
+ You are generating production-ready Python AutoGen agent code from an AgentSpec manifest JSON.
4
+ The universal output format, reference syntax, and quality rules are in the guidelines prepended above.
5
+
6
+ ## File Generation Rules
7
+
8
+ | File | When to generate |
9
+ |---|---|
10
+ | `agent.py` | Always |
11
+ | `tools.py` | When `spec.tools` is non-empty |
12
+ | `tool_implementations.py` | When `spec.tools` is non-empty (flat — **no `tools/` subdir**) |
13
+ | `manifest.py` | **Always** |
14
+ | `agent.yaml` | **Always** (copy of source manifest, `$secret:` refs replaced with empty string) |
15
+ | `requirements.txt` | Always — runtime deps only |
16
+ | `requirements-test.txt` | Always — test/CI deps (pytest); never in prod image |
17
+ | `.env.example` | Always |
18
+ | `guardrails.py` | When `spec.guardrails` is set |
19
+ | `server.py` | When `spec.api` is set (FastAPI + streaming) |
20
+ | `tests/test_guardrails.py` | When `spec.guardrails` is set |
21
+ | `tests/test_tools.py` | When `spec.tools` is non-empty |
22
+ | `README.md` | Always |
23
+ | `docker-compose.yml` | **Always** — agent service + agentspec-sidecar |
24
+ | `agentspec-sidecar.env` | **Always** — sidecar env vars prefilled from spec |
25
+
26
+ **Invariants:**
27
+ - Map **every** manifest field. Do not skip sections.
28
+ - All string values embedded in Python code must be escaped (backslashes, quotes, newlines).
29
+ - Never embed literal API keys — always emit `os.environ.get("VAR")`.
30
+ - `validate_env()` must be called at module top-level before any connection is made.
31
+
32
+ ---
33
+
34
+ ## Mapping Rules
35
+
36
+ ### spec.model — AutoGen model client
37
+
38
+ AutoGen 0.4+ uses typed model clients from `autogen_ext.models.*`.
39
+
40
+ | Manifest field | Python |
41
+ |---|---|
42
+ | `provider: openai` | `from autogen_ext.models.openai import OpenAIChatCompletionClient` |
43
+ | `provider: anthropic` | `from autogen_ext.models.anthropic import AnthropicChatCompletionClient` |
44
+ | `provider: azure` | `from autogen_ext.models.azure import AzureOpenAIChatCompletionClient` |
45
+ | `provider: groq` | `from autogen_ext.models.openai import OpenAIChatCompletionClient` + `base_url="https://api.groq.com/openai/v1"` |
46
+ | `provider: mistral` | `from autogen_ext.models.openai import OpenAIChatCompletionClient` + `base_url="https://api.mistral.ai/v1"` |
47
+ | `provider: google` | `from autogen_ext.models.openai import OpenAIChatCompletionClient` + `base_url="https://generativelanguage.googleapis.com/v1beta/openai/"` |
48
+ | `apiKey: $env:VAR` | `api_key=os.environ.get("VAR")` kwarg |
49
+ | `id` | `model="model-id"` kwarg |
50
+ | `parameters.temperature` | `model_capabilities=ModelCapabilities(...)` — or omit if not supported by client |
51
+ | `parameters.maxTokens` | passed via `model_capabilities` or ignored if unsupported |
52
+
53
+ **OpenAI example:**
54
+ ```python
55
+ from autogen_ext.models.openai import OpenAIChatCompletionClient
56
+
57
+ model_client = OpenAIChatCompletionClient(
58
+ model="gpt-4o",
59
+ api_key=os.environ.get("OPENAI_API_KEY"),
60
+ )
61
+ ```
62
+
63
+ **Anthropic example:**
64
+ ```python
65
+ from autogen_ext.models.anthropic import AnthropicChatCompletionClient
66
+
67
+ model_client = AnthropicChatCompletionClient(
68
+ model="claude-sonnet-4-6",
69
+ api_key=os.environ.get("ANTHROPIC_API_KEY"),
70
+ )
71
+ ```
72
+
73
+ **Groq (OpenAI-compatible) example:**
74
+ ```python
75
+ from autogen_ext.models.openai import OpenAIChatCompletionClient
76
+
77
+ model_client = OpenAIChatCompletionClient(
78
+ model="llama-3.3-70b-versatile",
79
+ api_key=os.environ.get("GROQ_API_KEY"),
80
+ base_url="https://api.groq.com/openai/v1",
81
+ )
82
+ ```
83
+
84
+ ### spec.prompts
85
+
86
+ Use `spec.prompts.system` as the `system_message` argument on `AssistantAgent`.
87
+ If `system` is a `$file:` reference, read it at runtime:
88
+
89
+ ```python
90
+ def load_system_prompt() -> str:
91
+ try:
92
+ with open(SYSTEM_PROMPT_PATH, "r", encoding="utf-8") as f:
93
+ template = f.read()
94
+ variables = {
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 "You are a helpful AI assistant."
102
+ ```
103
+
104
+ ### spec.tools — two files
105
+
106
+ Tools in AutoGen are plain async Python functions. Register them directly in `tools=[]`.
107
+
108
+ **tool_implementations.py** (stubs — user fills in bodies):
109
+ ```python
110
+ """
111
+ Tool implementations for {agent_name}
112
+ Generated by AgentSpec — fill in the function bodies.
113
+ """
114
+
115
+
116
+ async def log_workout(exercises: list, duration: int, notes: str = "") -> str:
117
+ """Log a completed training session with exercises, sets, reps, and duration"""
118
+ raise NotImplementedError("Implement log_workout")
119
+
120
+
121
+ async def get_workout_history(limit: int = 10, exercise_type: str = "") -> str:
122
+ """Retrieve past training sessions with optional filters"""
123
+ raise NotImplementedError("Implement get_workout_history")
124
+ ```
125
+
126
+ Rules:
127
+ - Function name: `tool.function` if set, otherwise `snake_case(tool.name)` (replace `-` with `_`)
128
+ - Signature: typed parameters inferred from tool description — **never `**kwargs`**
129
+ - Docstring: `tool.description`
130
+ - Body: `raise NotImplementedError("Implement {func_name}")`
131
+
132
+ **tools.py** (imports and exposes the list used in agent.py):
133
+ ```python
134
+ """
135
+ Tool registry for {agent_name}
136
+ """
137
+ from tool_implementations import log_workout, get_workout_history
138
+
139
+ AGENT_TOOLS = [log_workout, get_workout_history]
140
+ ```
141
+
142
+ **agent.py imports tools:**
143
+ ```python
144
+ from tools import AGENT_TOOLS
145
+
146
+ agent = AssistantAgent(
147
+ name="{agent_name}",
148
+ model_client=model_client,
149
+ tools=AGENT_TOOLS,
150
+ system_message=load_system_prompt(),
151
+ )
152
+ ```
153
+
154
+ ### spec.memory
155
+
156
+ AutoGen `AssistantAgent` accepts a `memory=[]` list of memory objects.
157
+
158
+ **In-process (no backend specified or `backend: in-memory`):**
159
+ ```python
160
+ from autogen_agentchat.memory import ListMemory, MemoryContent, MemoryMimeType
161
+
162
+ user_memory = ListMemory()
163
+ ```
164
+
165
+ **Redis backend (`backend: redis`):**
166
+ ```python
167
+ # AutoGen does not have a first-class Redis memory adapter yet.
168
+ # Use ListMemory with a custom persistence wrapper populated at startup.
169
+ from autogen_agentchat.memory import ListMemory, MemoryContent, MemoryMimeType
170
+ import redis
171
+
172
+ _redis_client = redis.from_url(os.environ.get("REDIS_URL")) # spec.memory.shortTerm.url
173
+
174
+ def load_memory_from_redis(memory: ListMemory) -> None:
175
+ """Populate ListMemory from Redis on startup."""
176
+ for key in _redis_client.scan_iter("agentmem:*"):
177
+ value = _redis_client.get(key)
178
+ if value:
179
+ memory.add_sync(MemoryContent(content=value.decode(), mime_type=MemoryMimeType.TEXT))
180
+ ```
181
+
182
+ **Wire memory into agent:**
183
+ ```python
184
+ agent = AssistantAgent(
185
+ name="{agent_name}",
186
+ model_client=model_client,
187
+ tools=AGENT_TOOLS,
188
+ system_message=load_system_prompt(),
189
+ memory=[user_memory], # when spec.memory is set
190
+ )
191
+ ```
192
+
193
+ ### spec.guardrails — guardrails.py
194
+
195
+ Generate with real implementation (identical pattern to LangGraph/CrewAI adapter):
196
+
197
+ ```python
198
+ """
199
+ Guardrails for {agent_name}
200
+ Generated by AgentSpec
201
+ """
202
+
203
+ import re
204
+ from typing import Optional
205
+
206
+
207
+ class GuardrailError(Exception):
208
+ """Raised when a guardrail rejects a message."""
209
+ pass
210
+
211
+
212
+ BLOCKED_TOPICS = ["illegal_activity", "self_harm", "violence", "explicit_content"]
213
+ TOPIC_REJECTION_MSG = "{rejection_message}"
214
+
215
+
216
+ def check_topic_filter(text: str) -> None:
217
+ """Reject messages matching blocked topics."""
218
+ text_lower = text.lower()
219
+ for topic in BLOCKED_TOPICS:
220
+ if topic.replace("_", " ") in text_lower or topic in text_lower:
221
+ raise GuardrailError(f"TOPIC_BLOCKED: {TOPIC_REJECTION_MSG}")
222
+
223
+
224
+ def scrub_pii(text: str) -> str:
225
+ """Scrub PII from text."""
226
+ text = re.sub(r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}', '[EMAIL]', text)
227
+ text = re.sub(r'\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b', '[PHONE]', text)
228
+ text = re.sub(r'\b\d{3}-\d{2}-\d{4}\b', '[SSN]', text)
229
+ return text
230
+
231
+
232
+ def check_prompt_injection(text: str) -> None:
233
+ """Detect prompt injection attempts."""
234
+ INJECTION_PATTERNS = [
235
+ r'ignore\s+(?:all\s+)?(?:previous|prior|above)\s+instructions',
236
+ r'disregard\s+(?:your\s+)?(?:previous|prior|system)\s+(?:prompt|instructions)',
237
+ r'jailbreak',
238
+ r'dan\s+mode',
239
+ ]
240
+ text_lower = text.lower()
241
+ for pattern in INJECTION_PATTERNS:
242
+ if re.search(pattern, text_lower):
243
+ raise GuardrailError("PROMPT_INJECTION: Prompt injection attempt detected")
244
+
245
+
246
+ def run_input_guardrails(text: str) -> str:
247
+ """Run all input guardrails. Returns scrubbed text or raises GuardrailError."""
248
+ check_topic_filter(text)
249
+ text = scrub_pii(text)
250
+ check_prompt_injection(text)
251
+ return text
252
+
253
+
254
+ def run_output_guardrails(text: str, context: Optional[str] = None) -> str:
255
+ """Run all output guardrails. Returns scrubbed text or raises GuardrailError."""
256
+ text = scrub_pii(text)
257
+ return text
258
+ ```
259
+
260
+ Apply guardrails in `run_agent()` before passing to the agent and after collecting the response:
261
+
262
+ ```python
263
+ from guardrails import run_input_guardrails, run_output_guardrails, GuardrailError
264
+
265
+ async def run_agent(user_input: str) -> str:
266
+ try:
267
+ safe_input = run_input_guardrails(user_input)
268
+ except GuardrailError as e:
269
+ logger.warning("agentspec.audit guardrail_rejection input reason=%s", str(e))
270
+ return f"Request rejected: {e}"
271
+
272
+ result = await Console(agent.run_stream(task=safe_input))
273
+ response_text = str(result.messages[-1].content) if result.messages else ""
274
+
275
+ try:
276
+ safe_output = run_output_guardrails(response_text)
277
+ except GuardrailError as e:
278
+ logger.warning("agentspec.audit guardrail_rejection output reason=%s", str(e))
279
+ return f"Response filtered: {e}"
280
+
281
+ return safe_output
282
+ ```
283
+
284
+ ### spec.requires
285
+
286
+ ```python
287
+ REQUIRED_ENV_VARS = ["OPENAI_API_KEY"] # from spec.requires.envVars[]
288
+
289
+
290
+ def validate_env() -> None:
291
+ missing = [v for v in REQUIRED_ENV_VARS if not os.environ.get(v)]
292
+ if missing:
293
+ raise EnvironmentError(
294
+ f"Missing required environment variables: {', '.join(missing)}\n"
295
+ f"Copy .env.example to .env and fill in the values."
296
+ )
297
+
298
+
299
+ validate_env()
300
+ ```
301
+
302
+ ### spec.observability
303
+
304
+ AutoGen does not have native Langfuse/LangSmith tracing hooks; inject via environment variables
305
+ and the `autogen_ext` telemetry extension if available:
306
+
307
+ ```python
308
+ # ── Tracing: Langfuse ─────────────────────────────────────────────────────────
309
+ # Set env vars before creating model_client — autogen_ext picks them up automatically
310
+ import os
311
+ os.environ.setdefault("LANGFUSE_PUBLIC_KEY", os.environ.get("LANGFUSE_PUBLIC_KEY", ""))
312
+ os.environ.setdefault("LANGFUSE_SECRET_KEY", os.environ.get("AGENTSPEC_SECRET_LANGFUSE_SECRET_KEY", ""))
313
+ os.environ.setdefault("LANGFUSE_HOST", os.environ.get("LANGFUSE_HOST", "https://cloud.langfuse.com"))
314
+ ```
315
+
316
+ ---
317
+
318
+ ## Complete agent.py Structure
319
+
320
+ Generate sections in this exact order:
321
+
322
+ 1. **Module docstring** — agent name, version, model provider/id, tools count, memory backend
323
+ 2. **Imports**:
324
+ - `import asyncio`
325
+ - `import logging`
326
+ - `import os`
327
+ - `import datetime` (if `$func:now_iso` used)
328
+ - `from autogen_agentchat.agents import AssistantAgent`
329
+ - `from autogen_agentchat.ui import Console`
330
+ - Provider model client import
331
+ - Memory imports (if `spec.memory` is set)
332
+ - Tool imports: `from tools import AGENT_TOOLS` (if tools exist)
333
+ - Guardrail imports (if `spec.guardrails` is set)
334
+ 3. **Logger setup**: `logger = logging.getLogger("agentspec.audit")`
335
+ 4. **Observability setup** (env vars for Langfuse / OpenTelemetry)
336
+ 5. **Env var validation** (`validate_env()` call)
337
+ 6. **System prompt loading** (if `spec.prompts.system` is a `$file:` ref)
338
+ 7. **Prompt path constant** (if `$file:` ref): `SYSTEM_PROMPT_PATH = "path/to/prompt.txt"`
339
+ 8. **Model client setup**
340
+ 9. **Memory setup** (if `spec.memory` is set)
341
+ 10. **Agent definition**:
342
+ ```python
343
+ agent = AssistantAgent(
344
+ name="{agent_name}",
345
+ model_client=model_client,
346
+ tools=AGENT_TOOLS, # omit if no tools
347
+ system_message=load_system_prompt(),
348
+ reflect_on_tool_use=True,
349
+ model_client_stream=True,
350
+ memory=[user_memory], # omit if no memory
351
+ )
352
+ ```
353
+ 11. **`run_agent()` coroutine** — applies guardrails, calls `agent.run_stream()`, returns string
354
+ 12. **`main()` coroutine** — reads argv[1] as task, calls `run_agent()`, prints result, closes model client
355
+ 13. **`if __name__ == "__main__"` block**: `asyncio.run(main())`
356
+
357
+ ---
358
+
359
+ ## server.py — FastAPI + streaming (when spec.api is set)
360
+
361
+ ```python
362
+ """
363
+ FastAPI server for {agent_name}
364
+ Generated by AgentSpec
365
+ """
366
+
367
+ import asyncio
368
+ import os
369
+ from fastapi import FastAPI, HTTPException
370
+ from fastapi.responses import StreamingResponse
371
+ from pydantic import BaseModel
372
+ from agent import agent, model_client, run_agent
373
+
374
+ app = FastAPI(title="{agent_name}", version="{version}")
375
+
376
+ _RATE_LIMIT_RPM = {requests_per_minute} # spec.api.rateLimit.requestsPerMinute
377
+
378
+
379
+ class ChatRequest(BaseModel):
380
+ message: str
381
+ stream: bool = False
382
+
383
+
384
+ class ChatResponse(BaseModel):
385
+ response: str
386
+
387
+
388
+ @app.get("/health")
389
+ async def health() -> dict:
390
+ return {"status": "ok"}
391
+
392
+
393
+ @app.get("/capabilities")
394
+ async def capabilities() -> dict:
395
+ from manifest import get_capabilities
396
+ return get_capabilities()
397
+
398
+
399
+ @app.post("/chat")
400
+ async def chat(req: ChatRequest):
401
+ if req.stream:
402
+ async def event_stream():
403
+ async for chunk in agent.run_stream(task=req.message):
404
+ if hasattr(chunk, "content") and isinstance(chunk.content, str):
405
+ yield f"data: {chunk.content}\n\n"
406
+ yield "data: [DONE]\n\n"
407
+ return StreamingResponse(event_stream(), media_type="text/event-stream")
408
+ response = await run_agent(req.message)
409
+ return ChatResponse(response=response)
410
+
411
+
412
+ @app.on_event("shutdown")
413
+ async def shutdown():
414
+ await model_client.close()
415
+ ```
416
+
417
+ ---
418
+
419
+ ## manifest.py — always generated
420
+
421
+ ```python
422
+ """
423
+ Manifest loader for {agent_name}
424
+ Generated by AgentSpec
425
+ """
426
+
427
+ import yaml
428
+ from pathlib import Path
429
+
430
+ _MANIFEST_PATH = Path(__file__).parent / "agent.yaml"
431
+
432
+
433
+ def load_manifest() -> dict:
434
+ with open(_MANIFEST_PATH, "r", encoding="utf-8") as f:
435
+ return yaml.safe_load(f)
436
+
437
+
438
+ def get_capabilities() -> dict:
439
+ manifest = load_manifest()
440
+ spec = manifest.get("spec", {})
441
+ tools = [
442
+ {
443
+ "name": t.get("name"),
444
+ "description": t.get("description"),
445
+ "annotations": t.get("annotations", {}),
446
+ }
447
+ for t in spec.get("tools", [])
448
+ ]
449
+ return {
450
+ "metadata": manifest.get("metadata", {}),
451
+ "tools": tools,
452
+ "compliance": spec.get("compliance", {}),
453
+ }
454
+ ```
455
+
456
+ ---
457
+
458
+ ## requirements.txt Template
459
+
460
+ Always include base packages. Add extras based on manifest:
461
+
462
+ ```
463
+ # Base (always)
464
+ autogen-agentchat>=0.4.0
465
+ autogen-ext[openai]>=0.4.0
466
+ python-dotenv>=1.0.0
467
+ pyyaml>=6.0
468
+
469
+ # Model provider
470
+ autogen-ext[anthropic]>=0.4.0 # provider: anthropic
471
+ autogen-ext[azure]>=0.4.0 # provider: azure
472
+
473
+ # Memory
474
+ redis>=5.0.0 # spec.memory.shortTerm.backend: redis
475
+ chromadb>=0.5.0 # spec.memory.longTerm.backend: chroma
476
+
477
+ # API server
478
+ fastapi>=0.110.0 # spec.api is set
479
+ uvicorn[standard]>=0.29.0 # spec.api is set
480
+
481
+ # Observability
482
+ langfuse>=2.0.0 # spec.observability.tracing.backend: langfuse
483
+
484
+ # Guardrails
485
+ detoxify>=0.5.0 # toxicity-filter guardrail
486
+ deepeval>=1.0.0 # hallucination-detector guardrail
487
+ ```
488
+
489
+ ---
490
+
491
+ ## .env.example Rules
492
+
493
+ - One line per env var referenced in the manifest
494
+ - Strip `$env:` prefix for the variable name
495
+ - For `$secret:name`, the env var is `AGENTSPEC_SECRET_NAME` (uppercase, `-`→`_`)
496
+ - Add a comment describing what each var is for
497
+ - Group by concern: model, memory, observability, agent config
498
+
499
+ ---
500
+
501
+ ## README.md Template
502
+
503
+ ```markdown
504
+ # {agent_name}
505
+
506
+ {description}
507
+
508
+ **Generated by [AgentSpec](https://agentspec.io) v{version}**
509
+
510
+ ## Stack
511
+
512
+ | Component | Value |
513
+ |-----------|-------|
514
+ | Framework | AutoGen (autogen-agentchat) |
515
+ | Model | {provider}/{model_id} |
516
+ | Memory | {memory_backend} |
517
+ | Tracing | {tracing_backend} |
518
+ | Tools | {tools_count} |
519
+
520
+ ## Quick Start
521
+
522
+ ```bash
523
+ python -m venv .venv && source .venv/bin/activate
524
+ pip install -r requirements.txt
525
+ cp .env.example .env # fill in your API keys
526
+ python agent.py "Hello, what can you help me with?"
527
+ ```
528
+
529
+ ## Run the API server
530
+
531
+ ```bash
532
+ uvicorn server:app --reload
533
+ ```
534
+
535
+ ## Tools
536
+
537
+ {tool_list}
538
+
539
+ ## Environment Variables
540
+
541
+ {env_var_list}
542
+ ```
543
+
544
+ ---
545
+
546
+ ## Quality Checklist
547
+
548
+ | Check | Verify |
549
+ |---|---|
550
+ | `$secret:` resolution | `$secret:langfuse-secret-key` → `AGENTSPEC_SECRET_LANGFUSE_SECRET_KEY` |
551
+ | No literal keys | No `sk-`, `pk-`, raw API key strings in generated code |
552
+ | `validate_env()` called | At module top-level, before any connections |
553
+ | `tools.py` + `tool_implementations.py` generated | When `spec.tools` is non-empty |
554
+ | Tool params typed | No `**kwargs` — always typed parameters |
555
+ | Guardrails applied in `run_agent()` | Input before agent call, output after |
556
+ | `manifest.py` always generated | Required regardless of spec sections present |
557
+ | `get_capabilities()` returns tools with annotations | `readOnlyHint`, `destructiveHint`, `idempotentHint` carried through |
558
+ | `model_client.close()` called | In `main()` coroutine after agent run |
559
+ | Requirements complete | All packages match imports in generated files |