@agentspec/adapter-claude 0.2.2 → 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.
- package/LICENSE +183 -0
- package/dist/index.d.ts +40 -47
- package/dist/index.js +35 -194
- package/dist/index.js.map +1 -1
- package/package.json +12 -24
- package/dist/skills/autogen.md +0 -559
- package/dist/skills/crewai.md +0 -397
- package/dist/skills/guidelines.md +0 -141
- package/dist/skills/helm.md +0 -151
- package/dist/skills/langgraph.md +0 -1463
- package/dist/skills/mastra.md +0 -372
- package/dist/skills/scan.md +0 -182
package/dist/skills/autogen.md
DELETED
|
@@ -1,559 +0,0 @@
|
|
|
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-opus-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 |
|