> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON

> Read and manipulate JSON files

## Overview

JSON tool allows you to read, write, and query JSON files.

The user provides JSON data; the agent parses, queries, or writes it and returns the result.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "JSONTool Flow"
        User[👤 User] --> Agent[🤖 Agent]
        Agent --> Tool[🔧 JSONTool]
        Tool --> Result[✅ Result]
        Result --> Agent
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class User,Agent agent
    class Tool tool
    class Result output
```

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai[tools]"
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai_tools import JSONTool

    # Initialize
    json_tool = JSONTool()

    # Read JSON
    data = json_tool.read("config.json")
    print(data)
    ```
  </Step>

  <Step title="With Configuration">
    Use the same tool with an agent — see **Usage with Agent** below, or pass env vars and options from the sections above.
  </Step>
</Steps>

## Usage with Agent

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai_tools import JSONTool

agent = Agent(
    name="DataProcessor",
    instructions="You help process JSON data.",
    tools=[JSONTool()]
)

response = agent.chat("Read config.json and show the database settings")
print(response)
```

## Available Methods

### read(path)

Read a JSON file.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import JSONTool

json_tool = JSONTool()
data = json_tool.read("data.json")
```

### write(path, data)

Write data to a JSON file.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
json_tool.write("output.json", {"key": "value"})
```

### query(path, jq\_query)

Query JSON with JQ-like syntax.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
result = json_tool.query("data.json", ".users[0].name")
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Tool as Tool
    participant Svc as JSON data

    User->>Agent: Request
    Agent->>Tool: Call tool
    Tool->>Svc: Query
    Svc-->>Tool: Data
    Tool-->>Agent: Result
    Agent-->>User: Response
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Validate before parsing">
    Handle malformed JSON gracefully so the agent returns a clear error instead of crashing.
  </Accordion>

  <Accordion title="Query by path">
    Extract only the fields you need rather than loading the whole document into context.
  </Accordion>

  <Accordion title="Preserve types">
    Keep numbers and booleans typed — don't stringify everything when writing JSON back out.
  </Accordion>
</AccordionGroup>

***

## Related Tools

<CardGroup cols={2}>
  <Card title="CSV" icon="book" href="/docs/tools/external/csv">
    CSV files
  </Card>

  <Card title="File" icon="book" href="/docs/tools/external/file">
    General files
  </Card>
</CardGroup>