Guardrails

What is agent.guard.yml?

Every AgentVoy project includes an agent.guard.yml file — a universal declarative config that defines what your agent can and cannot do. It controls:

Full config reference

version: "1.0"

identity:
  name: my-agent
  description: Research assistant agent
  version: 0.1.0

model:
  provider: openai              # openai | anthropic | google | ollama | groq | mistral
  model: gpt-4o                 # Model name
  api_key_env: OPENAI_API_KEY   # Env var containing your API key

permissions:
  network:
    mode: restricted             # open | restricted | blocked
    allow:                       # Allowed domains (when restricted)
      - "*.github.com"
      - "*.stackoverflow.com"
  filesystem:
    read: ["./**"]               # Glob patterns for read access
    write: ["./output/**"]       # Glob patterns for write access
  tools:
    require_approval:            # Tools that need user confirmation
      - "delete_*"
      - "send_*"
      - "deploy_*"
  execution:
    allow_shell: false           # Allow shell command execution
    allow_subprocess: false      # Allow spawning subprocesses

guardrails:
  input:
    block_prompt_injection: true # Detect and block injection attempts
    max_tokens: 4096             # Maximum input token count
    pii_detection: warn          # off | warn | block
    content_filter: moderate     # off | moderate | strict
  output:
    block_harmful_content: true  # Filter harmful output
    max_output_tokens: 8192      # Maximum output token count
  behavior:
    max_iterations: 20           # Max agent loops
    timeout: 5m                  # Maximum execution time
    cost_limit: "$1.00"          # Maximum cost per session

observability:
  tracing: true                  # Enable execution tracing
  log_level: info                # debug | info | warn | error
  cost_tracking: true            # Track API costs

Runtime enforcement

Install the Python guard package to enforce rules at runtime:

pip install agentvoy-guard

Use it in your agent code:

from agentvoy_guard import Guard

guard = Guard.from_config()  # reads agent.guard.yml

with guard.session() as session:
    session.check_input(user_prompt)    # validates input
    result = my_agent.run(user_prompt)  # your agent logic
    session.check_output(result)        # validates output

print(guard.last_summary)  # see what checks ran

Common configurations

Strict mode (production)

permissions:
  network:
    mode: restricted
    allow: ["api.openai.com"]
  execution:
    allow_shell: false
    allow_subprocess: false
guardrails:
  input:
    block_prompt_injection: true
    content_filter: strict
  output:
    block_harmful_content: true
  behavior:
    timeout: 2m
    cost_limit: "$0.50"

Development mode (permissive)

permissions:
  network:
    mode: open
  execution:
    allow_shell: true
guardrails:
  input:
    content_filter: off
  behavior:
    timeout: 10m
    cost_limit: "$5.00"