Setup Guide

Setup Guide

Get Rover Agent Python running in minutes.

Prerequisites

Install these tools before starting:

• Python 3.11 or later: Check your version with python --version
• uv package manager: Fast Python package installer (install guide)

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify installation:

uv --version

Installation

Clone and set up the project:

# 1. Clone the repository
git clone <repository-url>
cd consumer-agent

# 2. Install dependencies
uv sync

# 3. Install development tools (optional)
uv sync --dev

# 4. Activate the virtual environment
source .venv/bin/activate

The uv sync command creates a virtual environment in .venv/ and installs all dependencies from pyproject.toml.

Environment Variables Configuration

Create a .env file in the project root. This file stores API keys and configuration.

Copy the example file:

cp .env.example .env

Edit .env with your credentials:

# OpenAI Configuration (Required)
OPENAI_API_KEY=sk-your-openai-api-key-here

# Rover MCP Configuration (Optional - only if using MCP tools)
ROVER_MCP_AUTHORIZATION=your-mcp-auth-token-here
# ROVER_MCP_SERVER_URL=http://localhost:8000/mcp  # Override default from settings.yaml

# History Configuration (Optional - for local DynamoDB/S3 testing)
# HISTORY_TABLE_NAME=local-consumer-agent-history
# HISTORY_S3_BUCKET=local-bucket

Environment Variables Loaded into Configuration:

These environment variables are automatically loaded into Dynaconf configuration groups:

Variable	Loaded Into	Description
OPENAI_API_KEY	agent_config.openai.api_key	OpenAI API authentication
ROVER_MCP_AUTHORIZATION	settings.rover_mcp.authorization	Rover MCP tool server auth token
ROVER_MCP_SERVER_URL	settings.rover_mcp.server_url	Rover MCP server endpoint
HISTORY_TABLE_NAME	settings.history.table_name	DynamoDB table name
HISTORY_S3_BUCKET	settings.history.s3_bucket	S3 bucket name

Get Your OpenAI API Key

1. Go to platform.openai.com/api-keys
2. Click “Create new secret key”
3. Copy the key (starts with sk-)
4. Add to .env:

   OPENAI_API_KEY=sk-your-key-here

Get MCP Authorization Token (Optional)

MCP enables the agent to use external tools. Skip this if you don’t need tool execution.

# 1. Login to AWS SSO
aws sso login --profile stage-services-admin

# 2. Retrieve token from Secrets Manager
aws secretsmanager get-secret-value \
  --secret-id rover-mcp/auth-tokens \
  --profile stage-services-admin \
  --query SecretString \
  --output text

Add the token to .env:

ROVER_MCP_AUTHORIZATION=your-token-here

Configuration

Edit agent_config.yaml to customize the agent.

Default configuration:

openai:
  model: gpt-5-mini
  base_url: https://api.openai.com/v1
  max_output_tokens: 2000
  reasoning_effort: low
  text_verbosity: low
  timeout: 90
  use_responses_api: true

rover_mcp:
  server_url: https://stage-partners-gateway.fetchrewards.com/rover-mcp
  timeout: 90.0

Model Parameters

GPT-5 series models use reasoning parameters:

• reasoning_effort: low, medium, high (controls reasoning depth)
• text_verbosity: low, high (controls response length)
• max_output_tokens: Token limit (default: 2000)

Do not use temperature, top_p, or frequency_penalty with reasoning models. The config system rejects these parameters.

MCP Configuration

MCP is optional. Remove the rover_mcp: section if you don’t need external tools.

Required when using MCP:

• server_url: Rover MCP server endpoint
• timeout: Request timeout in seconds
• ROVER_MCP_AUTHORIZATION in .env

Evaluation Configuration

The evaluation section in agent_config.yaml provides user context for evaluation runs, ensuring parity with API and CLI behavior:

• user_id: User ID for MCP tool calls during evaluation
• latitude/longitude: Location context for offers
• locale: Language preference (en, es-419)
• enabled_components: Which prompt components to enable (null = all)

See agent_config.yaml for current configuration.

Verify Installation

Test the setup:

# 1. Check CLI is installed
consumer-agent --help

# 2. Verify environment variables
python -c "from consumer_agent.config import agent_config; print('Config loaded')"

# 3. Run tests
pytest

Expected output:

consumer-agent --help
Usage: consumer-agent [OPTIONS] COMMAND [ARGS]...

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  chat  Start interactive chat with Rover agent

Run the Agent

Option 1: TUI Chatbot (Terminal UI)

Interactive chat interface:

consumer-agent chat

Features:

• Real-time streaming responses
• Conversation history
• Command shortcuts

Option 2: FastAPI Server

Run as a web service:

uvicorn consumer_agent.api.main:app --reload --port 8000

Test the API:

curl -X POST http://localhost:8000/agent/stream \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello"}],
    "agent_id": "conversational",
    "enabled_components": []
  }'

API endpoints:

• GET /health - Health check
• POST /agent/stream - Streaming chat responses

Troubleshooting

Error: OPENAI_API_KEY environment variable is required

The .env file is missing or the API key is not set.

Fix:

# Check if .env exists
ls -la .env

# If missing, create it
cp .env.example .env
# Edit .env and add your OpenAI API key

Error: openai.use_responses_api missing in agent_config.yaml

The configuration file is outdated.

Fix:

# Add to agent_config.yaml under openai:
use_responses_api: true

Error: ModuleNotFoundError: No module named 'consumer_agent'

Virtual environment is not activated or dependencies are not installed.

Fix:

# Install dependencies
uv sync

# Activate virtual environment
source .venv/bin/activate

Error: MCP connection timeout

The MCP server is unreachable or the auth token is invalid.

Check:

1. Verify ROVER_MCP_AUTHORIZATION in .env
2. Test server connection: curl -H "Authorization: Bearer $ROVER_MCP_AUTHORIZATION" <server_url>/health
3. Increase timeout in settings.yaml: rover_mcp.timeout: 120

Tests fail with missing OPENAI_API_KEY

The test environment is missing the OpenAI API key.

Fix - add to .env:

OPENAI_API_KEY=test-key-for-unit-tests

Or set environment variable directly:

export OPENAI_API_KEY=test-key-for-unit-tests

Next Steps

• Read Architecture Guide to understand how the agent works
• See Development Guide for contributing and testing
• Check API Documentation for endpoint details
• Learn about Responses API for reasoning access