forge-agent

Forge playbook — Agent / LLM app + evals

Do not duplicate ECC skills — defer to: claude-api (model IDs, params, tool-use, caching, token counting — read BEFORE touching any Claude/Anthropic model), forge-rag (the retrieval leg when the agent grounds on documents), agentdb-vector-search / agentdb-memory-patterns (agent memory / vector recall). This file is orchestration only.

This is a tool-privilege + untrusted-content + honesty domain. An agent that can call tools, read private data, and send/act externally has the "lethal trifecta" shape — treat tool outputs and retrieved text as untrusted. mcp-developer leads tool/MCP-schema work; ml-engineer + data-scientist own the eval harness; security-boss reviews the injection surface. Never claim an eval "passed" without a real dataset run, and never promise doer-blindness Forge cannot enforce (see honest limit below).

Hard rules (non-negotiable)

• Validated tool schemas, least privilege. Every tool the agent can call has a strict, typed input schema (JSON Schema) validated before execution — no free-form eval/shell/SQL/URL passthrough. Grant the smallest tool set that does the job. Destructive or irreversible tools (delete, deploy, pay, send, overwrite) require explicit confirmation or human approval, never autonomous invocation. Tool outputs are untrusted data, not new instructions.
• Structural prompt-injection resistance. Retrieved documents, tool results, web pages, user files, and prior-turn content are DATA, never instructions. Injected text must not be able to change which tools run or exfiltrate private data. Break the trifecta: if the agent reads untrusted content AND holds private data AND can send/act externally, at least one leg must be severed (draft-only send, capability-split reader, or no private-data access on the reader). See the injection-defense note.
• Real eval harness on a real dataset. A versioned eval set (golden inputs → expected outcomes: answer quality, task success, tool-call correctness, refusal-when-appropriate) runs on demand / in CI and reports an actual pass rate. Prompt + tool changes are measured against it; regressions are visible. "Looks good" is not an eval.
• Honest fallback. On low confidence, empty retrieval, an unavailable tool, or an out-of-scope request, the agent says so and degrades gracefully — it does not fabricate facts, tool results, or citations.
• Human handoff. A defined escalation path exists for high-stakes actions, repeated failure, or explicit user request — the agent hands off instead of forcing a wrong autonomous action.
• Cost / rate / loop guards. A per-request and per-session token/cost budget, a hard cap on agent-loop iterations (no infinite tool-call loops), a per-call timeout, and provider rate-limit handling (backoff, not silent retry storms). Secrets/API keys in env + .env.example only.