Waiting for engine...
Skip to main content

Structured agent responses

When building an agent in Profile, you can control how it handles inputs and generates outputs. Two response modes are available:

  • Conversational mode (default):

    • Behavior - Responds in natural language text
    • Best for - Conversational agents where the user may have follow up questions after the initial prompt
    • Key attributes:
      • Uses chat history and context to respond to the user and achieve its goal.
      • Useful for agents that work toward a goal over multiple exchanges with a user.

  • Structured mode:

    • Behavior - Receives JSON input from Boomi Integration and responds in a consistent, structured JSON format.
    • Best for - Automation workflows that use Agent step where the agent’s response is consumed by downstream systems.
    • Key attributes:
      • Single-turn response: A single input and output with no context to previous responses.

Refer to Agent step and Creating a Data Quality Report agent to understand how an AI agent in Agent step is applied to an integration.

Benefits​

  • Eliminates the overhead of parsing free-form text.
  • Enables reliable automation with predictable output.
  • Downstream systems can directly consume the JSON payload.

Use case: Customer Retention agent​

A manufacturing company collects customer satisfaction surveys after support interactions. They contain a few ratings and an optional open-ended feedback field. Until now, customer service managers only see the information when they pull weekly reports. By then, it’s too late to rescue a frustrated customer.

With Boomi Agentstudio, the company creates an AI agent that receives survey responses in a structured JSON format. The AI agent then evaluates the ratings and analyzes the free-text feedback for sentiment. If the overall score falls below a threshold, the agent identifies it as negative. The output schema is returned in a consistent, machine-readable format that is consumable by their enterprise systems and APIs.

Their process in Boomi Integration receives the agent’s response through Agent step and routes the alert into downstream workflows - creating a ticket for follow-up in the CRM and sending a Slack notification to the customer service manager. Instead of waiting for weekly reports, the business can proactively follow up within hours of a bad experience, turning a potential detractor into a retained customer.

Important considerations​

  • When structured mode is turned on, agents can only respond in a single turn, meaning a single output for each input. They cannot use previous responses and context to form outputs.

  • Deployed agents in structured mode do not appear in the conversational user interface in Agent Garden.

  • When testing agents in the Test Agent window, streaming notifications about the agent’s reasoning and actions, such as “Thinking” or “Retrieving data” are not available. However, the agent’s trace and all components within it are available.

  • JSON format must be in draft 04 schema.

Build an agent in Structured mode​

The following steps guide you through setting up structured mode for an AI agent.

  1. Navigate to Agentstudio > Agent Garden > Agents.

  2. In Profile > Agent Mode, select Structured.

  3. In Input Schema, do one of the following:

    • Upload a file with the JSON schema.
    • Enter a JSON schema for the input payload the AI agent will receive as a prompt. For instance, if sending a customer survey response from an API for the AI to process, the schema could look like this:
    JSON input schema example
    {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Customer Survey Response Input",
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "customerId": {
        "type": "string",
        "description": "Unique identifier for the customer"
        },
        "survey": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
            "serviceSatisfaction": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "description": "Service satisfaction rating (1-5)"
            },
            "easeOfResolution": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "description": "Ease of resolution rating (1-5)"
            },
            "likelihoodToRecommend": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "description": "Likelihood to recommend (1-5)"
            },
            "feedback": {
            "type": "string",
            "description": "Optional free-text feedback from the customer"
            }
        },
        "required": [
            "serviceSatisfaction",
            "easeOfResolution",
            "likelihoodToRecommend"
        ]
        }
    },
    "required": ["customerId", "survey"]
    }

  4. Select Validate to check that the schema is in the correct format.

  5. In Output Schema, repeat steps 3-4.

    JSON output schema example
    {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Customer Survey Response Output",
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "customerId": {
            "type": "string",
            "description": "Unique identifier for the customer"
        },
        "totalScore": {
        "type": "integer",
        "description": "Sum of survey ratings (range 3-15)"
        },
        "sentiment": {
        "type": "string",
        "enum": ["Positive", "Neutral", "Negative"],
        "description": "AI classification of feedback sentiment"
        },
        "status": {
        "type": "string",
        "enum": ["Good", "Neutral", "Bad"],
        "description": "Overall classification based on score and sentiment"
        },
        "alertTriggered": {
        "type": "boolean",
        "description": "True if score is below threshold or sentiment is negative"
        }
    },
    "required": [
    "customerId",
    "totalScore",
    "sentiment",
    "status",
    "alertTriggered"
    ]
    }

  6. Click Save and Continue. Continue building your agent, adding tasks, instructions, and guardrails according to the steps in Building an agent. You can test your agent in the Test Agent window by entering a JSON input as a prompt. Refer to Testing and troubleshooting an agent. For example you could enter:

JSON input test example
    {
    "customerId": "CUST1001",
    "survey": {
        "serviceSatisfaction": 2,
        "easeOfResolution": 3,
        "likelihoodToRecommend": 2,
        "feedback": "The support person was polite but my issue is still unresolved."
        }
    }
JSON output test example

    {
    "customerId": "CUST1001",
    "totalScore": 3,
    "sentiment": "Negative",
    "status": "Bad",
    "alertTriggered": true
    }

  1. Deploy your agent.

Next steps:

  • Refer to Agent step to learn how an agent in Structured mode can apply to an agentic workflow.
On this Page