JsonAgent

⚠️ DEPRECATION WARNING

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

The JsonAgent component lets you create a JSON‑based agent that can read a JSON or YAML file, understand its structure, and then use that knowledge to interact with a language model (LLM). It’s useful when you want the agent to follow a specific data schema or to validate its responses against a predefined format.

How it Works

File Loading – The component reads the file you specify in the File Path input.
- If the file ends in .yaml or .yml, it is parsed as YAML.
- Otherwise, it is treated as a JSON file.
Specification Creation – From the parsed data, a JsonSpec object is built. This object describes the expected JSON structure that the agent should produce or consume.
Toolkit Setup – A JsonToolkit is created from the spec. This toolkit gives the agent tools to read, write, and validate JSON according to the spec.
Agent Construction – Using the selected Model (LLM) and the toolkit, a JSON agent is created with create_json_agent.
The agent is configured with callbacks that log its activity back to the Nappai dashboard.
Execution – When the workflow runs, the agent can be invoked to generate or validate JSON data, and its responses are returned as the Response output.

The component works entirely locally (apart from the LLM call), so it doesn’t require any external APIs beyond the LLM provider you choose.

Inputs

Input	Description
Model	The language model (LLM) that the agent will use to generate or interpret text.
File Path	Path to the JSON or YAML file that defines the data schema the agent should follow.
Handle Parse Errors	Determines how the agent should react if it encounters errors while parsing JSON responses (e.g., retry, fail, or ignore).
Input	The raw data or prompt that you want the agent to process.
Max Iterations	The maximum number of turns the agent is allowed to take before stopping.
Verbose	If set to true, the agent will produce detailed logs that can be viewed in the dashboard.

Note: This component does not expose any operations, so all inputs are always visible.

Outputs

Output	Type	Description
Agent	`AgentExecutor`	The fully configured agent that can be invoked elsewhere in your workflow.
Response	`Message`	The textual or JSON response produced by the agent after execution.

Usage Example

Add the component to your workflow canvas.
Connect an LLM (e.g., GPT‑4) to the Model input.
Specify the file path of a JSON schema you want the agent to follow.
Optionally set Handle Parse Errors, Max Iterations, and Verbose to your preference.
Connect the Agent output to another component that will trigger the agent (e.g., a “Run Agent” button).
Read the Response output to see the agent’s generated JSON or text.

This setup allows you to create a reusable JSON agent that can be called from multiple parts of your automation workflow.

LLM – Provides the language model that the agent uses.
FileInput – Helps select and validate file paths for JSON/YAML files.
JsonToolkit – Offers tools for JSON manipulation and validation.
AgentExecutor – The runtime object that actually runs the agent logic.

Tips and Best Practices

Use a clear, well‑structured JSON/YAML file so the agent can reliably validate its output.
Keep the file path accessible from the machine running Nappai; relative paths work best.
Set Verbose to true only when debugging to avoid cluttering logs.
Limit Max Iterations to prevent runaway loops in complex tasks.
Handle parse errors gracefully by choosing a strategy that fits your workflow (e.g., retry or fail).

Security Considerations

File Path Safety – Ensure the file path does not expose sensitive data or allow directory traversal.
LLM Data Privacy – Any data sent to the LLM is subject to the provider’s privacy policy; avoid sending confidential information unless you’re sure it’s safe.
Logging – When Verbose is enabled, logs may contain raw prompts and responses; store them securely if they contain sensitive content.