Input/Output Tracking

This guide explains how to properly handle input and output data when using the traceAgentNode wrapper in your Handit.AI implementation. Accurate tracking ensures meaningful traces, metrics, and agent monitoring.

Node Wrapper Data Handling

When using the traceAgentNode wrapper, it's crucial to handle input and output data correctly:

Input Data

When wrapping a function with traceAgentNode, make sure you’re passing the actual input the function works with—not just metadata.

Best Practices

• Pass the full input data used in your logic (not summaries or labels)

• Sanitize PII or sensitive fields before passing input to the wrapper

• Maintain the expected data structure your function relies on

Output Data

To enable complete traceability, the function wrapped by traceAgentNode should return the full result of the operation.

Best Practices

• Return the unmodified result directly from the function

• Avoid trimming, masking, or simplifying outputs unless absolutely necessary

• Let Handit.AI trace the raw output to preserve context

Examples

Node.js

// Correct: Passing actual input data
const tracedProcessor = traceAgentNode({
  agentNodeId: "data-processor",
  callback: async (input) => {
    // Sanitize PII if needed
    const sanitizedInput = sanitizePII(input);
    
    // Process the data
    const result = await processData(sanitizedInput);
    
    // Return complete output
    return result;
  }
});

// Incorrect: Only passing metadata
const wrongProcessor = traceAgentNode({
  agentNodeId: "data-processor",
  callback: async (input) => {
    // Don't do this - only passing metadata
    return { status: "processed", timestamp: Date.now() };
  }
});

Python

# Correct: Passing actual input data
traced_processor = trace_agent_node(
    agent_node_id="data-processor",
    callback=async (input_data):
        # Sanitize PII if needed
        sanitized_input = sanitize_pii(input_data)
        
        # Process the data
        result = await process_data(sanitized_input)
        
        # Return complete output
        return result
)

# Incorrect: Only passing metadata
wrong_processor = trace_agent_node(
    agent_node_id="data-processor",
    callback=async (input_data):
        # Don't do this - only passing metadata
        return {"status": "processed", "timestamp": time.time()}
)

Data Sanitization Guidelines

When dealing with PII or sensitive data, sanitize inputs before passing them to Handit.AI.

🔧 How to sanitize:

• Identify fields like email, phone, name, etc.

• Mask or remove sensitive values

• Preserve the structure and semantics for downstream processing

Example: JavaScript sanitization

function sanitizePII(data) {
  if (typeof data !== 'object') return data;
  
  const sanitized = { ...data };
  
  // Mask email addresses
  if (sanitized.email) {
    sanitized.email = sanitized.email.replace(/(?<=.{3}).*(?=@)/, '***');
  }
  
  // Mask phone numbers
  if (sanitized.phone) {
    sanitized.phone = sanitized.phone.replace(/\d(?=\d{4})/g, '*');
  }
  
  return sanitized;
}

Best Practices Summary

1. Always pass complete input data through the wrapper

2. Return complete output from your functions

3. Sanitize sensitive data before processing

4. Maintain data structure integrity

5. Don't modify output before returning