NudgeLang Documentation
Components
Manifest

Manifest

Manifest

The manifest is the entry point of every NudgeLang program. It defines metadata about your agent and its deployment configuration.

Basic Structure 

manifest:
  version: "1.0"
  title: "My Agent"
  description: "Description of what the agent does"
  author: "Your Name"
  created_at: "2025-05-07"

Deployment Configuration

The deployment section defines how your agent will be deployed and executed:

manifest:
  # ... other manifest fields ...
  
  deployment:
    type: "web_service"  # Options: web_service, cron, cli, event_driven
    config:
      # Web service configuration
      endpoint: "/api/agent"
      port: 8080
      rate_limit: 100  # requests per minute
      authentication:
        type: "jwt"
        secret_env: "JWT_SECRET"
      
      # For cron configuration
      # schedule: "*/30 * * * *"  # Run every 30 minutes
      # timezone: "UTC"
      
      # For CLI configuration
      # command: "my-agent"
      # arguments:
      #   - name: "input_file"
      #     type: "string"
      #     required: true
      
      # For event-driven configuration
      # event_source: "message_queue"
      # queue_name: "agent_requests"
      # trigger_events: ["new_request", "escalation"]

Deployment Types

  1. Web Service

    • Exposes your agent as a REST API
    • Supports rate limiting and authentication
    • Configurable endpoints and ports

  2. Cron

    • Runs your agent on a schedule
    • Supports standard cron syntax
    • Configurable timezone

  3. CLI

    • Runs your agent as a command-line tool
    • Supports command-line arguments
    • Useful for batch processing

  4. Event-Driven

    • Runs your agent in response to events
    • Supports various event sources
    • Configurable trigger events

Environment Configuration

Define environment-specific settings:

manifest:
  # ... other manifest fields ...
  
  environment:
    dev:
      log_level: "debug"
      model_overrides:
        main_model: "claude-3-5-sonnet"  # Use cheaper model in dev
    production:
      log_level: "info"
      timeout: 60  # Global timeout in seconds
      retry:
        max_attempts: 3
        backoff: "exponential"

MCP Server Configuration

Configure Model Context Protocol (MCP) servers that your agent will interact with:

manifest:
  # ... other manifest fields ...
  
  mcp_servers:
    - id: knowledge_base
      endpoint: "https://api.example.com/kb"
      description: "Product knowledge base"
      capabilities:
        resources: true
        prompts: true
        tools: true
      auth:
        type: "bearer"
        token_env: "KB_API_TOKEN"
    
    - id: customer_data
      endpoint: "https://api.example.com/customers"
      description: "Customer database"
      capabilities:
        resources: true
        tools: true
      auth:
        type: "basic"
        username_env: "DB_USERNAME"
        password_env: "DB_PASSWORD"

The MCP server configuration defines external services that provide:

  • Resources: Application-controlled data for context
  • Prompts: User-controlled templates for LLM interactions
  • Tools: Model-controlled functions for external actions

Human Oversight

Configure human-in-the-loop settings:

manifest:
  # ... other manifest fields ...
  
  human_oversight:
    required_for:
      - "refund_above_100"
      - "account_deletion"
    escalation_path: "support_team"
    approval_timeout: 300  # seconds

Complete Example

Here’s a complete manifest example:

manifest:
  version: "1.0"
  title: "Customer Support Assistant"
  description: "An agent that handles customer inquiries using Claude and product knowledge"
  author: "Your Name"
  created_at: "2025-05-07"
  
  deployment:
    type: "web_service"
    config:
      endpoint: "/api/support-agent"
      port: 8080
      rate_limit: 100
      authentication:
        type: "jwt"
        secret_env: "JWT_SECRET"
  
  environment:
    dev:
      log_level: "debug"
      model_overrides:
        main_model: "claude-3-5-sonnet"
    production:
      log_level: "info"
      timeout: 60
      retry:
        max_attempts: 3
        backoff: "exponential"
  
  human_oversight:
    required_for:
      - "refund_above_100"
      - "account_deletion"
    escalation_path: "support_team"
    approval_timeout: 300

Best Practices

  1. Version Control: Always specify a version number
  2. Descriptive Metadata: Provide clear title and description
  3. Environment Separation: Use environment-specific configurations
  4. Security: Configure authentication and rate limiting
  5. Human Oversight: Define clear escalation paths
  6. Documentation: Add comments to explain configuration choices

Next Steps

Last updated on
Models