Skip to main content
The JSON Mode tool lets an agent return a structured JSON payload to the application that is driving the conversation, instead of a text reply. When the agent calls the tool, AGO hands your defined JSON to the caller and ends the turn — your own backend processes the payload. AGO does not run any logic on it and does not continue the conversation on a result. Use it when the outcome of a request belongs in your system rather than in the chat: create a record, trigger a workflow, return a machine-readable result to a caller that then acts on it.

​
Overview

Tool type: json_mode You define the shape of the JSON with the tool’s parameters (its input schema). The agent fills those fields based on the conversation, and that filled-in object is exactly what your application receives. Because the tool is configured on the agent, only agents you attach it to can produce this payload. It cannot be declared or triggered from a browser through the SDK’s client functions — the behavior is tied to the agent, not to the caller’s request.

​
How it works

  1. You create a JSON Mode tool, define its fields, and attach it to an agent.
  2. During a conversation, the agent decides the tool is relevant and calls it, filling the fields.
  3. AGO ends the turn and exposes the payload to the caller.
  4. Your application reads the payload and does the processing.
The agent gets no result back and does not keep talking about it — the turn stops once the payload is handed over.

​
Configuration

  1. Navigate to AI Studio → Tools
  2. Click Create Tool
  3. Select json_mode as the tool type
  4. Set a clear name and description (the agent reads the description to decide when to call it)
  5. Define the parameters — each field the agent should fill, with a type and a description
  6. Attach the tool to one or more agents

​
Parameters

Parameters follow the same input-schema format as other tools. Each field has a type (str, int, float, bool, or a list), a description, and can be marked required. The object the agent fills is what your backend receives.

​
Reading the payload

The payload is delivered on the message’s tool call data, so you can read it two ways:
  • Streaming: while reading the response stream, catch the tool call entry of type json_mode — it carries the data object (and the same values under arguments).
  • Request/poll: fetch the conversation and read the message’s tool_call_data; the json_mode entry holds the payload under data.

​
When to use something else

  • If the agent needs the result of an action to continue its answer, use a client function in pause mode instead — that round-trips a result back into the conversation.
  • If AGO should perform the call itself (and the agent should use the response), use the HTTP Request Tool.

HTTP Request Tool

Let the agent call an external API and use the response

SDK API Reference

Send messages and read conversations over the API