maestro-bundle 1.7.0 → 1.9.0

package/templates/bundle-ai-agents-deep/skills/deep-agent-deployment/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: deep-agent-deployment
+description: Deploy Deep Agents as APIs or CLI tools using FastAPI, LangGraph Platform, or Docker. Use when serving the agent as an API, deploying to production, or creating a CLI interface.
+version: 1.0.0
+author: Maestro
+---
+
+# Deep Agent Deployment
+
+Deploy your Deep Agent as a REST API, WebSocket server, or CLI tool for production use.
+
+## When to Use
+- When serving the agent as an API endpoint
+- When deploying to LangGraph Platform
+- When creating a Docker container for the agent
+- When building a CLI interface
+
+## Available Operations
+1. Serve as FastAPI REST API
+2. Add WebSocket streaming
+3. Deploy with Docker
+4. Deploy to LangGraph Platform
+5. Create CLI interface
+
+## Multi-Step Workflow
+
+### Step 1: FastAPI REST API
+
+```python
+# api/server.py
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from deepagents import create_deep_agent
+from langgraph.checkpoint.postgres import PostgresSaver
+
+app = FastAPI(title="Deep Agent API")
+
+agent = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    checkpointer=PostgresSaver(conn_string=os.environ["DATABASE_URL"])
+)
+
+class ChatRequest(BaseModel):
+    message: str
+    thread_id: str
+
+class ChatResponse(BaseModel):
+    response: str
+    thread_id: str
+
+@app.post("/api/chat", response_model=ChatResponse)
+async def chat(req: ChatRequest):
+    config = {"configurable": {"thread_id": req.thread_id}}
+    result = agent.invoke(
+        {"messages": [{"role": "user", "content": req.message}]},
+        config=config
+    )
+    return ChatResponse(
+        response=result["messages"][-1].content,
+        thread_id=req.thread_id
+    )
+```
+
+### Step 2: WebSocket Streaming
+
+```python
+# api/websocket.py
+from fastapi import WebSocket
+
+@app.websocket("/ws/chat/{thread_id}")
+async def ws_chat(websocket: WebSocket, thread_id: str):
+    await websocket.accept()
+    config = {"configurable": {"thread_id": thread_id}}
+
+    while True:
+        message = await websocket.receive_text()
+
+        async for event in agent.astream_events(
+            {"messages": [{"role": "user", "content": message}]},
+            config=config,
+            version="v2"
+        ):
+            if event["event"] == "on_chat_model_stream":
+                chunk = event["data"]["chunk"].content
+                if chunk:
+                    await websocket.send_text(chunk)
+
+        await websocket.send_text("[DONE]")
+```
+
+### Step 3: Docker
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY src/ ./src/
+COPY skills/ ./skills/
+USER 1000
+EXPOSE 8000
+CMD ["uvicorn", "src.api.server:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+```bash
+docker build -t deep-agent:latest .
+docker run -p 8000:8000 -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY deep-agent:latest
+```
+
+### Step 4: LangGraph Platform
+
+```python
+# langgraph.json
+{
+    "graphs": {
+        "agent": {
+            "path": "src/agent/main.py:agent"
+        }
+    },
+    "dependencies": ["deepagents", "langchain"]
+}
+```
+
+```bash
+# Deploy to LangGraph Platform
+langgraph deploy
+```
+
+### Step 5: CLI Interface
+
+```python
+# cli.py
+import asyncio
+from deepagents import create_deep_agent
+
+async def main():
+    agent = create_deep_agent(model="anthropic:claude-sonnet-4-6")
+    config = {"configurable": {"thread_id": "cli-session"}}
+
+    print("Deep Agent CLI (type 'exit' to quit)")
+    while True:
+        user_input = input("\n> ")
+        if user_input.lower() == "exit":
+            break
+
+        async for event in agent.astream_events(
+            {"messages": [{"role": "user", "content": user_input}]},
+            config=config,
+            version="v2"
+        ):
+            if event["event"] == "on_chat_model_stream":
+                print(event["data"]["chunk"].content, end="", flush=True)
+
+asyncio.run(main())
+```
+
+### Step 6: Verify
+
+```bash
+# Test API
+uvicorn src.api.server:app --reload --port 8000
+curl -X POST http://localhost:8000/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Hello", "thread_id": "test-1"}'
+
+# Test CLI
+python cli.py
+```
+
+## Resources
+- `references/deployment-checklist.md` — Production deployment checklist
+
+## Examples
+
+### Example 1: REST API
+User asks: "Serve the agent as an API"
+Response approach:
+1. Create FastAPI app with `/api/chat` endpoint
+2. Add PostgresSaver for persistence
+3. Run with `uvicorn`
+4. Test with curl
+
+### Example 2: Streaming UI
+User asks: "Real-time streaming like ChatGPT"
+Response approach:
+1. Add WebSocket endpoint
+2. Use `astream_events` for token-by-token streaming
+3. Send chunks via WebSocket
+4. Frontend connects and renders
+
+## Notes
+- Always use PostgresSaver in production (not MemorySaver)
+- Set resource limits in Docker (memory, CPU)
+- Add health check endpoint: `GET /health`
+- Rate limit the API endpoints
+- Use environment variables for API keys, never hardcode

package/templates/bundle-ai-agents-deep/skills/deep-agent-hitl/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: deep-agent-hitl
+description: Configure human-in-the-loop approval workflows for Deep Agents. Use when requiring human approval before destructive operations like file deletion, deployment, or email sending.
+version: 1.0.0
+author: Maestro
+---
+
+# Deep Agent Human-in-the-Loop
+
+Configure approval gates that pause the agent and wait for human approval before executing sensitive operations.
+
+## When to Use
+- When the agent should ask before deleting files
+- When deploys require human approval
+- When sending emails/messages needs confirmation
+- When any destructive operation needs a gate
+
+## Available Operations
+1. Configure `interrupt_on` per tool
+2. Handle approval/rejection flow
+3. Resume after approval
+4. Custom approval decisions
+
+## Multi-Step Workflow
+
+### Step 1: Configure Interrupts
+
+```python
+from deepagents import create_deep_agent
+from langgraph.checkpoint.memory import MemorySaver
+
+agent = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    tools=[delete_file, read_file, send_email, deploy],
+    interrupt_on={
+        "delete_file": True,       # Always ask
+        "read_file": False,         # Never ask
+        "send_email": True,         # Always ask
+        "deploy": True,             # Always ask
+        "write_file": {             # Custom decisions
+            "allowed_decisions": ["approve", "reject", "modify"]
+        }
+    },
+    checkpointer=MemorySaver()  # REQUIRED for interrupts
+)
+```
+
+### Step 2: Run and Handle Interrupts
+
+```python
+config = {"configurable": {"thread_id": "session-1"}}
+
+# Agent runs until it hits an interrupt
+result = agent.invoke(
+    {"messages": [{"role": "user", "content": "Delete the old log files"}]},
+    config=config
+)
+
+# Check if agent is waiting for approval
+if result.get("__interrupt__"):
+    interrupt = result["__interrupt__"]
+    print(f"Agent wants to: {interrupt['tool']} with args: {interrupt['args']}")
+
+    # Approve
+    result = agent.invoke(
+        {"messages": [{"role": "user", "content": "approved"}]},
+        config=config
+    )
+
+    # Or reject
+    # result = agent.invoke(
+    #     {"messages": [{"role": "user", "content": "rejected, don't delete those"}]},
+    #     config=config
+    # )
+```
+
+### Step 3: Build Approval UI (FastAPI)
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class ApprovalRequest(BaseModel):
+    session_id: str
+    decision: str  # "approve" or "reject"
+    reason: str = ""
+
+@app.post("/api/approve")
+async def approve(req: ApprovalRequest):
+    config = {"configurable": {"thread_id": req.session_id}}
+    result = agent.invoke(
+        {"messages": [{"role": "user", "content": req.decision}]},
+        config=config
+    )
+    return {"status": "resumed", "result": result["messages"][-1].content}
+```
+
+### Step 4: Verify
+
+```bash
+python -c "
+from deepagents import create_deep_agent
+from langchain.tools import tool
+from langgraph.checkpoint.memory import MemorySaver
+
+@tool
+def dangerous_operation(action: str) -> str:
+    '''Execute a dangerous operation.'''
+    return f'Executed: {action}'
+
+agent = create_deep_agent(
+    tools=[dangerous_operation],
+    interrupt_on={'dangerous_operation': True},
+    checkpointer=MemorySaver()
+)
+
+config = {'configurable': {'thread_id': 'test-hitl'}}
+result = agent.invoke(
+    {'messages': [{'role': 'user', 'content': 'Run dangerous operation: cleanup'}]},
+    config=config
+)
+print('Interrupted:', bool(result.get('__interrupt__')))
+"
+```
+
+## Resources
+- `references/hitl-patterns.md` — Human-in-the-loop patterns
+
+## Examples
+
+### Example 1: Approve Before Deploy
+User asks: "Agent should ask before deploying"
+Response approach:
+1. Add `"deploy": True` to `interrupt_on`
+2. Agent pauses before calling deploy tool
+3. Show user what will be deployed
+4. Resume on approval
+
+### Example 2: Custom Approval Decisions
+User asks: "For file writes, allow approve, reject, or modify"
+Response approach:
+1. Use `{"write_file": {"allowed_decisions": ["approve", "reject", "modify"]}}`
+2. If "modify", user provides updated content
+3. Agent retries with modified input
+
+## Notes
+- `checkpointer` is REQUIRED — without it, interrupts don't work
+- Agent remembers state during interrupt — it resumes exactly where it paused
+- Use for: delete, deploy, send email, run destructive commands
+- Don't interrupt on read-only operations (wastes user's time)

