Converse

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

prompt

required

A text prompt to send to the agent.

config

object

Override the agent config for this converse call. This is applied as a partial override.

Show child attributes

config.agent_model

default:magpie-1.1

The version of Datagrid's agent brain.

magpie-1.1 is the default and most powerful model.
magpie-1.1-flash is a faster model useful for RAG usecases, it currently only supports semantic_search tool. Structured outputs are not supported with this model.
Can also accept any custom string value for future model versions.
Magpie-2.0 our latest agentic model with more proactive planning and reasoning capabilities.

Predefined agent model versions The version of Datagrid's agent brain.

magpie-1.1 is the default and most powerful model.
magpie-1.1-flash is a faster model useful for RAG usecases, it currently only supports semantic_search tool. Structured outputs are not supported with this model.
Can also accept any custom string value for future model versions.
Magpie-2.0 our latest agentic model with more proactive planning and reasoning capabilities.

Predefined agent model versions

Available options:

magpie-1.1,

magpie-1.1-flash,

magpie-2.0,

magpie-1

config.llm_model

default:gemini-2.5-flash

The LLM used to generate responses. The LLM used to generate responses.

Available options:

gemini-2.5-pro,

gemini-2.5-pro-preview-05-06,

gemini-2.5-flash,

gemini-2.5-flash-preview-04-17,

gemini-2.5-flash-lite,

gpt-5,

gpt-5.1,

gemini-2.0-flash-001,

gemini-2.0-flash,

gemini-1.5-pro-001,

gemini-1.5-pro-002,

gemini-1.5-flash-002,

gemini-1.5-flash-001,

chatgpt-4o-latest,

gpt-4o,

gpt-4,

gpt-4-turbo,

gpt-4o-mini

config.knowledge_ids

string[] | null

Array of Knowledge IDs the agent should use during the converse. When ommited, all knowledge is used.

config.tools

object[]

Tools that this agent can use. Array of the agent tools to enable. If not provided - default tools of the agent are used. If empty list provided - none of the tools are used. If null provided - all tools are used. When connection_id is set for a tool, it will use that specific connection instead of the default one.

Knowledge management tools:

data_analysis: Answer statistical or analytical questions like "Show my quarterly revenue growth"
semantic_search: Search knowledge through natural language queries.
agent_memory: Agents can remember experiences, conversations and user preferences.
schema_info: Helps the Agent understand column names and dataset purpose. Avoid disabling
table_info: Allow the AI Agent to get information about datasets and schemas
create_dataset: Agents respond with data tables

Actions:

calendar: Allow the Agent to access and make changes to your Google Calendar
schedule_recurring_message_tool: Eliminate busywork such as: "Send a summary of today's meetings at 5pm on workdays"

Data processing tools:

data_classification: Agents handle queries like "Label these emails as high, medium, or low priority"
data_extraction: Helps the agent understand data from other tools. Avoid disabling
image_detection: Extract information from images using AI
pdf_extraction: Extraction of information from PDFs using AI

Enhanced response tools:

connect_data: Agents provide buttons to import data in response to queries like "Connect Hubspot"
download_data: Agents handle queries like "download the table as CSV"

Web tools:

web_search: Agents search the internet, and provide links to their sources
fetch_url: Fetch URL content
company_prospect_researcher: Agents provide information about companies
people_prospect_researcher: Agents provide information about people

Show child attributes

config.tools.name

required

Available options:

data_analysis,

semantic_search,

agent_memory,

schema_info,

table_info,

create_dataset,

find_files,

read_file_contents,

file_analysis,

calendar,

email,

schedule_recurring_message_tool,

procore,

egnyte,

notion,

slack,

microsoft_teams,

sharepoint,

drive,

fieldwire,

webbrowser,

pdf_manipulation,

pdf_generator,

acc,

docusign,

webflow,

hubspot,

nec,

github,

trimble_project_site,

linkedin,

google_docs,

google_slides,

google_sheets,

avoma,

code_tool,

data_classification,

data_extraction,

image_detection,

attachment_extraction,

pdf_extraction,

pdf_page_info,

youtube_video_analysis,

calculate,

pdf_form_filling,

image_generator,

video_generator,

connect_data,

download_data,

web_search,

fetch_url,

company_prospect_researcher,

people_prospect_researcher

config.tools.connection_id

string | null

The ID of the connection to use for the tool. The ID of the connection to use for the tool.

config.system_prompt

string | null

Directs your AI Agent's operational behavior.

config.custom_prompt

string | null

Use custom prompt to instruct the style and formatting of the agent's response

config.planning_prompt

string | null

Define the planning strategy your AI Agent should use when breaking down tasks and solving problems

config.disabled_tools

(enum<string> | string | object)[] | null

Array of the agent tools to disable. Disabling is performed after the 'agent_tools' rules are applied. For example, agent_tools: null and disabled_tools: [data_analysis] will enable everything but the data_analysis tool. If nothing or [] is provided, nothing is disabled and therefore only the agent_tools setting is relevant.

Available options:

data_analysis,

semantic_search,

agent_memory,

schema_info,

table_info,

create_dataset,

find_files,

read_file_contents,

file_analysis,

calendar,

email,

schedule_recurring_message_tool,

procore,

egnyte,

notion,

slack,

microsoft_teams,

sharepoint,

drive,

fieldwire,

webbrowser,

pdf_manipulation,

pdf_generator,

acc,

docusign,

webflow,

hubspot,

nec,

github,

trimble_project_site,

linkedin,

google_docs,

