Skip to main content

Configuring Output JSON Format

This feature is only available on Activity and Chat Completion agents.

The output JSON format allows us to specify which format we want for an agent response. For instance, if our prompt instructs the agent to give us a recipe, we can specify the output format to be:

{
    "ingredients": [
        "ingredient1",
        "ingredient2",
        ...
    ],
    "preparation-steps": [
        "step1",
        "step2",
        ...
    ]
}

This guide explains how to configure the output JSON format for activity or chat completion agents in Serenity* Star. This allows you to control the agent's response format to interact seamlessly with other systems.

Setting Up Output JSON Format​

Let's see how to set output JSON format to an existing agent using the Agent Designer.

  1. Visit Serenity* Star Dashboard and click on the "AI Agents" button in the sidebar.

    image

  2. From the list of agents, click the card of the agent you want to edit to open the Agent Designer. alt text

  3. Once in the Agent Designer, search for the "Output JSON format" section within the "General" tab and select the appropiate method of processing.

  • Json Format: With this option, you must provide a sample JSON with the required structure for the agent to map the relevant information.

  • Json Schema: This ensures that the model always generates responses that adhere to your supplied JSON Schema, preventing it from omitting required keys or producing invalid values

    image

  1. Add your expected output format. Here's an example using the JSON defined before:

    image

    Json Format example

    image

    Json Schema example

  2. Use the preview pane on the right to execute the agent and test the response format.

    image

Agent Response Management​

JSON responses may vary depending on the vendor or provider. While JSON format is supported across all models, JSON Schema may not always be available. When supported, we recommend using JSON Schema, as it ensures more predictable and structured results.

Error Handling​

When an agent fails to respond with the specified format, the response will be empty. This ensures that systems relying on structured data are not disrupted by malformed responses.

If we execute the agent through the API, the received message can be displayed in the "generatedJson" field.

{
  "code": "ERR_BAD_REQUEST",
  "response-steps": {
    "data": {
      "errors": {
        "generatedJson": "..."
      }
    }
  }
}