package/templates/bundle-ai-agents-deep/skills/deep-agent-memory/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: deep-agent-memory
+description: Configure persistent memory for Deep Agents using AGENTS.md and LangGraph Store. Use when the agent needs to remember context across sessions, persist learnings, or maintain long-term knowledge.
+version: 1.0.0
+author: Maestro
+---
+
+# Deep Agent Memory
+
+Give your Deep Agent persistent memory that survives across sessions using AGENTS.md files and LangGraph Store.
+
+## When to Use
+- When the agent should remember context between sessions
+- When loading project-specific knowledge at startup
+- When persisting learnings across threads
+- When configuring AGENTS.md for persistent context
+
+## Available Operations
+1. Load AGENTS.md as persistent context
+2. Configure LangGraph Store for cross-thread memory
+3. Use CompositeBackend for memory routing
+4. Persist agent learnings
+
+## Multi-Step Workflow
+
+### Step 1: AGENTS.md as Memory
+
+```python
+from deepagents import create_deep_agent
+from deepagents.backends.utils import create_file_data
+from langgraph.checkpoint.memory import MemorySaver
+
+agents_md = """
+# Project Context
+
+## Architecture
+This project uses Clean Architecture with Python FastAPI.
+
+## Conventions
+- Use Pydantic for all DTOs
+- Pytest for testing
+- Ruff for linting
+"""
+
+agent = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    memory=["/AGENTS.md"],
+    checkpointer=MemorySaver()
+)
+
+result = agent.invoke(
+    {
+        "messages": [{"role": "user", "content": "What architecture do we use?"}],
+        "files": {"/AGENTS.md": create_file_data(agents_md)}
+    },
+    config={"configurable": {"thread_id": "session-1"}}
+)
+```
+
+### Step 2: Persistent Store Memory
+
+```python
+from deepagents import create_deep_agent
+from deepagents.backends import StoreBackend
+from langgraph.store.postgres import PostgresStore
+from langgraph.checkpoint.postgres import PostgresSaver
+
+# Production: PostgreSQL for both
+store = PostgresStore(conn_string="postgresql://user:pass@localhost/agents")
+checkpointer = PostgresSaver(conn_string="postgresql://user:pass@localhost/agents")
+
+agent = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    backend=lambda rt: StoreBackend(rt),
+    store=store,
+    checkpointer=checkpointer,
+    memory=["/AGENTS.md"]
+)
+```
+
+### Step 3: CompositeBackend with Memory
+
+```python
+from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
+
+composite = lambda rt: CompositeBackend(
+    default=StateBackend(rt),
+    routes={
+        "/memories/": StoreBackend(rt),   # Long-term memory: persistent
+        "/workspace/": StateBackend(rt),   # Working files: ephemeral
+    }
+)
+
+agent = create_deep_agent(
+    backend=composite,
+    store=InMemoryStore()
+)
+# Agent writes to /memories/ for things it wants to remember
+# Agent writes to /workspace/ for temporary work
+```
+
+### Step 4: Consistent Thread IDs
+
+```python
+# Same thread_id = same conversation context
+config = {"configurable": {"thread_id": f"project-{project_id}"}}
+
+# First invocation
+agent.invoke({"messages": [msg1]}, config=config)
+
+# Later invocation — agent remembers the first one
+agent.invoke({"messages": [msg2]}, config=config)
+```
+
+### Step 5: Verify
+
+```bash
+python -c "
+from deepagents import create_deep_agent
+from langgraph.checkpoint.memory import MemorySaver
+
+agent = create_deep_agent(checkpointer=MemorySaver())
+config = {'configurable': {'thread_id': 'test-memory'}}
+
+# First message
+agent.invoke({'messages': [{'role': 'user', 'content': 'My name is João'}]}, config=config)
+
+# Second message — should remember
+result = agent.invoke({'messages': [{'role': 'user', 'content': 'What is my name?'}]}, config=config)
+print(result['messages'][-1].content)
+"
+```
+
+## Resources
+- `references/memory-patterns.md` — Memory architecture patterns
+
+## Examples
+
+### Example 1: Project Context Memory
+User asks: "Agent should know our project conventions"
+Response approach:
+1. Write AGENTS.md with conventions
+2. Pass via `memory=["/AGENTS.md"]`
+3. Agent loads it every session
+
+### Example 2: Learning Memory
+User asks: "Agent should remember what worked in previous sessions"
+Response approach:
+1. Use CompositeBackend with StoreBackend for `/memories/`
+2. Agent writes learnings to `/memories/`
+3. Next session, agent reads from `/memories/`
+
+## Notes
+- `checkpointer` is REQUIRED for memory to persist
+- AGENTS.md follows the agents.md standard (https://agents.md/)
+- Use PostgresStore for production, InMemoryStore for dev
+- Thread ID determines conversation scope
+- Memory files are loaded at session start

package/templates/bundle-ai-agents-deep/skills/deep-agent-middleware/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: deep-agent-middleware
+description: Configure and create custom middleware for Deep Agents including logging, validation, and tool interception. Use when adding cross-cutting concerns, logging tool calls, or modifying agent behavior.
+version: 1.0.0
+author: Maestro
+---
+
+# Deep Agent Middleware
+
+Add cross-cutting concerns to Deep Agents with built-in and custom middleware for logging, validation, rate limiting, and tool interception.
+
+## When to Use
+- When you need to log all tool calls
+- When you need to validate inputs before tools execute
+- When you need rate limiting on API calls
+- When you need custom behavior around tool execution
+
+## Available Operations
+1. Use built-in middleware (TodoList, Filesystem, SubAgent, Summarization)
+2. Create custom middleware with `@wrap_tool_call`
+3. Chain multiple middleware
+4. Add conditional middleware
+
+## Multi-Step Workflow
+
+### Step 1: Understand Built-in Middleware
+
+These are automatically active:
+
+| Middleware | What it does | Can disable? |
+|---|---|---|
+| TodoListMiddleware | `write_todos` tool for planning | No |
+| FilesystemMiddleware | `ls`, `read_file`, `write_file`, etc. | No |
+| SubAgentMiddleware | `task` tool for delegation | No |
+| SummarizationMiddleware | Compresses long conversations | No |
+| AnthropicPromptCachingMiddleware | Token optimization for Anthropic | Auto |
+| PatchToolCallsMiddleware | Repairs broken tool calls | Auto |
+
+### Step 2: Create Custom Middleware
+
+```python
+# agent/middleware.py
+from langchain.agents.middleware import wrap_tool_call
+import time
+import logging
+
+logger = logging.getLogger(__name__)
+
+@wrap_tool_call
+def log_tool_calls(request, handler):
+    """Log every tool call with timing."""
+    start = time.time()
+    logger.info(f"[TOOL] {request.name} called with: {request.args}")
+
+    result = handler(request)
+
+    duration = time.time() - start
+    logger.info(f"[TOOL] {request.name} completed in {duration:.2f}s")
+    return result
+
+@wrap_tool_call
+def validate_file_paths(request, handler):
+    """Prevent access to sensitive files."""
+    if request.name in ("read_file", "write_file", "edit_file"):
+        path = request.args.get("path", "")
+        blocked = [".env", "secrets", "credentials", ".git/config"]
+        if any(b in path for b in blocked):
+            return f"Access denied: {path} is a protected file"
+
+    return handler(request)
+
+@wrap_tool_call
+def rate_limit_api_calls(request, handler):
+    """Rate limit external API calls."""
+    api_tools = ["internet_search", "call_api"]
+    if request.name in api_tools:
+        time.sleep(1)  # Simple rate limit
+
+    return handler(request)
+```
+
+### Step 3: Register Middleware
+
+```python
+from deepagents import create_deep_agent
+from agent.middleware import log_tool_calls, validate_file_paths, rate_limit_api_calls
+
+agent = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    middleware=[
+        log_tool_calls,
+        validate_file_paths,
+        rate_limit_api_calls,
+    ]
+)
+```
+
+### Step 4: Verify
+
+```bash
+# Run agent and check logs
+python agent/main.py 2>&1 | grep "[TOOL]"
+
+# Run tests
+pytest tests/test_middleware.py -v
+```
+
+## Resources
+- `references/middleware-guide.md` — Middleware patterns and best practices
+
+## Examples
+
+### Example 1: Add Logging
+User asks: "Log all tool calls with timing"
+Response approach:
+1. Create `@wrap_tool_call` that logs name, args, duration
+2. Register in `create_deep_agent(middleware=[...])`
+3. Run agent, check logs
+
+### Example 2: Block Sensitive Files
+User asks: "Agent should not read .env files"
+Response approach:
+1. Create middleware that checks file paths
+2. Return "Access denied" for blocked paths
+3. Test with agent trying to read .env
+
+## Notes
+- Do NOT mutate agent attributes after initialization — use graph state
+- Middleware executes in order: first registered = outermost wrapper
+- Built-in middleware cannot be removed
+- Keep middleware lightweight — it runs on every tool call