Skip to content
Nappai Documentation

JsonAgent

⚠️ DEPRECATION WARNING

This component is deprecated and will be removed in a future version of Nappai. Please migrate to the recommended alternative components.

JsonAgent

The JsonAgent component allows you to connect an intelligent assistant to your data files. It acts as a bridge between natural language questions and structured data stored in JSON or YAML files. By using this component, you can ask questions about your data in plain text, and the agent will automatically explore the file structure to find relevant information and provide clear answers.

How it Works

This component works by loading your data file into memory and creating a set of “tools” that help the AI understand the structure of your data. When you interact with the agent, it uses these tools to navigate through the file, check for specific keys or values, and retrieve the information you need. The agent handles the complex logic of reading and parsing the file, allowing you to focus on getting the answers you need.

Inputs

Input Fields

The following fields are available to configure this component:

  • Model: The AI language model that powers the agent’s reasoning and response generation.
  • File Path: The path to the local JSON or YAML file containing the structured data you want to explore.
  • Handle Parse Errors: Controls how the component handles errors when reading the file structure.
  • Input: The input stream or data feed for the agent’s execution.
  • Max Iterations: The maximum number of steps the agent can take to process a request before stopping.
  • Verbose: Enables detailed logging of the agent’s actions and decisions for debugging purposes.

Outputs

This component produces the following outputs:

  • Agent: The fully configured agent executor ready to process interactions.
  • Response: The final message or answer generated by the agent based on your input.

Output Data Example (JSON)json

{ “content”: “Based on the file, the user data contains 3 active records with the specified criteria.”, “tool_calls”: [], “status”: “success”, “type”: “Message” }

Usage Example

Imagine you have a products.json file containing details about inventory items. You can use the JsonAgent to ask questions like, “What products are currently out of stock?” or “Show me the price of item ID 105.” By providing the File Path to products.json and connecting a Model, the agent will read the file, understand its structure, and return the specific information you requested in the Response output.

Important Notes

🔒 Use Trusted Spec Files Only 🟡 Loading YAML or JSON from untrusted sources can expose your system to malicious code execution. Only load spec files you trust.

⚠️ Supported File Formats Only 🟢 This component only processes files with .json, .yaml, or .yml extensions. Files with other extensions will be ignored and cause an error.

⚠️ File Path Must Be Valid 🟢 The component expects a valid local file path. If the file is missing or unreadable, the agent will fail to build.

📋 LanguageModel Input Required 🟢 An LLM compatible with the LanguageModel interface must be supplied. Without it, the agent cannot function.

📋 Python Dependencies 🟢 The component relies on langchain, langchain_community, and PyYAML. Ensure these packages are installed in your environment.

💡 Use YAML for Readability 🟢 When creating your spec, YAML offers clearer formatting and easier editing. JSON is also supported for compactness.

💡 Validate Spec Before Running 🟢 Test your JSON/YAML spec file with a simple loader to confirm it’s well‑formed. This prevents runtime errors in the agent.

⚙️ Only Local File Paths Accepted 🟡 The component does not support remote URLs or network paths. Provide an absolute or relative path to a local file.

⚙️ Keep Spec File Size Reasonable 🟢 Large spec files can slow down agent initialization. Aim to keep the file under a few megabytes for optimal performance.

ℹ️ Automatic Logging via Callbacks 🟢 The agent automatically logs its actions and outputs through callbacks. You can monitor these logs to trace the agent’s decisions.

Tips and Best Practices

  • Use descriptive file names and clear structures in your JSON/YAML files to help the agent provide more accurate answers.
  • If you are working with large datasets, consider splitting your data into smaller files to improve performance.
  • Always verify the integrity of your data files before connecting them to the agent to avoid unexpected errors.
  • Monitor the logs generated by the agent to understand how it interprets your requests and resolves data queries.

Security Considerations

To ensure the security of your automation system, always verify the source and integrity of the JSON or YAML files you provide to this component. Never load files from untrusted or external sources, as parsing malformed or malicious data can pose security risks. Use local file paths and validate your data files regularly to maintain a safe working environment.