Converse Modes

In the Datagrid web app, chat uses three modes—Ask, Extended, and Execute—which correspond to the Converse chat_mode field (llm_router, light_agent, full_agent). This page documents config.agent_model, which selects the model implementation and which tools are allowed. Default mode: New chats and omitted/default chat_mode run as Execute (full_agent) with the default agent_model: magpie-2.5, unless you explicitly set a different supported agent_model. Auto mode: chat_mode: auto is still accepted for compatibility, but currently runs as Execute (full_agent). It does not predict Ask, Extended, or Execute per message. Orchestrator turns: A turn on the orchestrator always runs as Execute and reports chat_mode: full_agent, whatever chat_mode you send. See Agent routing. Structured outputs: For any agent_model, you can request JSON that matches a schema by passing text.format (JSON Schema) on the Converse request. The same mechanism applies across modes; tool limits below still apply. Important: The Ask mode in the web app is the llm_router chat_mode, not magpie-1.1-flash. The magpie-1.1-flash model aligns with Extended in the app (search-backed, lighter agent). Use both chat_mode and agent_model when reproducing in-app behavior from the API.

Ask (in-app; `chat_mode: llm_router`)

Ask is a product / routing mode, not a value of config.agent_model. In the web app it is selected with chat_mode: llm_router. What it is good for: Fast, LLM-forward answers when the product has already chosen an agent for instructions and context. The server resolves routing (including agent context), then follows an LLM-focused path rather than full Execute-style multi-tool planning. How it differs from llm-only: llm-only is an explicit agent_model on the Converse API: you get the direct LLM tier with no tool execution and predictable behavior from that string alone. llm_router instead means “use the in-app Ask routing rules” (agent resolution, mode refinement, default models) on top of whatever agent_model and agent_id you pass. To mirror Ask from the API, set chat_mode to llm_router and the same agent identifiers you use in the app; do not assume agent_model: llm-only alone reproduces Ask, and do not confuse llm_router with Extended (light_agent / magpie-1.1-flash). Structured outputs for turns that use llm_router still use text.format like any other Converse call.

Execute (full agent models)

Full agent with multi-step planning, reasoning, and broad tool execution. Matches Execute in the Datagrid web app (chat_mode: full_agent). This is the default for new chats and omitted/default chat_mode; when agent_model is omitted, Execute uses magpie-2.5.

`agent_model`	Description
`magpie-2.0`	Legacy full-agent model with proactive planning and reasoning.
`magpie-2.5`	Default. Latest full-agent model — faster, more adaptable, and built to handle a broader range of real-world tasks.
`magpie-1.1`	Previous-generation full agent model.

All tools listed for agents are available for Execute-tier models. Structured outputs use text.format (see Structured outputs).

response = datagrid.converse(
    prompt="Analyze my sales data and create a summary report",
    config={
        "agent_model": "magpie-2.5",
        "tools": ["data_analysis", "semantic_search", "create_dataset"]
    }
)

const response = await datagrid.converse({
    prompt: "Analyze my sales data and create a summary report",
    config: {
        agent_model: "magpie-2.5",
        tools: ["data_analysis", "semantic_search", "create_dataset"],
    },
});

Extended (search-focused agent)

Lightweight turns optimized for RAG (retrieval-augmented generation). Matches Extended in the Datagrid web app (chat_mode: light_agent). Faster than Execute-tier models with lower latency.

`agent_model`	Description
`magpie-1.1-flash`	Fast model that only supports the `semantic_search` tool.

Only the semantic_search tool is supported for magpie-1.1-flash. Requests specifying other tools will be rejected. Structured outputs use text.format like other models (see Structured outputs).

response = datagrid.converse(
    prompt="What is our refund policy?",
    config={
        "agent_model": "magpie-1.1-flash",
        "tools": ["semantic_search"]
    }
)

const response = await datagrid.converse({
    prompt: "What is our refund policy?",
    config: {
        agent_model: "magpie-1.1-flash",
        tools: ["semantic_search"],
    },
});

Direct LLM (`llm-only`)

Direct LLM response with no planning or tool execution. Lowest latency, best for simple conversational or structured JSON answers that do not need retrieval or actions.

`agent_model`	Description
`llm-only`	Direct LLM conversation with no tool calls.

llm-only is the API’s explicit tool-free model key. It is not the same thing as selecting Ask in the web app: Ask is chat_mode: llm_router (see the Ask section at the top of this page). No tools are executed for llm-only. Requests specifying tools will be rejected. Structured outputs use text.format (see Structured outputs).

response = datagrid.converse(
    prompt="Summarize the key differences between GAAP and IFRS",
    config={
        "agent_model": "llm-only"
    }
)

const response = await datagrid.converse({
    prompt: "Summarize the key differences between GAAP and IFRS",
    config: {
        agent_model: "llm-only",
    },
});

Beta (`magpie-3.0`)

