Agent Setup
Give a coding agent a safe runbook for integrating Elektric into an existing application.
Give this page to Codex, Cursor, Claude Code, or another coding agent when you want it to add Elektric to an existing project.
The agent should inspect your codebase first, preserve your existing architecture, and make the smallest change needed to route AI requests through Elektric.
#Give this to your agent
The following instruction is designed to be copied as one block.
You are integrating Elektric into this repository.
Before changing code:
1. Inspect the repository and identify:
- the application runtime and language;
- the existing AI provider/client;
- where API keys are loaded;
- where AI requests are sent;
- how conversation/history state is currently managed;
- whether responses are streamed;
- whether the application uses images, audio, video, transcription, embeddings, or other AI operations.
2. Do not redesign the application. Preserve the current architecture and make the smallest integration change that works.
3. Use these canonical Elektric identifiers:
- API key environment variable: `ELEKTRIC_API_KEY`
- API base: `https://elektric.ai/v1`
- Grid model: `elektric-grid`
4. Choose Grid or Wire deliberately:
Use Grid when Elektric should choose the operation, model, and provider.
Use Wire when the application must call a specific public model.
5. If the application already uses a supported OpenAI client, prefer the OpenAI-compatible migration path when it requires fewer changes.
6. Otherwise use the current Elektric SDK or API pattern that best matches the repository.
7. Keep `ELEKTRIC_API_KEY` server-side. Never expose it in browser/client code or commit it to source control.
8. Do not add Elektric-managed Conversation, Memory, Knowledge, `userId`, `conversationId`, or old Context behavior. Those are retired public concepts. Preserve the application's existing message/history handling.
9. Do not hard-code guesses about current model capabilities. Use authenticated `GET /v1/models` or the current Models documentation when model capability information is needed.
10. Do not assume every operation has the same limits. Use authenticated `GET /v1/limits` for project limits and the relevant product documentation for model/media capabilities.
11. Preserve existing streaming behavior where supported.
12. For exact-model Wire requests, do not add automatic model substitution. Wire must execute the requested public model or return an error.
13. For Grid requests, use the exact canonical model identifier `elektric-grid`.
14. Do not use `elektrik-grid` or invent alternate model names.
15. After implementation:
- run the project's existing tests;
- run typechecking/build checks;
- exercise at least one real Elektric request if credentials are available;
- confirm the request reaches the intended Grid or Wire path;
- confirm errors do not expose secrets.
16. Report:
- files changed;
- integration path chosen;
- Grid or Wire choice;
- environment variables required;
- tests/builds run;
- anything you could not verify.
Do not modify unrelated files.#Choose Grid or Wire
| Use | When |
|---|---|
| Grid | You want Elektric to choose the operation, model, and provider. |
| Wire | You want a specific public model. |
For Grid, send `model: "elektric-grid"`.
For Wire, use the exact public model ID returned by `GET /v1/models`.
Wire does not silently substitute another model.
#If the app already uses OpenAI
If the project already uses a supported OpenAI client, the smallest migration may be to keep that client and change the API key, base URL, and model.
Keep the rest of the application's message/history logic where it already lives.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.ELEKTRIC_API_KEY,
baseURL: "https://elektric.ai/v1",
});
const response = await client.chat.completions.create({
model: "elektric-grid",
messages: [{ role: "user", content: "Hello" }],
});#If this is a new integration
For a new integration, start with the Quickstart. It contains the shortest current path to a working request.
#If the app uses images, audio, or video
Inspect how the application currently represents media before changing anything. Preserve its existing upload/storage flow unless Elektric requires a different public input format.
Grid routes supported multimodal requests by intent. Understanding media stays on the chat path; generation and transcription route to the corresponding operation.
Do not infer media support from a model name. Check `GET /v1/models` for current capabilities.
#Keep state in the application
Elektric chat is stateless with respect to retired stateful products.
Send the messages or context the request needs. If your application already stores conversation history, keep using that system.
Do not add `userId` or `conversationId` solely for Elektric.
#Keep the API key server-side
Store `ELEKTRIC_API_KEY` in your server environment or secret manager. Never expose a project API key in browser JavaScript, mobile application bundles, logs, or source control.
ELEKTRIC_API_KEY=...#Verify the integration
Use `GET /v1/models` to verify current model IDs and capabilities. Use authenticated `GET /v1/limits` to inspect the limits applied to the project.
- The application uses `https://elektric.ai/v1`.
- Grid requests use exactly `elektric-grid`.
- Exact-model requests use a current model ID from `/v1/models`.
- The API key remains server-side.
- Existing conversation/history handling still works.
- Streaming behavior is preserved where required.
- At least one request succeeds with the expected path.
- Errors are logged with the Request ID, not the API key.
#What the agent should not do
- Do not replace working application architecture unnecessarily.
- Do not add retired Conversation, Memory, Knowledge, or Context integrations.
- Do not invent model IDs or alternate spellings.
- Do not expose `ELEKTRIC_API_KEY` to client-side code.
- Do not silently change an exact-model Wire request into Grid.
- Do not silently add provider fallback to Wire.
- Do not hard-code model capabilities that are available from `/v1/models`.
- Do not modify unrelated files just to complete the integration.
#Canonical references
Quickstart →Grid →Wire →Models →OpenAI migration →Errors & Limits →Capture & privacy →