> ## 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](/api-reference/converse/converse).

## Your first call

<CodeGroup>
  ```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);
  ```
</CodeGroup>

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

## Use an agent

To run a configured [agent](/api-reference/agents/agents), pass its `agent_id`. The agent's instructions, knowledge, and tools are applied automatically.

<CodeGroup>
  ```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>',
  });
  ```
</CodeGroup>

The `config` object lets you override an agent's settings for a single turn without changing the stored agent. See [Getting started with Agents](/api-reference/agents/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](/api-reference/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.

<CodeGroup>
  ```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' },
      ],
    },
  });
  ```
</CodeGroup>

More detail in [Knowledge and corpus](/api-reference/converse/knowledge-and-corpus).

## Stream responses

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

<CodeGroup>
  ```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);
    }
  }
  ```
</CodeGroup>

See [Streaming](/api-reference/converse/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.

<CodeGroup>
  ```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);
  ```
</CodeGroup>

More in [Structured outputs](/api-reference/converse/structured-outputs).

## Add file inputs

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

<CodeGroup>
  ```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 },
        ],
      },
    ],
  });
  ```
</CodeGroup>

See [File inputs](/api-reference/converse/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](/api-reference/conversations/create-conversation)).

<CodeGroup>
  ```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,
  });
  ```
</CodeGroup>

## More capabilities

* [MCP servers](/api-reference/converse/mcp-servers) — connect external tools via the Model Context Protocol (Beta).
* [Rate limits](/api-reference/rate-limits) — limits, headers, and retry guidance.

## Next steps

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