First test with an LLM model

This page is an optional starting point. It is not a prerequisite for using ALIDA agents: it is here to help you get familiar with the platform's LLM models and to verify, with two curl commands, that access works.

A model and an agent are not the same thing

Here you talk directly to a model, not to an agent. This distinction is the most important thing to clear up before going further.

An LLM model is served by Ollama and is reachable as an ordinary HTTP endpoint. It receives text, returns text, and ends there: it has no memory of the previous conversation, no tools, and no knowledge of the ALIDA context you are working in. That is exactly what you try out on this page.

An agent, instead, is an ALIDA Service that uses a model: it keeps the session, can use tools and MCP servers, works on repositories and datasets, and is connected to the platform chat. An agent is a long-running component with its own exposed ports, not a model endpoint.

Agents must be deployed in a workflow

ALIDA ships two agents: the OpenCode agent and the ADK agent. There is no list of agents "already served" by the platform to connect to: each of the two must be placed in a workflow, configured with its ports, and started. Only while that workflow is running does the agent expose the endpoints the chat calls, as described in Configure and use the chat.

The models are served by Ollama

ALIDA uses Ollama and provides both native APIs and OpenAI-compatible endpoints. The sections below show how to reach it, list the available models, and get a first response.

Two ways to reach the models

The same models can be reached in two ways, which differ in who mediates the call and how the call is authenticated.

	ALIDA gateway	Direct Ollama access
Base URL	https://<alida-instance-url>/events/ollama/ollama-user	https://ollama.develop.alidalab.it
Who answers	ALIDA, which authenticates the caller and forwards the request to Ollama	The Ollama server, contacted directly
Authentication	Authorization: Apikey <api-key>, with an API key created in the ALIDA user interface	Authorization: Basic <base64-credentials>, with credentials issued by an administrator
When to use it	Everything that operates in ALIDA: agents, services, notebooks, and your own tests	Only when you have authorized credentials for the development instance and need to bypass the platform

The ALIDA gateway is the recommended option: the call travels with your ALIDA identity, so access follows the roles and permissions already defined in the platform, and the URL stays valid for the instance you work on. For example, the gateway of the devng instance is https://alida.devng.alidalab.it/events/ollama/ollama-user.

Direct access to https://ollama.develop.alidalab.it talks to the Ollama server without passing through ALIDA. It is useful for debugging, but it requires separate credentials and grants no ALIDA-side control over the call.

Both expose the same two API families:

• Native Ollama APIs, under /api, for example /api/tags and /api/generate.
• OpenAI-compatible APIs, under /v1, for example /v1/models and /v1/chat/completions.

Calls to the models are standard HTTP endpoints, so the base URL chosen here is the same value you give to any component that must talk to the model: the model configuration of an ADK agent, an OpenAI-compatible client such as Open WebUI or LangChain, or a simple curl like the ones below. Clients that expect an OpenAI endpoint need the /v1 form of the URL and accept the ALIDA API key as their API key.

ALIDA gateway

WARNING

To create an API key for use with agents, you must have the ollama-user role in ALIDA. Contact an administrator to request access.

Set the variables

export ALIDA_URL='https://<alida-instance-url>'
export ALIDA_API_KEY='<api-key-generated-in-the-alida-ui>'

The procedure for creating the key is described in the API keys guide.

List the models

Before sending a request, retrieve the catalog and choose a value to use in place of <model>.

Native Ollama APIs

curl -sS \
  "${ALIDA_URL}/events/ollama/ollama-user/api/tags" \
  -H "Authorization: Apikey ${ALIDA_API_KEY}"

OpenAI-compatible APIs

curl -sS \
  "${ALIDA_URL}/events/ollama/ollama-user/v1/models" \
  -H "Authorization: Apikey ${ALIDA_API_KEY}"

Generate a first response

The "stream": false parameter returns a single JSON response, which is useful for an initial test.

Native Ollama APIs

curl -sS \
  "${ALIDA_URL}/events/ollama/ollama-user/api/generate" \
  -H "Authorization: Apikey ${ALIDA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<model>",
    "prompt": "Hello world",
    "stream": false
  }'

OpenAI-compatible APIs

curl -sS \
  "${ALIDA_URL}/events/ollama/ollama-user/v1/chat/completions" \
  -H "Authorization: Apikey ${ALIDA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<model>",
    "messages": [
      {"role": "user", "content": "Hello world"}
    ],
    "stream": false
  }'

Direct Ollama access

Use this mode only if you have authorized credentials for direct access to the development instance.

WARNING

An API key for the development instance cannot be generated automatically; contact an administrator to request it.

Set the variables

export OLLAMA_DEVELOP_URL='https://ollama.develop.alidalab.it'
export OLLAMA_DEVELOP_BASIC_AUTH='<base64-encoded-basic-credentials>'

List the models

Before sending a request, retrieve the catalog and choose a value to use in place of <model>.

Native Ollama APIs

curl -sS "${OLLAMA_DEVELOP_URL}/api/tags" \
  -H "Authorization: Basic ${OLLAMA_DEVELOP_BASIC_AUTH}"

OpenAI-compatible APIs

curl -sS "${OLLAMA_DEVELOP_URL}/v1/models" \
  -H "Authorization: Basic ${OLLAMA_DEVELOP_BASIC_AUTH}"

Generate a first response

Native Ollama APIs

curl -sS "${OLLAMA_DEVELOP_URL}/api/generate" \
  -H "Authorization: Basic ${OLLAMA_DEVELOP_BASIC_AUTH}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<model>",
    "prompt": "Hello world",
    "stream": false
  }'

OpenAI-compatible APIs

curl -sS "${OLLAMA_DEVELOP_URL}/v1/chat/completions" \
  -H "Authorization: Basic ${OLLAMA_DEVELOP_BASIC_AUTH}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<model>",
    "messages": [
      {"role": "user", "content": "Hello world"}
    ],
    "stream": false
  }'

After verifying the model, choose and prepare an OpenCode agent or an ADK agent. Configure chat only after the agent has been deployed and started.