API
Tool Definitions

Tool Definitions

NudgeLang provides a flexible system for defining and using tools in autonomous agents. This document covers the various tool types, their configuration, and best practices.

Basic Structure 

tools:
  - name: string          # Required: Unique tool identifier
    type: string          # Required: Tool type
    description: string   # Required: Tool description
    parameters:           # Required: Parameter definitions
      - name: string      # Required: Parameter name
        type: string      # Required: Parameter type
        required: boolean # Required: Is parameter required
        description: string # Required: Parameter description
    implementation: string # Optional: Implementation path
    config: object        # Optional: Tool configuration

Built-in Tool Types

HTTP Tool

Makes HTTP requests to external services.

tools:
  - name: api_client
    type: http
    description: "HTTP client for API calls"
    parameters:
      - name: url
        type: string
        required: true
        description: "API endpoint URL"
      - name: method
        type: string
        required: true
        description: "HTTP method"
      - name: headers
        type: object
        required: false
        description: "Request headers"
      - name: body
        type: object
        required: false
        description: "Request body"
    config:
      timeout: 5000
      retry_attempts: 3

Database Tool

Interacts with databases.

tools:
  - name: db_client
    type: database
    description: "Database client"
    parameters:
      - name: query
        type: string
        required: true
        description: "SQL query"
      - name: params
        type: object
        required: false
        description: "Query parameters"
    config:
      type: postgresql
      host: localhost
      port: 5432
      database: mydb
      user: user
      password: password

File Tool

Handles file operations.

tools:
  - name: file_handler
    type: file
    description: "File operations handler"
    parameters:
      - name: operation
        type: string
        required: true
        description: "File operation"
      - name: path
        type: string
        required: true
        description: "File path"
      - name: content
        type: string
        required: false
        description: "File content"
    config:
      base_path: /data
      allowed_operations:
        - read
        - write
        - delete

Email Tool

Sends emails.

tools:
  - name: email_sender
    type: email
    description: "Email sender"
    parameters:
      - name: to
        type: string
        required: true
        description: "Recipient email"
      - name: subject
        type: string
        required: true
        description: "Email subject"
      - name: body
        type: string
        required: true
        description: "Email body"
    config:
      smtp_host: smtp.example.com
      smtp_port: 587
      username: user
      password: password

Custom Tools

Basic Custom Tool 

tools:
  - name: custom_tool
    type: custom
    description: "Custom tool implementation"
    parameters:
      - name: input
        type: object
        required: true
        description: "Input parameters"
    implementation: "path/to/implementation"

Advanced Custom Tool 

tools:
  - name: advanced_tool
    type: custom
    description: "Advanced custom tool"
    parameters:
      - name: input
        type: object
        required: true
        description: "Input parameters"
      - name: options
        type: object
        required: false
        description: "Tool options"
    implementation: "path/to/implementation"
    config:
      timeout: 5000
      retry_attempts: 3
      cache_enabled: true
      cache_ttl: 3600

Tool Configuration

Common Properties 

tools:
  - name: tool_name
    type: tool_type
    description: "Tool description"
    parameters:
      - name: param_name
        type: param_type
        required: true
        description: "Parameter description"
    config:
      timeout: 5000
      retry_attempts: 3
      cache_enabled: true
      cache_ttl: 3600

Security Configuration 

tools:
  - name: secure_tool
    type: tool_type
    description: "Secure tool"
    parameters:
      - name: input
        type: object
        required: true
        description: "Input parameters"
    config:
      auth:
        type: oauth2
        client_id: client_id
        client_secret: client_secret
      ssl:
        enabled: true
        verify: true

Tool Usage

Basic Usage 

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

Advanced Usage 

states:
  - id: use_tool
    type: tool
    tool: tool_name
    parameters:
      param1: "${input.value}"
      param2: "${context.value}"
    retry:
      attempts: 3
      delay: 1000
    timeout: 5000
    next: next_state

Best Practices

  1. Tool Definition

    • Use clear names
    • Provide descriptions
    • Define parameters
    • Document usage

  2. Parameter Design

    • Keep it simple
    • Use appropriate types
    • Mark required fields
    • Add descriptions

  3. Configuration

    • Set timeouts
    • Configure retries
    • Enable caching
    • Handle errors

  4. Security

    • Use authentication
    • Enable SSL
    • Validate inputs
    • Handle secrets

Common Patterns

  1. Error Handling
tools:
  - name: error_handling_tool
    type: tool_type
    description: "Tool with error handling"
    parameters:
      - name: input
        type: object
        required: true
        description: "Input parameters"
    config:
      error_handling:
        retry_on_error: true
        max_retries: 3
        error_callback: "path/to/callback"
  1. Caching
tools:
  - name: cached_tool
    type: tool_type
    description: "Tool with caching"
    parameters:
      - name: input
        type: object
        required: true
        description: "Input parameters"
    config:
      cache:
        enabled: true
        ttl: 3600
        strategy: lru
  1. Rate Limiting
tools:
  - name: rate_limited_tool
    type: tool_type
    description: "Tool with rate limiting"
    parameters:
      - name: input
        type: object
        required: true
        description: "Input parameters"
    config:
      rate_limit:
        enabled: true
        requests_per_second: 10
        burst: 20

Next Steps

Last updated on
State TypesMCP Integration