Skip to main content
Feedback

Using Structured agent mode

When building an agent, you can choose how an AI agent responds in the Profile screen. There are two agent response modes:

  • Conversational mode (default) - The AI agent responds in natural language text. This mode is ideal for conversational agents where the user may have follow up questions after the initial prompt. The agent can use chat history and context to respond to the user and achieve its goal.

  • Structured mode - The AI agent receives JSON input from Boomi Integration and responds in a consistent, structured JSON format. This model is ideal for workflows that use Agent step where the agent’s response is consumed by downstream systems. The response is single turn, meaning the agent has a single input and output with no reference to previous responses.

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

In this video, discover how to use Structured agent mode.

Benefits

Structured mode reduces the need to process natural language responses from AI agents into a machine-readable format. It streamlines intelligent automation through the Agent step in Boomi Integration and makes it easy for downstream clients, like integrations and APIs, to consume AI agent responses.

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. Refer to JSON 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