Skip to content

README.md

Latest commit

 

History

History
225 lines (164 loc) · 7.34 KB

README.md

File metadata and controls

225 lines (164 loc) · 7.34 KB

AgentSpec

npm CI License Slack

One agent.yaml. Validate, health-check, audit, and generate any AI agent.

npm install -g @agentspec/cli
agentspec validate agent.yaml   # Schema validation
agentspec health agent.yaml     # Runtime health checks
agentspec audit agent.yaml      # Compliance scoring (OWASP LLM Top 10)
agentspec generate agent.yaml --framework langgraph

What you can do

🔑 = requires an LLM API key  ·  all other commands are fully local, no API key needed

  • Define your agent in a single agent.yaml — model, tools, memory, guardrails, prompts
  • Validate schema with instant feedback and path-aware errors
  • Health-check all runtime dependencies (env vars, model API, Redis, Postgres, MCP servers)
  • Audit compliance against OWASP LLM Top 10, model resilience, and memory hygiene packs
  • 🔑 Generate production-ready LangGraph, CrewAI, Mastra, or AutoGen code
  • 🔑 Scan an existing codebase and auto-generate the manifest
  • Evaluate agent quality against JSONL datasets with CI pass/fail gates
  • Meter token usage per model — in-process ledger, sidecar aggregation, CRD visibility
  • Deploy to Kubernetes — operator injects sidecar, exposes /health/ready, /gap, and /usage
  • Export to A2A / AgentCard format
  • Visual dashboard for fleet-wide agent observability (coming soon)
  • Native OpenTelemetry trace export (coming soon)

How it Works

AgentSpec Architecture

  • agent.yaml is the single source of truth — the SDK reads it at runtime, the CLI validates and audits it, the operator deploys it
  • Sidecar is injected automatically by the operator and exposes live /health/ready, /gap, /explore, and /usage endpoints without touching agent code
  • CLI wraps the SDK for local development — validate, audit, generate, scan, evaluate
  • MCP Server bridges the sidecar to Claude Code and VS Code for in-editor introspection

Quick Start

# Install
npm install -g @agentspec/cli

# Create a manifest interactively (no API key needed)
agentspec init

# Or scan an existing codebase (🔑 requires a codegen provider, see below)
agentspec scan --dir ./src/

# Validate, health-check, audit (no API key needed)
agentspec validate agent.yaml
agentspec health agent.yaml
agentspec audit agent.yaml

# Generate runnable code (🔑 requires a codegen provider, see below)
agentspec generate agent.yaml --framework langgraph --output ./generated/

🔑 scan and generate need a codegen provider. AgentSpec auto-detects the first one available:

# Option A: Claude subscription (Pro / Max), no API key
claude auth login

# Option B: any OpenAI-compatible endpoint (OpenAI, OpenRouter, Groq, Together, Ollama, Nvidia NIM, ...)
export AGENTSPEC_LLM_API_KEY=sk-...
export AGENTSPEC_LLM_MODEL=gpt-4o-mini
# export AGENTSPEC_LLM_BASE_URL=https://openrouter.ai/api/v1   # optional, defaults to OpenAI

# Option C: Anthropic API key
export ANTHROPIC_API_KEY=sk-ant-...

Check which one is active with agentspec provider-status. Full setup, CI examples, and overrides in the Provider Authentication guide.

Kubernetes

# One-line install
curl -fsSL https://raw.githubusercontent.com/agents-oss/agentspec/main/install.sh | bash

# Or with Helm
helm install agentspec-operator \
  oci://ghcr.io/agents-oss/charts/agentspec-operator \
  --version 0.1.1 \
  --namespace agentspec-system --create-namespace

SDK (Node.js)

npm install @agentspec/sdk

CLI Output

Health check:

  AgentSpec Health — budget-assistant
  ─────────────────────────────────────
  Status: ● healthy

  ENV
    ✓ env:GROQ_API_KEY
    ✓ env:DATABASE_URL
    ✓ env:REDIS_URL

  MODEL
    ✓ model:groq/llama-3.3-70b-versatile (94ms)
    ✓ model-fallback:azure/gpt-4 (112ms)

  MEMORY
    ✓ memory.shortTerm:redis (3ms)
    ✓ memory.longTerm:postgres (5ms)

Compliance audit:

  AgentSpec Audit — budget-assistant
  ────────────────────────────────────
  Score : B  82/100

  Category Scores
    owasp-llm-top10          75% ███████████████░░░░░
    model-resilience         100% ████████████████████
    memory-hygiene            80% ████████████████░░░░

  Violations (2)
    [high] SEC-LLM-10 — API keys use $secret, not $env
    [medium] MEM-04 — Vector store namespace isolated

Manifest

apiVersion: agentspec.io/v1
kind: AgentSpec

metadata:
  name: budget-assistant
  version: 1.0.0

spec:
  model:
    provider: openai
    id: gpt-4o-mini
    apiKey: $env:OPENAI_API_KEY
    fallback:
      provider: azure
      id: gpt-4
      apiKey: $env:AZURE_OPENAI_API_KEY

  prompts:
    system: $file:prompts/system.md

  tools:
    - name: get-balance
      type: function
      description: "Get account balance"
      module: $file:tools/finance.py

  guardrails:
    input:
      - type: prompt-injection
        action: reject

  compliance:
    packs:
      - owasp-llm-top10
      - model-resilience

See the full manifest reference for all fields including memory, evaluation, MCP, subagents, and observability.

Documentation

Full docs at agents-oss.github.io/agentspec
Quick Start Up and running in 5 minutes
Manifest Concepts All manifest fields explained
Health Checks Runtime dependency checking
Compliance & Audit OWASP LLM Top 10 scoring
CLI Reference All commands and flags

Tech Stack

TypeScript · pnpm workspaces · Zod · js-yaml · commander · vitest · tsup · Python · Kopf · FastAPI · Fastify · Helm

License

Apache 2.0

Contributing

Issues and PRs welcome at github.com/agents-oss/agentspec.

Join the conversation on Slack — ask questions in #help, share what you're building in #show-and-tell, or hack on the project in #contributing.