> ## Documentation Index
> Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started with Converse

> Make your first Converse call, then add modes, knowledge, streaming, structured outputs, file inputs, and MCP servers.

**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](https://developers.datagrid.com/api-reference/converse/converse.md).

## Your first call

```python Python theme={null}
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)
```

```javascript JavaScript theme={null}
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](https://developers.datagrid.com/api-reference/agents/agents.md), pass its `agent_id`. The agent's instructions, knowledge, and tools are applied automatically.

```python Python theme={null}
response = client.converse(
    prompt="What's our policy on remote work?",
    agent_id="<your-agent-id>",
)
```

```javascript JavaScript theme={null}
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](https://developers.datagrid.com/api-reference/agents/agents.md) 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](https://developers.datagrid.com/api-reference/converse/modes.md) 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.

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

```javascript JavaScript theme={null}
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](https://developers.datagrid.com/api-reference/converse/knowledge-and-corpus.md).

## Stream responses

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

```python Python theme={null}
response = client.converse(prompt="Write a short summary", stream=True)

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

```javascript JavaScript theme={null}
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](https://developers.datagrid.com/api-reference/converse/streaming.md) 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.

```python Python theme={null}
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)
```

```javascript JavaScript theme={null}
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);
```

More in [Structured outputs](https://developers.datagrid.com/api-reference/converse/structured-outputs.md).

## Add file inputs

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

```python Python theme={null}
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},
            ],
        }
    ]
)
```

```javascript JavaScript theme={null}
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](https://developers.datagrid.com/api-reference/converse/file-inputs.md) 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](https://developers.datagrid.com/api-reference/conversations/create-conversation.md)).

```python Python theme={null}
first = client.converse(prompt="What's the capital of France?")
follow_up = client.converse(
    prompt="What's its population?",
    conversation_id=first.conversation_id,
)
```

```javascript JavaScript theme={null}
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](https://developers.datagrid.com/api-reference/converse/mcp-servers.md) — connect external tools via the Model Context Protocol (Beta).
* [Rate limits](https://developers.datagrid.com/api-reference/rate-limits.md) — limits, headers, and retry guidance.

## Next steps

* [Getting started with Agents](https://developers.datagrid.com/api-reference/agents/agents.md) — create reusable agents to run via Converse.
* [Converse modes](https://developers.datagrid.com/api-reference/converse/modes.md) — pick the right mode for each task.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.