Provider Setup

Provider Setup Guide

Essential Multiple Options

AgentForce ADK supports multiple AI providers, giving you flexibility to choose between local and cloud-based models based on your needs.

Available Providers

Ollama

Local Free Privacy

Best for:

• Development and testing
• Privacy-sensitive applications
• Offline environments
• Cost-effective solutions

OpenRouter

Cloud Multiple Providers API Key Required

Best for:

• Production applications
• Access to latest models
• Scalable solutions
• Multiple model providers

Note

Coming Soon: Native OpenAI, Anthropic, and Google provider support. Currently available through OpenRouter.

Ollama Setup (Local Models)

Ollama allows you to run large language models locally on your machine.

Installation

macOS - Homebrew

# Install Ollama using Homebrew
brew install ollama

# Start Ollama service
brew services start ollama

# Verify installation
ollama --version

macOS/Linux

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama service
ollama serve

# Verify installation
ollama --version

Windows

# Download and install from https://ollama.ai/download
# Or use Windows Subsystem for Linux (WSL)
wsl curl -fsSL https://ollama.ai/install.sh | sh

Docker

# Run Ollama in Docker
docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

# Pull a model
docker exec -it ollama ollama pull gemma3:12b

Recommended Models

Pull models based on your hardware and use case:

Lightweight (4-8GB RAM)

# Fast and efficient models
ollama run phi4-mini-reasoning    # 3.8B params, great small thinking model
ollama run gemma3:4b              # 4B params, balanced performance
ollama run llama3.2:3b            # 3B params, Meta's model

Balanced (8-16GB RAM)

# Good performance and capability
ollama run gemma3:12b             # 12B params, recommended
ollama run gpt-oss:20b            # 20B params, 14GB, versatile
ollama run phi4:latest            # Microsoft's latest model

High-End (16GB+ RAM)

# Maximum capability
ollama run gpt-oss:120b           # 65GB open-source model from OpenAI
ollama run qwen3:32b              # Mixture of experts model
ollama run qwen3-coder:30b        # Specialized for code generation

Verify Ollama Setup

Test your Ollama installation:

# Check if Ollama is running
ollama list

# Test a model
ollama run gemma3:12b "Hello, how are you?"

# Check Ollama API
curl http://localhost:11434/api/tags

Using Ollama in AgentForce ADK

import { AgentForceAgent } from '@agentforce/adk';

const agent = new AgentForceAgent({ name: "LocalAgent" })
  .useLLM("ollama", "gemma3:12b")  // provider: "ollama", model: "gemma3:12b"
  .systemPrompt("You are a helpful assistant running locally")
  .prompt("What are the benefits of local AI models?");

const response = await agent.output("text");
console.log(response);

OpenRouter Setup (Cloud Models)

OpenRouter provides access to multiple AI providers through a single API.

Get API Key

1. Visit OpenRouter.ai
2. Sign up for a free account
3. Navigate to API Keys
4. Create a new API key

Configure API Key

Environment Variable

# Add to your shell profile (.bashrc, .zshrc, etc.)
export OPENROUTER_API_KEY="sk-or-v1-your-api-key-here"

# Or add to .env file
echo "OPENROUTER_API_KEY=sk-or-v1-your-api-key-here" >> .env

Runtime Configuration

// Set at runtime (not recommended for production)
process.env.OPENROUTER_API_KEY = "sk-or-v1-your-api-key-here";

import { AgentForceAgent } from '@agentforce/adk';
// ... rest of your code

Available Models

OpenRouter provides access to models from multiple providers:

🔥 Free Models

// Great for development and testing
.useLLM("openrouter", "moonshotai/kimi-k2:free")
.useLLM("openrouter", "openai/gpt-oss-20b:free")
.useLLM("openrouter", "z-ai/glm-4.5-air:free")

🚀 OpenAI Models

// OpenAI's latest models
.useLLM("openrouter", "openai/gpt-5-chat")
.useLLM("openrouter", "openai/gpt-5-mini")
.useLLM("openrouter", "openai/o3")

🧠 Anthropic Models

// Claude models
.useLLM("openrouter", "anthropic/claude-opus-4.1")
.useLLM("openrouter", "anthropic/claude-opus-4")
.useLLM("openrouter", "anthropic/claude-sonnet-4")

🦙 Meta Models

// Llama models
.useLLM("openrouter", "meta-llama/llama-4-maverick")
.useLLM("openrouter", "meta-llama/llama-4-scout")
.useLLM("openrouter", "meta-llama/llama-3.3-70b-instruct")

Using OpenRouter in AgentForce ADK

import { AgentForceAgent } from '@agentforce/adk';

const agent = new AgentForceAgent({ name: "CloudAgent" })
  .useLLM("openrouter", "z-ai/glm-4.5v")  // provider: "openrouter", model: "z-ai/glm-4.5v"
  .systemPrompt("You are a cloud-powered AI assistant")
  .prompt("What are the advantages of cloud-based AI models?");

const response = await agent.output("text");
console.log(response);

Cost Management

Monitor your OpenRouter usage:

1. Check your OpenRouter Settings
2. Set up budget alerts
3. Use free models for development
4. Consider model costs for production

Tip

Pro Tip: Start with free models during development, then upgrade to premium models for production use.

Provider Comparison

Feature	Ollama (Local)	OpenRouter (Cloud)
Cost	Free	Pay-per-use
Privacy	Complete	Provider-dependent
Latency	Low (local)	Network-dependent
Models	Limited selection	100+ models
Setup	Installation required	API key only
Offline	✅ Yes	❌ No
Scalability	Hardware-limited	Unlimited

Troubleshooting

Ollama Issues

Ollama not starting:

# Check if Ollama is running
ps aux | grep ollama

# Start Ollama manually
ollama serve

# Check logs
ollama logs

Model not found:

# List available models
ollama list

# Pull missing model
ollama pull gemma3:12b

# Check model info
ollama show gemma3:12b

Connection refused:

# Check if Ollama API is accessible
curl http://localhost:11434/api/tags

# Restart Ollama service
brew services restart ollama  # macOS
sudo systemctl restart ollama  # Linux

OpenRouter Issues

API key not working:

• Verify key at OpenRouter Keys
• Check environment variable: echo $OPENROUTER_API_KEY
• Ensure key starts with sk-or-v1-

Rate limiting:

• Check your usage at OpenRouter Activity
• Consider upgrading your plan
• Use free models for development

Model not available:

• Check OpenRouter Models for availability
• Some models require approval or higher tier plans

Next Steps

Now that AgentForce ADK is installed, you’ll need to set up AI providers to power your agents:

1. Quick Start - Create your first agent
2. Server Mode - Run agents in server mode as endpoints
3. Basic Agents Guide - Learn agent fundamentals

Great! You now have AI providers configured and ready to power your AgentForce ADK agents. Choose Ollama for local development and privacy, or OpenRouter for access to the latest cloud models.