NudgeLang Documentation
Components
States

States

States

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

Basic Structure 

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

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 the following input:
    {input}
    
    Provide a response in JSON format.    
  input:
    input: "${input.message}"
  next: next_state

3. Tool State

Executes a tool:

- id: execute
  type: tool
  tool: my_tool
  parameters:
    param1: "${input.value1}"
    param2: "${input.value2}"
  next: next_state

4. Output State

Returns a value:

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

5. Parallel State

Executes multiple branches in parallel:

- id: parallel_processing
  type: parallel
  branches:
    - id: process_a
      type: llm
      model: model_a
      prompt: "Process A: {input}"
    - id: process_b
      type: llm
      model: model_b
      prompt: "Process B: {input}"
  next: combine_results

6. Agent State

Autonomous agent that can use tools:

- id: autonomous_agent
  type: agent
  model: main_model
  prompt: |
    You are an autonomous agent. Complete this task:
    {task}    
  tools: [tool1, tool2, tool3]
  next: end

7. MCP State

Interacts with MCP servers to access resources, prompts, or tools:

- id: mcp_state
  type: mcp
  server: knowledge_base
  action: get_resource
  input:
    resource_id: "${input.resource_id}"
  next: process_resource

- id: mcp_tool_state
  type: mcp_tool
  server: product_knowledge
  tool: search_products
  parameters:
    query: "${input.query}"
  next: process_results

MCP states can:

  1. Access resources from MCP servers
  2. Use prompts provided by MCP servers
  3. Execute tools defined on MCP servers
  4. Handle MCP server responses and errors

State Transitions

1. Simple Transition 

- id: state_a
  type: llm
  model: main_model
  prompt: "Process: {input}"
  next: state_b

2. Conditional Transition 

- id: classify
  type: llm
  model: classifier
  prompt: "Classify: {input}"
  transitions:
    - when: "${output === 'category_a'}"
      next: handle_category_a
    - when: "${output === 'category_b'}"
      next: handle_category_b
    - next: handle_unknown

3. Parallel Transition 

- id: parallel
  type: parallel
  branches:
    - id: branch_a
      type: llm
      model: model_a
    - id: branch_b
      type: llm
      model: model_b
  transitions:
    - when: "${branches.branch_a.output === 'success' && branches.branch_b.output === 'success'}"
      next: success
    - next: failure

Context Management

1. Accessing Context 

- id: process
  type: llm
  model: main_model
  prompt: |
    Process this input with context:
    Input: {input}
    User: {context.user.name}
    History: {context.history}    
  input:
    input: "${input.message}"
    context: "${context}"

2. Updating Context 

- id: update_context
  type: function
  implementation: |
    function(input, context) {
      return {
        ...context,
        last_processed: input.message,
        timestamp: new Date().toISOString()
      };
    }    
  next: next_state

Error Handling

1. Retry Logic 

- id: process
  type: llm
  model: main_model
  prompt: "Process: {input}"
  error_handling:
    retry:
      max_attempts: 3
      backoff: "exponential"
    fallback:
      state: error_state

2. Fallback States 

- id: process
  type: llm
  model: main_model
  prompt: "Process: {input}"
  fallback:
    state: error_state
    input:
      error: "${error.message}"
      original_input: "${input}"

Complete Example

Here’s a complete state configuration:

states:
  - id: start
    type: initial
    next: classify_input
  
  - id: classify_input
    type: llm
    model: classifier
    prompt: |
      Classify this input into one of these categories:
      - general_inquiry
      - technical_support
      - billing
      
      Input: {input}      
    input:
      input: "${input.message}"
    transitions:
      - when: "${output === 'general_inquiry'}"
        next: handle_general
      - when: "${output === 'technical_support'}"
        next: handle_technical
      - when: "${output === 'billing'}"
        next: handle_billing
      - next: handle_unknown
  
  - id: handle_technical
    type: agent
    model: main_model
    prompt: |
      You are a technical support agent. Help with this issue:
      {input}      
    tools: [search_kb, check_status, create_ticket]
    context:
      mcp_servers: [knowledge_base]
      resources:
        - uri: "file:///kb/technical.md"
    next: end
  
  - id: handle_billing
    type: llm
    model: main_model
    prompt: |
      You are a billing support agent. Handle this billing inquiry:
      {input}      
    tools: [check_balance, process_payment]
    error_handling:
      retry:
        max_attempts: 3
        backoff: "exponential"
      fallback:
        state: escalate_billing
    next: end
  
  - id: end
    type: output
    value: "${previous.output}"

Best Practices

  1. Clear State Names: Use descriptive names for states
  2. Error Handling: Implement proper error handling and fallbacks
  3. Context Management: Keep context updates explicit
  4. State Transitions: Make transitions clear and predictable
  5. Documentation: Document state behavior and requirements
  6. Testing: Test state transitions thoroughly

Next Steps

Last updated on
Tools