google_slides,

google_sheets,

avoma,

code_tool,

data_classification,

data_extraction,

image_detection,

attachment_extraction,

pdf_extraction,

pdf_page_info,

youtube_video_analysis,

calculate,

pdf_form_filling,

image_generator,

video_generator,

connect_data,

download_data,

web_search,

fetch_url,

company_prospect_researcher,

people_prospect_researcher

config.agent_tools

(enum<string> | string | object)[] | null

deprecated

Deprecated, use tools instead

Available options:

data_analysis,

semantic_search,

agent_memory,

schema_info,

table_info,

create_dataset,

find_files,

read_file_contents,

file_analysis,

calendar,

email,

schedule_recurring_message_tool,

procore,

egnyte,

notion,

slack,

microsoft_teams,

sharepoint,

drive,

fieldwire,

webbrowser,

pdf_manipulation,

pdf_generator,

acc,

docusign,

webflow,

hubspot,

nec,

github,

trimble_project_site,

linkedin,

google_docs,

google_slides,

google_sheets,

avoma,

code_tool,

data_classification,

data_extraction,

image_detection,

attachment_extraction,

pdf_extraction,

pdf_page_info,

youtube_video_analysis,

calculate,

pdf_form_filling,

image_generator,

video_generator,

connect_data,

download_data,

web_search,

fetch_url,

company_prospect_researcher,

people_prospect_researcher

config.disabled_agent_tools

(enum<string> | string | object)[] | null

deprecated

Deprecated, use disabled_tools instead. If not provided - no tools are disabled.

Available options:

data_analysis,

semantic_search,

agent_memory,

schema_info,

table_info,

create_dataset,

find_files,

read_file_contents,

file_analysis,

calendar,

email,

schedule_recurring_message_tool,

procore,

egnyte,

notion,

slack,

microsoft_teams,

sharepoint,

drive,

fieldwire,

webbrowser,

pdf_manipulation,

pdf_generator,

acc,

docusign,

webflow,

hubspot,

nec,

github,

trimble_project_site,

linkedin,

google_docs,

google_slides,

google_sheets,

avoma,

code_tool,

data_classification,

data_extraction,

image_detection,

attachment_extraction,

pdf_extraction,

pdf_page_info,

youtube_video_analysis,

calculate,

pdf_form_filling,

image_generator,

video_generator,

connect_data,

download_data,

web_search,

fetch_url,

company_prospect_researcher,

people_prospect_researcher

agent_id

string | null

The ID of the agent that should be used for the converse.

conversation_id

string | null

The ID of the present conversation to use. If it's not provided - a new conversation will be created.

stream

boolean | null

default:false

Determines the response type of the converse. Response is the Server-Sent Events if stream is set to true.

generate_citations

boolean | null

default:false

Determines whether the response should include citations. When enabled, the agent will generate citations for factual statements.

secret_ids

string[] | null

Array of secret ID's to be included in the context. The secret value will be appended to the prompt but not stored in conversation history.

text

object

Contains the format property used to specify the structured output schema. Structured output is not supported only supported by the default agent model, magpie-1.1 and magpie-2.0.

Show child attributes

text.format

object

The converse response will be a JSON string object, that adheres to the provided JSON schema.

const exampleJsonSchema = {
  $id: "movie_info",
  title: "movie_info",
  type: "object",
  properties: {
    name: {
      type: "string",
      description: "The name of the movie",
    },
    director: {
      type: "string",
      description: "The director of the movie",
    },
    release_year: {
      type: "number",
      description: "The year the movie was released",
    },
  },
  required: ["name", "director", "release_year"],
  additionalProperties: false,
};

const response = await datagrid.converse({
  prompt: "What movie won best picture at the 2001 oscars?",
  text: { format: exampleJsonSchema },
});

// Example response: "{ "name": "Gladiator", "director": "Ridley Scott", "release_year": 2000 }"
const parsedResponse = JSON.parse(response.content[0].text);

Response

200 - application/json

Converse response

The conversation.message object represents a message in a conversation.

object

enum<string>

required

The object type, which is always conversation.message.

Available options:

conversation.message

string

required

The message identifier.

agent_id

string

required

The ID of the agent that sent or responded to the message.

role

enum<string>

required

The role of the message sender - either 'user' or 'agent'.

Available options:

user,

agent

content

object[]

required

Contents of the message.

Show child attributes

content.type

enum<string>

required

Available options:

text

content.text

string

required

created_at

string<date-time>

required

The ISO string for when the message was created.

conversation_id

string

required

The ID of the conversation the message belongs to.

credits

object

required

Show child attributes

credits.consumed

number

required

The number of credits consumed by the converse call.

citations

object[] | null

required

Array of citations that provide knowledges for factual statements in the response. Each citation includes the referenced text and its knowledges.

Show child attributes

citations.citation

string

required

The text snippet from the response that is being cited.

citations.knowledges

object[]

required

Array of knowledges that support this citation.

Show child attributes

citations.knowledges.type

enum<string>

required

Available options:

image,

pdf_page,

record,

web_search,

sql_query_result,

action

citations.knowledges.knowledge_name

string

required

Name of the knowledge.

citations.knowledges.confirmations

string[]

required

An array of text snippets from the knowledge that confirm the citation.

citations.knowledges.knowledge_id

string

Id of the knowledge.

Introduction

Agents

Knowledge

Search

Conversations

Messages

Connections

Connectors

Files

Tools

Secrets

Memory

Organization

Converse

Authorizations

Body

Response