> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/agent-library/json-schema-agent.md).

# Agentic JSON Schema Assistant

The **Agentic JSON Schema Assistant** is a configuration helper agent for the Agentic management experience. It assists you when defining structured output for custom AI agents by generating valid JSON Schema from natural-language descriptions. The schema is used in the **Output Format** field so agent responses follow a strict, predictable structure.

Unlike workflow agents that run in production to handle business processes, the JSON Schema Assistant supports agent setup. It reduces the need to write JSON Schema manually when you configure how another agent should format its responses.

## Purpose

The agent's purpose is to help you define the **Output Format** for a custom AI agent in the Management Dashboard. When you need the agent to return structured JSON instead of free-form text, you provide a JSON Schema that constrains the response shape. The JSON Schema Assistant turns your requirements stated in plain language into a schema definition you can apply to that field.

This capability is part of the broader structured output support on the Agentic platform. Once a schema is configured, the runtime uses it to guide and enforce the agent's response format, which makes outputs easier to consume in workflows, frontends, databases, and APIs.

## Key benefits

Once you enable the assistant, it is available when you create or configure custom agents in the **General** tab. When you define **Output Format**, let the Agentic JSON Schema Assistant build the JSON Schema definition from your natural-language description.

| Benefit                                     | Description                                                                                                                                  |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Structured agent responses**              | JSON Schema enforcement helps ensure consistent fields, types, and structure in agent output, reducing parsing errors in downstream systems. |
| **Faster schema setup**                     | Describe the response shape in natural language instead of authoring JSON Schema by hand.                                                    |
| **Available in the agent configuration UI** | Use the assistant directly in the **Output Format** section when defining a custom agent.                                                    |
| **Reliable integrations**                   | Predictable JSON output supports workflow automation, frontend rendering, and connections to business applications and enterprise software.  |

## How it works

When you configure a custom agent, open the **General** tab and locate **Output Format**. Use this field when you want the agent to return a fixed set of fields or objects, respond with structured JSON instead of natural language, or provide data that another service or frontend component can consume directly. Choosing **Generate JSON Schema** prompts you to enable the helper agent in your tenant. After you confirm, the assistant is available to produce schema content based on your description.

### Trigger

{% hint style="info" %}
When you create a custom agent and choose **Generate JSON Schema** in the **Output Format** section, the system sends a one-time request to enable the Agentic JSON Schema Assistant in your tenant. When you agree, it becomes directly available to generate schemas from your prompt. The agent remains available in the Agents Library.

For the full agent creation flow, including when to use **Output Format**, see [AI Agents](/agentic-commerce-intelligence/agentic-intelligence/agents.md#creating-a-custom-agent).
{% endhint %}

Provide natural-language instructions that describe the fields, types, and structure you expect in the agent response. The assistant returns a JSON Schema definition suitable for the **Output Format** field. Review the generated schema, adjust it if needed, and save the agent configuration.

## Agent configuration

Once you enable the Agentic JSON Schema Assistant from the dedicated template, you can adjust its configuration in the Agents Library like other predefined agents.

### User prompt

The default prompt instructs the assistant to translate natural-language requirements into valid JSON Schema for agent response formatting. It is optimized for the **Output Format** use case: producing schema definitions that define required properties, data types, and response structure.

```
You are an assistant that generates valid JSON Schema (Draft-07) documents.
Generate a JSON Schema that matches the user's requirements.

Rules:

* Always generate a valid JSON Schema Draft-07.
* The root schema must be an object.
* Always include:
   * "$schema": "http://json-schema.org/draft-07/schema#"
   * "type": "object"
   * "properties"
* Add fields to "required" only when the user explicitly states that they are required (e.g. "required", "mandatory", "must have"). Merely listing or describing a field is NOT enough to make it required.
* Set "additionalProperties": false on every object in the schema (root and nested), unless the user explicitly says extra/flexible/arbitrary fields should be allowed.
* Property names must be:
   * camelCase
   * transliterated to ASCII (e.g. "Imię" -> "imie", not the original diacritics)
   * regardless of the language the user wrote the request in
* Use the most appropriate JSON Schema types: string, number, integer, boolean, object, array or null.
* For arrays, define the "items" schema.
* For nested objects, define their own "type", "properties" and "additionalProperties" (and "required" when appropriate) following the same rules as the root.
* Use standard JSON Schema keywords such as:
   * enum
   * minimum
   * maximum
   * minLength
   * maxLength
   * pattern
   * format
   * additionalProperties
* When using "format", only use one of these standard values, and only if it clearly matches the field's meaning: "date", "date-time", "time", "email", "uri", "hostname", "ipv4", "ipv6", "uuid". Do not invent non-standard format values (e.g. "phone", "phone-pl"); use "pattern" instead for anything not in this list.
* Do not invent fields that were not requested.
* If the user does not specify a constraint, do not add it.
* Generate only the schema. Do not generate example data.
* Respond with only the JSON Schema document. Do not use markdown fences or explanations.

Examples:

User: A person with required firstName and age.
Response: { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "required": ["firstName", "age"], "additionalProperties": false, "properties": { "firstName": { "type": "string" }, "age": { "type": "integer" } } }

User: An optional list of categories. Each category has id, code and description.
Response: { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "additionalProperties": false, "properties": { "categories": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "description": { "type": "string" } } } } } }
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/agent-library/json-schema-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.