# Best practices

Once you start using The Grid, you migrate your workloads from provider-specific models to Instruments: which ensure a minimum quality of inference while remaining model and supplier agnostic. The minimum requirements are defined by the [instrument-specifications-latest](https://thegrid.ai/docs/introduction/instruments-and-specifications/instrument-specifications-latest "mention").

We suggest the following guidelines to make this transition smooth and to ensure maximum performance and high reliability.

## What Use Cases are ideal fit for Instruments?

1. Suggested Use Cases:
   1. **General reasoning and conversational workflows**: chatbots, assistants, and interactive product UX
   2. **Summarization at scale**: meeting notes, long documents, and multi-part text summaries
   3. **Document Q\&A**: retrieval + answer generation over internal docs, policies, and knowledge bases
   4. **Code assist for everyday engineering**: code generation, code explanation, and bug fixes
   5. **Parsing Structured outputs**: JSON-like schemas and predictable response formats for downstream parsing
   6. **Tool usage**: calling tools as part of manual or agentic workflows
2. More generally, here are some great first workloads you can migrate:
   1. Latency-sensitive user-facing chat experiences
   2. High-volume internal automations (summaries, triage, classification, routing)
   3. Code assistant workflows for common tasks (snippets, refactors, fixes)
3. A few considerations before choosing Instruments:
   1. If a workflow is sensitive to a particular model’s style, run a quick side-by-side eval against the Instrument spec before fully switching.
   2. Keep prompts portable and stick to documented Instrument parameters so any conforming Supplier can serve your requests reliably.

## Mapping other chat APIs to The Grid

The Consumption API uses the Chat Completions API Interface. However, to use Instruments, we pass the `instrument_id` in the `model` parameter field.

**Conceptual mapping:**

* `model` → `instrument_id` (e.g., "gpt-5" → "text-fast" or "text-prime")
* `base_url` → Grid consumption base URL
* `api_key` → Grid consumption key

**Example request change:**

{% tabs %}
{% tab title="Before (OpenAI SDK)" %}

```js
import os
import openai

client = openai.OpenAI(
    api_key=os.environ['OPENAI_API_KEY'],
)

response = client.chat.completions.create(
    model='gpt-5',
    messages=[
        {'role': 'user', 'content': 'Hello!'},
    ],
)

print('Response:', response.choices[0].message.content)
```

{% endtab %}

{% tab title="After (The GRID)" %}

```js
import os
import openai

client = openai.OpenAI(
    api_key=os.environ['GRID_CONSUMPTION_API_KEY'],
    base_url='<https://consumption.api.thegrid.ai/api/v1>'
)

response = client.chat.completions.create(
    model='text-standard',
    messages=[
        {'role': 'user', 'content': 'Hello!'},
    ],
)

print('Response:', response.choices[0].message.content)
```

{% endtab %}
{% endtabs %}

**Note:** GRID uses the OpenAI Chat Completions API format. Native Anthropic and Google APIs (like Messages, Responses) are not currently supported. Use the OpenAI SDK as shown above.

## Best practices for modifying prompts when using Instruments

When using an Instrument, your prompts should be portable so any model serving the instrument provides acceptable inference.

<details>

<summary>Use a strict allowlist for request parameters</summary>

Send only officially supported parameters. Treat everything else as best-effort.

{% hint style="info" %}
Official list of suppported parameters in the Consumption API will be published soon.
{% endhint %}

</details>

<details>

<summary>Prompt for outcomes, not model quirks</summary>

**Good prompt (portable):**

{% code expandable="true" %}

```js
const messages = [
  {
    role: 'system',
    content: 'Summarize the meeting notes and provide a checklist with all accomplished tasks and outstanding items.'
  },
  {
    role: 'user',
    content: 'Hey everyone welcome, today we are going to..."'
  }
];

```

{% endcode %}

**Avoid (model-specific):**

{% code expandable="true" %}

```js
// Don't rely on specific model personalities or formatting habits
const messages = [
  {
    role: 'system',
    content: 'You are Claude, an AI assistant made by Anthropic...' // Too specific!
  }
];

```

{% endcode %}

</details>

<details>

<summary>Validate outputs in your app layer</summary>

```javascript
async function chatWithValidation(consumptionKey, request) {
  const result = await callGridWithRetries(consumptionKey, request);

  try {
    const content = result.choices[0].message.content;

    // If expecting JSON, parse and validate
    if (request.response_format?.type === 'json') {
      const parsed = JSON.parse(content);

      // Validate required fields
      if (!parsed.summary || !parsed.sentiment) {
        throw new Error('Missing required fields in response');
      }

      return parsed;
    }

    return content;

  } catch (error) {
    console.warn('Output validation failed, retrying once...');

    // Retry once
    const retryResult = await callGridWithRetries(consumptionKey, request, 1);
    return retryResult.choices[0].message.content;
  }
}

```

</details>

<details>

<summary>Plan for batch workloads with custom queueing</summary>

Key considerations:

* Estimate capacity before starting
* Pre-buy capacity, then start when available
* Treat rate limits and concurrency as first-class controls
* Monitor capacity continuously during run
* Decide what happens if you run low mid-run

See the [Batching Sequencer](https://thegrid.ai/docs/technical-guides/batch-sequencing-with-limit-orders) example script for our guideline implementation.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://thegrid.ai/docs/technical-guides/best-practices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.