---
url: /agentic-ai/getting-started.md
---
# 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.

::: warning Agents must be deployed in a workflow
ALIDA ships two agents: the [OpenCode agent](opencode-agent.md) and the [ADK agent](adk-agent.md). 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](configure-agent.md).
:::

## 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](adk-agent.md), 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

```bash
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](../api-keys.md) guide.

### List the models

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

::: code-group

```bash [Native Ollama APIs]
curl -sS \
  "${ALIDA_URL}/events/ollama/ollama-user/api/tags" \
  -H "Authorization: Apikey ${ALIDA_API_KEY}"
```

```bash [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.

::: code-group

```bash [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
  }'
```

```bash [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

```bash
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>`.

::: code-group

```bash [Native Ollama APIs]
curl -sS "${OLLAMA_DEVELOP_URL}/api/tags" \
  -H "Authorization: Basic ${OLLAMA_DEVELOP_BASIC_AUTH}"
```

```bash [OpenAI-compatible APIs]
curl -sS "${OLLAMA_DEVELOP_URL}/v1/models" \
  -H "Authorization: Basic ${OLLAMA_DEVELOP_BASIC_AUTH}"
```

:::

### Generate a first response

::: code-group

```bash [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
  }'
```

```bash [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](opencode-agent.md) or an [ADK agent](adk-agent.md). Configure chat only after the agent has been deployed and started.