> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ollama

> Run local models and call Ollama Cloud directly from Agno agents.

Run large language models with [Ollama](https://ollama.com) through a local Ollama server or the direct Ollama Cloud API.

| Access mode | Host | Authentication | Example model ID |
| - | - | - | - |
| Local Ollama server | `http://localhost:11434` | None | `llama3.1` |
| Direct Ollama Cloud API | `https://ollama.com` | `OLLAMA_API_KEY` | `gpt-oss:120b` |

Ollama also supports cloud-offloaded models through a signed-in local Ollama server. That access mode uses model IDs such as `gpt-oss:120b-cloud`. See the [Ollama Cloud guide](https://docs.ollama.com/cloud).

Ollama supports multiple open-source models. See the [Ollama library](https://ollama.com/library).

Experiment with different models to find the best fit for your use case. Here are some general recommendations:

* `gpt-oss:120b` is a general-purpose model available through the direct Ollama Cloud API.
* `llama3.3` models are good for most basic use cases.
* `qwen` models perform particularly well with tool use.
* `deepseek-r1` models have strong reasoning capabilities.
* `phi4` models offer strong performance at a small size.

## Direct Ollama Cloud API authentication

To call Ollama Cloud directly, set your `OLLAMA_API_KEY` environment variable. Create a key from [Ollama](https://ollama.com/settings/keys).

```bash Mac theme={null}
export OLLAMA_API_KEY=***
```

```bash Windows theme={null}
setx OLLAMA_API_KEY ***
```

When `OLLAMA_API_KEY` is set, Agno adds bearer authorization and defaults the host to `https://ollama.com`. Local requests use the Ollama server configured by the client.

## Set up a model

Both local and direct cloud usage require the `ollama` Python package:

```bash theme={null}
uv pip install -U ollama agno
```

### Local Usage

Install the [Ollama app](https://ollama.com) and run a model:

```bash run model theme={null}
ollama run llama3.1
```

This starts an interactive session with the model.

To download the model for use in an Agno agent:

```bash pull model theme={null}
ollama pull llama3.1
```

### Direct Ollama Cloud API

Set `OLLAMA_API_KEY` to access models through `https://ollama.com`. This direct API path runs without a local Ollama server.

## Examples

### Local Usage

Once the model is available locally, use the `Ollama` model class to access it:

```python agent.py theme={null}
from agno.agent import Agent
from agno.models.ollama import Ollama

agent = Agent(
    model=Ollama(id="llama3.1"),
    markdown=True
)

# Print the response in the terminal
agent.print_response("Share a 2 sentence horror story.")
```

### Direct Ollama Cloud API

> [!NOTE]
>
> When `OLLAMA_API_KEY` is set, the host defaults to `https://ollama.com`. You can omit the `host` parameter.

```python agent.py theme={null}
from agno.agent import Agent
from agno.models.ollama import Ollama

agent = Agent(
    model=Ollama(id="gpt-oss:120b"),
    markdown=True
)

# Print the response in the terminal
agent.print_response("Share a 2 sentence horror story.")
```

> [!NOTE]
>
> See [Ollama usage examples](https://agno-v2.mintlify.site/models/providers/local/ollama/usage/basic.md) for more.

## Params

| Parameter | Type | Default | Description |
| - | - | - | - |
| `id` | `str` | `"llama3.1"` | The name of the Ollama model to use |
| `name` | `str` | `"Ollama"` | The name of the model |
| `provider` | `str` | `"Ollama"` | The provider of the model |
| `format` | `Optional[Any]` | `None` | The format to return the response in (e.g., "json") |
| `options` | `Optional[Any]` | `None` | Additional model options (temperature, top\_p, etc.) |
| `keep_alive` | `Optional[Union[float, str]]` | `None` | How long to keep the model loaded (e.g., "5m", 3600 seconds) |
| `request_params` | `Optional[Dict[str, Any]]` | `None` | Additional parameters to include in the request |
| `host` | `Optional[str]` | `None` (`"http://localhost:11434"`; `"https://ollama.com"` when `api_key` is set) | The host URL for the Ollama server |
| `timeout` | `Optional[Any]` | `None` | Request timeout in seconds |
| `api_key` | `Optional[str]` | `getenv("OLLAMA_API_KEY")` | API key for Ollama Cloud. When set, the host defaults to Ollama Cloud |
| `client_params` | `Optional[Dict[str, Any]]` | `None` | Additional parameters for client configuration |
| `client` | `Optional[OllamaClient]` | `None` | Pre-configured Ollama client |
| `async_client` | `Optional[AsyncOllamaClient]` | `None` | Pre-configured async Ollama client |

`Ollama` is a subclass of the [Model](https://agno-v2.mintlify.site/reference/models/model.md) class and has access to the same params.

## Responses API

Ollama v0.13.3+ supports the OpenAI Responses API via the `/v1/responses` endpoint. Use `OllamaResponses` for this interface. It uses the OpenAI client, so install the `openai` package:

```bash theme={null}
uv pip install -U openai agno
```

```python agent.py theme={null}
from agno.agent import Agent
from agno.models.ollama import OllamaResponses

agent = Agent(
    model=OllamaResponses(id="gpt-oss:20b"),
    markdown=True,
)

agent.print_response("Share a 2 sentence horror story")
```

The Responses API is stateless. Each request is independent with no `previous_response_id` chaining.

See [OllamaResponses reference](https://agno-v2.mintlify.site/reference/models/ollama-responses.md) for full parameters.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.