NudgeLang Documentation
Basic Concepts

Basic Concepts

This guide covers the fundamental concepts you need to understand when working with NudgeLang.

Core Components

1. Manifest

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

manifest:
  version: "1.0"
  title: "My Agent"
  description: "Description of what the agent does"
  author: "Your Name"
  created_at: "2025-05-07"
  
  deployment:
    type: "web_service"
    config:
      endpoint: "/api/agent"
      port: 8080

2. Models

Models define the LLMs your agent will use:

models:
  - id: main_model
    type: claude
    version: "claude-3-7-sonnet"
    config:
      temperature: 0.7
      max_tokens: 1000

3. States

States define the flow of your agent. Each state has a type and can transition to other states:

states:
  - id: start
    type: initial
    next: process_input
  
  - id: process_input
    type: llm
    model: main_model
    prompt: "Process this input: {input}"
    next: end

State Types

1. Initial State

The starting point of your agent:

- id: start
  type: initial
  next: next_state

2. LLM State

Uses an LLM to process input:

- id: process
  type: llm
  model: main_model
  prompt: "Process: {input}"
  next: next_state

3. Tool State

Executes a tool:

- id: execute
  type: tool
  tool: my_tool
  parameters:
    param1: "value1"
  next: next_state

4. Output State

Returns a value:

- id: end
  type: output
  value: "${previous.output}"

Tools

Tools allow your agent to perform actions:

tools:
  - id: search
    description: "Search for information"
    parameters:
      - name: query
        type: string
        required: true
    implementation:
      type: http
      method: GET
      url: "https://api.example.com/search"

MCP Integration

The Model Context Protocol (MCP) allows your agent to interact with external services:

mcp_servers:
  - id: knowledge_base
    endpoint: "https://api.example.com/kb"
    capabilities:
      resources: true
      prompts: true
      tools: true

Variables and Expressions

NudgeLang supports variable interpolation and expressions:

input:
  query: "${input.message}"
  timestamp: "${now()}"
  user_id: "${context.user.id}"

State Transitions

States can transition based on conditions:

transitions:
  - when: "${output === 'success'}"
    next: success_state
  - when: "${output === 'error'}"
    next: error_state
  - next: default_state

Context Management

The context object maintains state across transitions:

context:
  user:
    id: "${input.user_id}"
    preferences: "${loadUserPreferences(input.user_id)}"

Error Handling

Handle errors gracefully:

error_handling:
  retry:
    max_attempts: 3
    backoff: "exponential"
  fallback:
    state: error_state

Best Practices

  1. Keep it Simple: Start with basic states and add complexity as needed
  2. Use Meaningful Names: Choose clear, descriptive names for states and tools
  3. Document Everything: Add comments and descriptions to explain your agent’s behavior
  4. Handle Errors: Always include error handling and fallback states
  5. Test Thoroughly: Test your agent with various inputs and scenarios

Next Steps

Last updated on
Installation