API
State Types

State Types

NudgeLang provides several built-in state types for building autonomous agents. Each state type serves a specific purpose and has its own configuration options.

Core State Types

Initial State

The starting point of an agent’s execution.

states:
  - id: start
    type: initial
    next: next_state

LLM State

Interacts with language models to process and generate text.

states:
  - id: process
    type: llm
    model: model_name
    prompt: |
      Your prompt template here
      {variable}      
    input:
      variable: "${context.value}"
    next: next_state

Tool State

Executes external tools and services.

states:
  - id: execute
    type: tool
    tool: tool_name
    parameters:
      param1: "${input.value}"
      param2: "${context.value}"
    next: next_state

Output State

Returns the final result of the agent’s execution.

states:
  - id: end
    type: output
    value: "${context.result}"

Advanced State Types

Parallel State

Executes multiple states concurrently.

states:
  - id: parallel_process
    type: parallel
    branches:
      - id: branch1
        states:
          - id: process1
            type: llm
            model: model1
            prompt: "Process 1"
            next: end
      - id: branch2
        states:
          - id: process2
            type: llm
            model: model2
            prompt: "Process 2"
            next: end
    next: combine_results

Choice State

Makes decisions based on conditions.

states:
  - id: choose
    type: choice
    choices:
      - when: "${input.value > 0}"
        next: positive
      - when: "${input.value < 0}"
        next: negative
      - next: zero

Wait State

Pauses execution for a specified duration.

states:
  - id: wait
    type: wait
    duration: 5000  # milliseconds
    next: next_state

Map State

Processes arrays of data.

states:
  - id: process_items
    type: map
    items: "${input.items}"
    iterator:
      - id: process_item
        type: llm
        model: model_name
        prompt: "Process {item}"
        next: end
    next: combine_results

State Configuration

Common Properties 

states:
  - id: state_id          # Required: Unique identifier
    type: state_type      # Required: State type
    next: next_state      # Required: Next state ID
    timeout: 5000         # Optional: Timeout in milliseconds
    retry:                # Optional: Retry configuration
      attempts: 3
      delay: 1000
    error: error_state    # Optional: Error state

Input/Output Mapping 

states:
  - id: process
    type: llm
    input:
      user_input: "${input.message}"
      context_data: "${context.data}"
      previous_result: "${previous.output}"
    output:
      result: "${output.data}"
      status: "${output.status}"

Transitions 

states:
  - id: process
    type: llm
    transitions:
      - when: "${output.status === 'success'}"
        next: success_state
      - when: "${output.status === 'error'}"
        next: error_state
      - next: default_state

State Types Reference

Initial State

  • Purpose: Starting point
  • Required Properties:
    • id: Unique identifier
    • type: “initial”
    • next: Next state ID

LLM State

  • Purpose: Language model interaction
  • Required Properties:
    • id: Unique identifier
    • type: “llm”
    • model: Model name
    • prompt: Prompt template
    • next: Next state ID
  • Optional Properties:
    • input: Input mapping
    • output: Output mapping
    • parameters: Model parameters

Tool State

  • Purpose: External tool execution
  • Required Properties:
    • id: Unique identifier
    • type: “tool”
    • tool: Tool name
    • parameters: Tool parameters
    • next: Next state ID
  • Optional Properties:
    • timeout: Execution timeout
    • retry: Retry configuration

Output State

  • Purpose: Result delivery
  • Required Properties:
    • id: Unique identifier
    • type: “output”
    • value: Output value

Parallel State

  • Purpose: Concurrent execution
  • Required Properties:
    • id: Unique identifier
    • type: “parallel”
    • branches: Branch definitions
    • next: Next state ID

Choice State

  • Purpose: Conditional branching
  • Required Properties:
    • id: Unique identifier
    • type: “choice”
    • choices: Choice definitions

Wait State

  • Purpose: Execution delay
  • Required Properties:
    • id: Unique identifier
    • type: “wait”
    • duration: Wait duration
    • next: Next state ID

Map State

  • Purpose: Array processing
  • Required Properties:
    • id: Unique identifier
    • type: “map”
    • items: Items to process
    • iterator: State definitions
    • next: Next state ID

Best Practices

  1. State Organization

    • Use clear naming
    • Keep states focused
    • Document purposes
    • Handle errors

  2. State Transitions

    • Define clear paths
    • Handle all cases
    • Use conditions
    • Avoid cycles

  3. State Configuration

    • Set timeouts
    • Configure retries
    • Map inputs/outputs
    • Handle errors

  4. State Types

    • Choose appropriate types
    • Use advanced types
    • Combine effectively
    • Monitor performance

Common Patterns

  1. Error Handling
states:
  - id: process
    type: llm
    error: handle_error
    next: next_state
  1. Retry Logic
states:
  - id: process
    type: tool
    retry:
      attempts: 3
      delay: 1000
    next: next_state
  1. Conditional Flow
states:
  - id: process
    type: llm
    transitions:
      - when: "${output.value > 0}"
        next: positive
      - when: "${output.value < 0}"
        next: negative
      - next: zero

Next Steps

Last updated on
Manifest SchemaTool Definitions