Configure and test a model connection
Configure a model connection, test it, and verify a small task before making it your default. Saving the form alone does not demonstrate that the provider accepted a request.
On this page
These controls describe the October 2026 development interface; labels and availability may differ in your installed release.
Prepare the connection details
Get the API protocol, upstream model identifier, Base URL and credentials from your provider or instance administrator. Use a model and account you are authorized to access. Model requests can leave your machine; consider the provider's data policy before supplying private content.
During initial setup, use Configure model. For subsequent management, open System config → Model config where that interface is available.
Fill the fields deliberately
- Provider type
The protocol actually supported by the endpoint
A provider's brand name alone does not establish its API protocol.
- Model name
A stable, recognizable name for this connection in AgReady
It is not necessarily the provider's model ID.
- Upstream model
The exact identifier accepted by the provider
A marketing model name may not be a valid API identifier.
- Base URL
The endpoint supplied for that protocol
Do not copy a URL from a different provider or the illustrated setup guide.
- API Key
The credential for that endpoint, entered only in your instance
Never include it in an example, screenshot or support request.
- Context tokens and capability settings
Values supported by the model and connection
A larger configured value does not increase the provider's actual limit or add capabilities.
https://api.example.com/v1 and example-chat-model in the illustrated walkthrough are fictional placeholders, not working configuration values. This guide does not claim universal provider compatibility.
Test, save and verify
- Use Test connection on your own configuration.
- Expand Latest test result and read the actual status. Do not infer success from the form closing or a saved notification.
- If the test passes, use Save model and confirm the intended configuration appears in the model list.
- Open Main Agent, check the selected model, and run the small first task.
- Check the response against the supplied notes. Only then choose the model as your default for routine work.
A connection test verifies less than a complete task. A text response does not establish that image input or tool use works. Verify additional capabilities separately with appropriate, non-sensitive inputs.
Diagnose a failure
- Connection test fails: compare the protocol, Base URL and exact upstream ID against the provider's instructions. Check credentials and account/quota messages when the error points there.
- Saved but does not work: inspect the real test result. The interface can retain a saved configuration after a failed test.
- The wrong model answers: check the selected model in the session rather than assuming the default changed an existing selection.
- A long task hits a limit: check the configured context capacity against the actual model. Shorten irrelevant input; do not increase a number merely to suppress a warning.
- Chat works but tools fail: inspect the tool environment and permissions. Replacing model credentials is not a general fix for missing tools.
Change one relevant setting at a time and retain the new error if it changes. For support, share the version, provider/protocol name when appropriate, failing step and a redacted error—not keys, headers, full configuration or private task content.