Install & Compatibility
Where this runs
tested against v1.0.0b260521 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OllamaAdapter
✓ from agent_framework_ollama import OllamaAdapter
This quickstart demonstrates how to set up an `OllamaAdapter` and integrate it with an `Agent` from the `agent-framework`. It assumes an Ollama server is running locally (or at `OLLAMA_BASE_URL`) and the specified model (default: `llama3`) is available. The interaction flow is logged to the console via `pre_process_messages` and `post_process_messages` hooks, providing visibility into the agent's communication.
import asyncio
import os
from agent_framework.agent import Agent
from agent_framework.user import User
from agent_framework_ollama import OllamaAdapter
async def main():
# Pre-requisites:
# 1. Ollama server must be running (e.g., `ollama serve` in your terminal)
# 2. The desired model must be pulled (e.g., `ollama pull llama3`)
# Configure Ollama connection using environment variables or defaults
ollama_base_url = os.environ.get("OLLAMA_BASE_URL", "http://localhost:11434")
ollama_model = os.environ.get("OLLAMA_MODEL", "llama3")
if not ollama_model:
print("Error: OLLAMA_MODEL environment variable not set, or no default provided.")
print("Please specify an Ollama model, e.g., 'llama3'.")
return
print(f"Attempting to connect to Ollama at {ollama_base_url} with model: {ollama_model}")
try:
# Initialize the OllamaAdapter
ollama_adapter = OllamaAdapter(
model=ollama_model,
base_url=ollama_base_url,
)
# Create an Agent using the OllamaAdapter
agent = Agent(
name="OllamaAgent",
adapter=ollama_adapter,
# Optional: Add hooks to log messages as they are processed
pre_process_messages=lambda msgs: print(f"\n[OllamaAgent received]: {[m.content for m in msgs if m.content]}"),
post_process_messages=lambda msgs: print(f"[OllamaAgent sent]: {[m.content for m in msgs if m.content]}")
)
# Create a User to interact with the agent
user = User(
name="User",
connect_to=agent
)
print("\n--- Starting conversation with OllamaAgent ---")
await user.send("Hello, OllamaAgent! Please introduce yourself and tell me what you can do.")
# In a more complex application, you'd manage message history or await a specific response.
# For this quickstart, we observe the interaction via the print hooks.
print("\n--- Conversation complete ---")
except Exception as e:
print(f"\nAn error occurred during agent execution: {e}")
print("Please ensure your Ollama server is running, the model is pulled, and the base_url is correct.")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingAs a beta package, the API of agent-framework-ollama is subject to frequent changes without strict adherence to semantic versioning. Methods, classes, and configurations may be renamed, altered, or removed in minor or even patch versions.fixRegularly check the official GitHub repository's `README.md` and release notes for breaking changes upon upgrade. Pin your dependency versions to specific beta releases (e.g., `agent-framework-ollama==1.0.0b260409`) if stability is critical.
affects: All beta versions (1.0.0b*)
gotchaThe functionality of agent-framework-ollama relies on a running Ollama server instance and pre-downloaded models. Network connectivity issues, an incorrect `base_url`, or missing models are common causes of runtime errors.fixVerify that your Ollama server is active and accessible at the `base_url` configured (default: `http://localhost:11434`). Ensure the specified `model` (e.g., `llama3`) has been pulled using `ollama pull <model_name>` via the Ollama CLI.
affects: All versions
gotchaThis library is tightly coupled with `agent-framework`, which is also in beta. Incompatibility issues can arise if `agent-framework-ollama` and `agent-framework` are not compatible versions, especially if `agent-framework` itself introduces breaking changes or requires specific underlying dependencies.fixWhen upgrading, it's often best practice to upgrade both `agent-framework` and `agent-framework-ollama` simultaneously. Consult the `agent-framework` repository and release notes for any specific dependency requirements or version compatibility matrices.
affects: All beta versions
Upgrade
Version history
1.0.0b260521latest on PyPI · released May 22, 2026
Audit
Dependencies
agent-frameworkrequiredThis library provides an adapter for the core agent_framework. It is a mandatory dependency for creating and running agents that use Ollama.