Getting started with Converse

Converse is the primary endpoint for talking to Datagrid: send a prompt, get an AI response. A single endpoint serves every mode and feature, so you can start simple and layer in capabilities as you need them. This page is a guided tour. For the full request and response schema, see the Converse API reference.

Your first call

import os
from datagrid_ai import Datagrid

client = Datagrid(api_key=os.environ.get("DATAGRID_API_KEY"))

response = client.converse(prompt="Hello world!")

print(response.content[0].text)

import Datagrid from 'datagrid-ai';

const client = new Datagrid({ apiKey: process.env['DATAGRID_API_KEY'] });

const response = await client.converse({ prompt: 'Hello world!' });

console.log(response.content[0].text);

The response content is an array; the text of the reply is at content[0].text.

Use an agent

To run a configured agent, pass its agent_id. The agent’s instructions, knowledge, and tools are applied automatically.

response = client.converse(
    prompt="What's our policy on remote work?",
    agent_id="<your-agent-id>",
)

const response = await client.converse({
  prompt: "What's our policy on remote work?",
  agent_id: '<your-agent-id>',
});

The config object lets you override an agent’s settings for a single turn without changing the stored agent. See Getting started with Agents for the full create-and-run flow.

Choose a mode

Converse can answer with a fast LLM-first response, a lighter search-backed agent, or a full multi-step agent. You select this with chat_mode (and config.agent_model):

`chat_mode`	In-app label	Best for
`llm_router`	Ask	Fast, routed answers with agent context.
`light_agent`	Extended	Search-backed (RAG) responses.
`full_agent`	Execute	Multi-step planning and broad tool use.
`auto`	—	Let the router pick the agent and mode per message.

See Converse modes for the full mapping between chat_mode, config.agent_model, and which tools each mode allows.

Scope knowledge with corpus

By default the agent can use all knowledge in scope. Pass config.corpus to limit a request to specific knowledge bases or pages.

response = client.converse(
    prompt="Summarize our Q4 policy updates",
    config={
        "corpus": [
            {"type": "knowledge", "knowledge_id": "kn_abc123"},
            {"type": "page", "page_id": "page_xyz789"},
        ]
    },
)

const response = await client.converse({
  prompt: 'Summarize our Q4 policy updates',
  config: {
    corpus: [
      { type: 'knowledge', knowledge_id: 'kn_abc123' },
      { type: 'page', page_id: 'page_xyz789' },
    ],
  },
});

More detail in Knowledge and corpus.

Stream responses

Set stream: true to receive the response incrementally as server-sent events — useful for responsive UIs on longer answers.

response = client.converse(prompt="Write a short summary", stream=True)

for event in response:
    if event.event == "delta":
        print(event.delta.text)

const response = await client.converse({ prompt: 'Write a short summary', stream: true });

for await (const event of response) {
  if (event.event === 'delta') {
    console.log(event.data.delta.text);
  }
}

See Streaming for the full event flow (start, delta, end).

Get structured output

Pass a JSON Schema in text.format to guarantee the response matches a schema. This works for every mode.

import json

response = client.converse(
    prompt="What movie won best picture at the 2001 Oscars?",
    text={
        "format": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "director": {"type": "string"},
                "release_year": {"type": "number"},
            },
            "required": ["name", "director", "release_year"],
            "additionalProperties": False,
        }
    },
)

result = json.loads(response.content[0].text)

const response = await client.converse({
  prompt: 'What movie won best picture at the 2001 Oscars?',
  text: {
    format: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        director: { type: 'string' },
        release_year: { type: 'number' },
      },
      required: ['name', 'director', 'release_year'],
      additionalProperties: false,
    },
  },
});

const result = JSON.parse(response.content[0].text);

Add file inputs

Upload a file, then reference it in a structured prompt to ask questions about documents, PDFs, or images.

with open("report.pdf", "rb") as file:
    uploaded = client.files.create(file=file)

response = client.converse(
    prompt=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Summarize this document"},
                {"type": "input_file", "file_id": uploaded.id},
            ],
        }
    ]
)

import fs from 'fs';

const uploaded = await client.files.create({ file: fs.createReadStream('report.pdf') });

const response = await client.converse({
  prompt: [
    {
      role: 'user',
      content: [
        { type: 'input_text', text: 'Summarize this document' },
        { type: 'input_file', file_id: uploaded.id },
      ],
    },
  ],
});

See File inputs for supported file types.

Continue a conversation

Pass a conversation_id to keep context across turns. The first call returns one (or you can create one explicitly via the Conversations API).

first = client.converse(prompt="What's the capital of France?")
follow_up = client.converse(
    prompt="What's its population?",
    conversation_id=first.conversation_id,
)

const first = await client.converse({ prompt: "What's the capital of France?" });
const followUp = await client.converse({
  prompt: "What's its population?",
  conversation_id: first.conversation_id,
});

More capabilities

MCP servers — connect external tools via the Model Context Protocol (Beta).
Rate limits — limits, headers, and retry guidance.

Next steps

Getting started with Agents — create reusable agents to run via Converse.
Converse modes — pick the right mode for each task.

Introduction

Converse

Voice

Identity

Agents

Knowledge

Search

Conversations

Messages

Connections

Connection Providers

Connectors

Files

Tools

Secrets

Webhooks

Memory

Pages

MCP Servers - Beta

Batch Predictions

Organization

Getting started with Converse

Your first call

Use an agent

Choose a mode

Scope knowledge with corpus

Stream responses

Get structured output

Add file inputs

Continue a conversation

More capabilities

Next steps

​Your first call

​Use an agent

​Choose a mode

​Scope knowledge with corpus

​Stream responses

​Get structured output

​Add file inputs

​Continue a conversation

​More capabilities

​Next steps

Your first call

Use an agent

Choose a mode

Scope knowledge with corpus

Stream responses

Get structured output

Add file inputs

Continue a conversation

More capabilities

Next steps