Skip to content

AI URI

Original Author: Michael Vorburger.ch
Contributors: YOU, contribute?
Status: Ready to Implement

Introduction

As you know, “There are only two hard things in Computer Science: cache invalidation and naming things.”

This spec proposes a convention for consistently naming some things related to AI with URIs.

These URIs are independent of any specific programming language, framework, tool, etc.

Perhaps your favorite one could adopt it!

Language Models (LM)

Great for Bring Your Own Model (“BYOM”) configuration!

Ollama 🦙

This is free!

http://localhost:11434?type=ollama&model=gemma3:1b is the URI of the Gemma 3 (1B) large language model running in Ollama, at http://localhost:11434.

The model query parameter of the URI needs to use a model name from https://ollama.com/search.

MCP Tools support may still have some bugs (see #1628).

Google AI 🔮

This API has a very generous free tier. It requires a Google account.

google://?model=gemini-2.5-flash is the URI of the Gemini 2.5 Flash LLM, used via the Google (Gemini) AI API.

For security, the API key is not part of this URI, but configured in a secret named GOOGLE_AI_API_KEY. Such keys can be easily obtained by clicking on Get API key in https://aistudio.google.com.

Note that the Google (Gemini) AI API is a different API from the Google Cloud Vertex AI Platform API.

Anthropic Claude

This API requires registering a credit card to purchase credits.

claude://?model=claude-3-haiku-20240307 is the URI of the Anthropic Claude 3 Haiku LLM.

For security, the API key is not part of this URI, but configured in a secret named ANTHROPIC_API_KEY. Such keys can be easily obtained on https://console.anthropic.com/settings/keys.

Mock 🦜

mocklm:hello,%20world is the URI of a mock LM which, like a 🦜 parrot, always replies with “hello, world” to any prompt.

Echo 🪞

echo:/ is the URI of a LM which, like a 🪞 mirror, always “echos back” the prompt itself.

This is sometimes suitable e.g. for testing.

Common

Language Model (LM) may include the following common configuration URI parameters:

  • temperature
  • topP
  • topK
  • maxOutputTokens

Some models and/or the client libraries we use for them might not support some of these.

Security

It is intentional that none of these URIs contain API keys. They are configured “elsewhere”, with a mechanism specific to the supporting framework or tool; typically in a secret.

This is primarily for security reasons, as such URIs may be used e.g. in agent configuration files stored under source control, or even shown to technical end-users in UIs.

It is also often more convenient in practice; because while the choice of a model, and its parameters, is often specific to a given Agent configuration, the specific API key really is not, and instead belongs to separate configuration.

We are not aware of any similar LM URI naming scheme. Please add any that you know of here.

ToDo

  1. Add many more URIs
  2. Add additional common parameters: seed, stopSequences etc. (see dotprompt config)

Support

Haiku

A URI's a name,
For AI, it's the same,
Ollama, Google, ...
No longer a struggle,
To call models by name.