BETA: Magpie 3.0. Behavior and schema may change. config.agent_model: "magpie-3.0" selects Magpie 3.0 on the public Converse API. The request runs Magpie 3.0 whether or not Magpie 3.0 is enabled for that user in the Datagrid web app. It is not an Ask, Extended, or Execute model. Structured outputs use text.format (see Structured outputs).

response = datagrid.converse(
    prompt="Summarize open RFIs and the drawings they reference",
    config={
        "agent_model": "magpie-3.0"
    }
)

const response = await datagrid.converse({
    prompt: "Summarize open RFIs and the drawings they reference",
    config: {
        agent_model: "magpie-3.0",
    },
});

Agent routing (`agent_routing`)

chat_mode and agent_model decide how a turn runs. agent_routing decides which agent runs it. Send either agent_id or agent_routing, not both.

`agent_routing.mode`	Who answers	Agents per turn
`auto`	The API picks the best agent in the Teamspace before the turn starts.	One
`manual`	The API picks the best agent from the `targets` you list.	One
`orchestrator`	The Teamspace’s orchestrator answers and hands parts of the work to specialist agents during the turn.	The orchestrator, plus any specialists it delegates to

auto and manual always select a single agent. Only orchestrator delegates to several agents in one turn.

Orchestrator mode

response = datagrid.converse(
    prompt="Summarize open RFIs and the submittals they block",
    agent_routing={"mode": "orchestrator"},
    stream=True,
)

const response = await datagrid.converse({
    prompt: "Summarize open RFIs and the submittals they block",
    agent_routing: { mode: "orchestrator" },
    stream: true,
});

The orchestrator is the agent that answers. agent_id on the start and end events and on the response is the orchestrator’s. The specialists it used are listed in delegations (see Streaming).
Follow-ups stay on the orchestrator. A later turn that sends only conversation_id keeps running on the orchestrator. Send agent_routing or agent_id to move the conversation to another agent.
Personal conversations only. Continuing a channel or shared conversation in orchestrator mode returns 400 with validation_error.
Only reachable through this mode. The orchestrator isn’t listed by GET /v1/agents, and sending its id as agent_id or as a manual target returns 404 with resource_not_found, the same as an unknown agent.
targets isn’t accepted, and the mode can’t be combined with agent_id.
chat_mode is always full_agent. The orchestrator reaches specialists through tools, and Ask (llm_router) and Extended (light_agent) run without them. A turn requested as either runs as Execute and reports chat_mode: full_agent on the end event and the response.
Credits include the specialists. credits.consumed is the orchestrator’s own spend plus what each specialist consumed. Each entry in delegations carries its own credits_consumed.
Turns can take minutes. Each delegation is a full agent run. Stream the response or raise your client timeout (see Long running calls).

Choosing a mode

Tier (in-app label)	API surface	Use when	Latency	Tools	Structured outputs
Ask	`chat_mode: llm_router` (not an `agent_model` string)	Routed LLM-first answers with agent context in the product	Lower	Per routing / resolved path	Yes
Execute	Default; `chat_mode: full_agent`; `magpie-2.5` when `agent_model` is omitted	Multi-step reasoning, tool calls, or data analysis	Higher	All	Yes
Auto	`chat_mode: auto`	Compatibility value that currently runs as Execute (`full_agent`)	Higher	All	Yes
Extended	`magpie-1.1-flash`	Fast answers from knowledge bases (RAG) with `semantic_search` only	Medium	`semantic_search` only	Yes
Direct LLM	`llm-only`	Tool-free conversational or structured JSON from a fixed model key	Lowest	None	Yes
Orchestrator	`agent_routing: { mode: "orchestrator" }`	Requests that span several specialist agents in one turn	Highest (minutes)	Orchestrator delegation, plus each specialist’s tools	Yes
Beta	`magpie-3.0`	BETA. Magpie 3.0 on the public Converse API. Behavior and schema may change.	Higher	Magpie 3.0 tools	Yes

When config.agent_model is omitted, the API defaults to magpie-2.5 (Execute tier).

Introduction

Converse

Voice

Identity

Agents

Skills

Automations

Knowledge

Search

Conversations

Messages

Connections

Connection Providers

Connectors

Files

Tools

Models

Secrets

Webhooks

Memory

Pages

MCP Servers - Beta

Batch Predictions

Event Triggers

Channels

Procore

Organization

Ask (in-app; `chat_mode: llm_router`)

Execute (full agent models)

Extended (search-focused agent)

Direct LLM (`llm-only`)

Beta (`magpie-3.0`)

Agent routing (`agent_routing`)

Orchestrator mode

Choosing a mode

Ask (in-app; chat_mode: llm_router)

Execute (full agent models)

Extended (search-focused agent)

Direct LLM (llm-only)

Beta (magpie-3.0)

Agent routing (agent_routing)

Orchestrator mode

Choosing a mode

Ask (in-app; `chat_mode: llm_router`)

Direct LLM (`llm-only`)

Beta (`magpie-3.0`)

Agent routing (`agent_routing`)