Configure an AI Connection¶
Before using the AI Assistant, your organization must have an active AI provider connection with a configured model.
FieldOps uses a Bring Your Own Key (BYOK) approach. Your organization provides its own API key for the AI provider it chooses to use.
Before You Begin¶
Before creating an AI connection, create an API key with the AI provider you want to use.
You need:
- An account with a supported AI provider
- An API key from that provider
- Access to AI Connections in FieldOps
- At least one active model configured for the selected provider
Your AI provider account is separate from your FieldOps account.
FieldOps does not provide or purchase AI credits on your behalf. Your organization manages its provider account, API key, credits, and billing directly with the provider.
Get an API Key¶
Use the official provider website or documentation to create an API key.
The exact process, billing requirements, available models, and account requirements vary by provider.
| Provider | Get an API key |
|---|---|
| OpenAI | OpenAI API platform ↗ |
| Google Gemini | Google AI Studio ↗ |
| Anthropic | Anthropic Console ↗ |
| Mistral | Mistral Studio ↗ |
| DeepSeek | DeepSeek Platform ↗ |
| Qwen | Alibaba Cloud Model Studio — API Key ↗ |
| Meta Llama | Llama models may be accessed through different API providers. Use the API provider configured for your FieldOps environment. |
| Grok | xAI Console ↗ |
| Kimi | Kimi / Moonshot AI Platform ↗ |
Important
API key creation, billing, credits, usage limits, and model availability are managed by the AI provider. FieldOps does not create or supply these credentials.
Add an AI Connection¶
1. Open AI Connections¶
From the FieldOps sidebar, open:
AI → AI Connections
The AI Connections page displays the AI provider connections configured for your organization.
You can see information such as:
- Connection name
- Provider
- Default model
- Active status
- Default connection status
- Connection test status
- Last tested time
2. Click Add AI Connection¶
Click Add AI Connection to create a new provider connection.
The connection form contains the provider configuration and connection status information.
Select a Provider¶
Under AI Provider, select the provider you want to connect.
Only providers with active models configured in FieldOps are available for selection.
Depending on your FieldOps configuration, available providers may include:
- OpenAI
- Google Gemini
- Anthropic
- Mistral
- DeepSeek
- Qwen
- Meta Llama
- Grok
- Kimi
The available providers may vary depending on the models enabled in your FieldOps environment.
Note
If a provider does not have any active models configured, it will not appear as an available provider when creating an AI connection.
Name the Connection¶
Enter a Connection name.
Choose a name that makes it easy to identify the connection later.
For example:
Gemini Production
or:
OpenAI Operations
The connection name is used to identify the connection within FieldOps.
Enter the API Key¶
Enter your provider's API key in the API key field.
The API key is treated as a sensitive credential.
FieldOps encrypts the API key before storing it.
After the connection has been saved, the complete API key is not displayed again. When editing an existing connection, FieldOps displays only a masked version.
Security
Never enter API keys into the AI Assistant conversation, project descriptions, visit notes, findings, corrective actions, or other operational records.
Select the Default Model¶
Select a Default model for the connection.
The available models depend on the provider you selected.
Each model may include information such as:
- Model name
- Model tier
- Description
- Strengths
- Best use cases
After selecting a model, FieldOps displays model guidance to help you understand what the model is best suited for.
Choosing a Model¶
Consider the type of AI work your organization expects to perform.
For simple questions such as:
How many sites do we have?
a fast general-purpose model may be sufficient.
For more analytical questions such as:
Why has Kapsabet Sub-County Hospital been underperforming for the last three months?
you may prefer a model with stronger reasoning and analytical capabilities.
For longer or more complex investigations, a model with a larger context capacity may be useful.
The model selection does not change how users interact with the AI Assistant. Users continue to ask questions using natural language.
Activate the Connection¶
The Active option determines whether FieldOps can use the connection.
When enabled:
The connection can be used by FieldOps AI.
When disabled:
The connection cannot be used by FieldOps AI.
Leave the connection active if you want it to be available for AI requests.
An inactive connection remains configured but cannot be used by FieldOps AI.
Set the Default Connection¶
The Default connection option determines whether this connection should be used when an AI feature does not specify another connection.
If your organization has multiple AI connections, you can configure one as the default.
For example, an organization might have:
- Gemini Production
- OpenAI Analysis
- DeepSeek Development
One of these connections can be designated as the default.
Default connection
The default connection is used when an AI feature does not specify another connection.
The Active and Default connection settings serve different purposes. A connection can be configured as the default connection, but it must be active to be usable by FieldOps AI.
Save the Connection¶
After entering the required information, save the AI connection.
The connection will then appear in the AI Connections list.
At this point, the connection may still need to be tested.
Test the Connection¶
After creating the connection, use the Test action from the AI Connections list.
FieldOps sends a small test request to the selected AI provider.
A successful test confirms that FieldOps can communicate with the provider using the configured connection and selected model.
The connection status will show the result of the most recent test.
Possible states include:
- Success — the provider responded correctly.
- Failed — the provider did not return the expected response.
- Never tested — the connection has not yet been tested.
The connection also records the time it was last tested.
Tip
Test a new connection immediately after creating it. This helps identify credential, account, model, or provider issues before users begin using the AI Assistant.
Connection Status¶
When editing an existing connection, FieldOps displays additional connection information.
This includes:
API Key¶
FieldOps displays a masked version of the configured API key rather than exposing the complete credential.
Last Tested¶
Shows when the connection was most recently tested.
Connection Status¶
Shows the result of the most recent connection test.
This allows administrators to quickly determine whether a configured connection has recently been verified.
Multiple AI Connections¶
An organization can configure multiple AI provider connections.
For example:
| Connection | Provider | Model | Purpose |
|---|---|---|---|
| Gemini Production | Google Gemini | Configured Gemini model | General AI use |
| OpenAI Analysis | OpenAI | Configured OpenAI model | Complex analysis |
| DeepSeek Development | DeepSeek | Configured DeepSeek model | Development and testing |
The exact providers and models available depend on your FieldOps configuration.
Multiple connections allow an organization to use and evaluate different providers and models without changing how users interact with the AI Assistant.
Changing a Model¶
You can edit an existing AI connection and select a different available model for that provider.
The available models are determined by the selected provider and the active models configured in FieldOps.
The provider itself cannot be changed when editing an existing connection.
If you need to use a different provider, create a new AI connection for that provider.
For example, if an existing connection uses Google Gemini and you want to use OpenAI instead, create a new OpenAI connection rather than changing the provider on the existing connection.
Changing an API Key¶
When editing an existing connection, you can enter a new API key.
Leave the API key field blank if you want to keep the existing key.
If you replace the key, test the connection again to verify that the new credentials work correctly.
Important
The existing API key is not displayed in full. The field remains blank when you edit the connection unless you enter a new key.
Deactivating a Connection¶
You can disable a connection by turning off Active.
An inactive connection remains stored in FieldOps but cannot be used by FieldOps AI.
This can be useful when:
- A provider connection is temporarily unavailable
- An API key needs to be replaced
- A provider is being evaluated
- An organization no longer wants to use a particular connection
- You want to keep the configuration for possible future use
You can reactivate the connection later if required.
Deleting a Connection¶
An existing AI connection can be deleted from the AI Connections list.
Before deleting a connection, consider whether it is currently being used as the organization's default connection or by other AI features.
If the connection is still required, deactivate it instead of deleting it.
Troubleshooting a Failed Connection¶
If a connection test fails, check the following.
API Key¶
Verify that the API key is correct and has not expired or been revoked.
If you recently replaced the API key, save the connection and run the Test action again.
Provider Account¶
Check that your organization has an active account with the AI provider.
Provider Credits¶
Some providers require available credits or an active billing arrangement before API requests can be made.
Check the provider's account if requests are being rejected because of insufficient credits or billing restrictions.
Model Availability¶
Verify that the selected model is still available through your provider account.
A model may be unavailable because of provider changes, account restrictions, or model retirement.
Provider Limits¶
The provider may have rate limits, usage limits, or account restrictions.
Check the provider's account and documentation if requests are being rejected because of usage limits.
Provider Availability¶
The provider may be experiencing an outage or temporary service interruption.
If the credentials and configuration appear correct, try testing the connection again later.
After resolving the issue, run the Test action again.
Recommended Setup¶
For most organizations, start with one well-tested connection:
- Create an account with an AI provider.
- Generate an API key using the provider's official website.
- Open AI → AI Connections in FieldOps.
- Click Add AI Connection.
- Select the provider.
- Give the connection a recognizable name.
- Enter the API key.
- Select a suitable default model.
- Keep Active enabled.
- Set it as the Default connection if appropriate.
- Save the connection.
- Run the Test action.
- Open the AI Assistant and ask a question.
For example:
Which sites currently require attention?
If the connection test succeeds and the AI Assistant has access to the relevant FieldOps data, the assistant can process the request using the configured provider and model.
Using Multiple Providers¶
Organizations that want to evaluate different AI providers can create multiple connections.
For example:
- Create a Gemini connection.
- Create an OpenAI connection.
- Create a DeepSeek connection.
- Give each connection an appropriate default model.
- Test each connection.
- Keep the connections you want to use active.
This allows administrators to compare different providers and models while keeping the user experience within FieldOps consistent.
Users continue to ask questions naturally through the AI Assistant regardless of which configured connection is used.
Important¶
An AI connection determines which AI provider and model FieldOps uses.
It does not change the underlying FieldOps data.
Your organization's projects, sites, visits, findings, corrective actions, and other operational records remain in FieldOps.
The AI Assistant uses the configured AI connection together with its available FieldOps data and tools to analyze relevant information and return a natural-language response.
The overall workflow is:
Ask → retrieve relevant FieldOps data → analyze → respond
The AI connection provides the AI model used for the analysis; the underlying FieldOps records remain the source of truth.