Skip to main content
BB AI SDK: 0.1.9 (see Installation). Starter repo version: v0.1.12 (repository badge / pyproject.toml).
The starter agent (Level 0) is a production-ready template for building single-agent applications. Built on the Agno framework, it demonstrates core agent capabilities including instruction following, step-by-step reasoning, and tool execution.
This repository can be used as a base template for creating your own application. Select starter-agent as the repository_template when provisioning a new repository via Self Service.

GitHub repository

View source code, releases, and issues

​
Prerequisites

  • Python 3.12+: Managed via UV
  • UV Package Manager: Modern Python package manager (replaces pip/poetry)

​
Quick start

​
1. Clone and install UV

git clone https://github.com/bb-ecos-agbs/starter-agent.git
cd starter-agent

# Install UV (macOS)
brew install uv

# Install UV (Linux/WSL)
curl -LsSf https://astral.sh/uv/install.sh | sh

​
2. Set up environment

# Create virtual environment
uv venv --python 3.12
source .venv/bin/activate  # macOS/Linux
# Or .venv\scripts\activate # Windows

# Copy environment template
cp env.template .env

​
3. Configure credentials

Edit .env with required values: 
# Required - Artifactory credentials (for bb-ai-sdk)
export UV_INDEX_BACKBASE_USERNAME=your-email@backbase.com
export UV_INDEX_BACKBASE_PASSWORD=your-Artifactory-token

# AI gateway
AI_GATEWAY_ENDPOINT=
AI_GATEWAY_API_KEY=

# Observability - Langfuse
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=
LANGFUSE_HOST=

# Server config
HOST=0.0.0.0
PORT=8001
DEBUG=true

# Web proxy (required for local dev)
HTTP_PROXY=http://webproxy.infra.backbase.cloud:8888
HTTPS_PROXY=http://webproxy.infra.backbase.cloud:8888
NO_PROXY=localhost,127.0.0.1

​
4. Install dependencies and run

Load environment variables and sync dependencies: 
# Export env vars (Linux/macOS) to authenticate with Artifactory
source .env && uv sync

# Run the server
uv run python -m src.main
VPN and Web Proxy: Required for local development. Configure Aviatrix VPN and web proxy settings. See Onboarding Guide for setup instructions.

​
Available agents

The starter exposes three specialized agent endpoints:

Instructions agent

Follows precise system prompts. Endpoint: /run/instructions_agent

Reasoning agent

Uses Chain-of-Thought (CoT) reasoning. Endpoint: /run/reasoning_agent

Tools agent

Equipped with tools (e.g., Web Search). Endpoint: /run/tools_agent

​
API usage

curl -X POST "http://localhost:8001/run/instructions_agent" \
  -H "Content-Type: application/json" \
  -d '{"query": "Summarize AI in 3 points"}'

​
Project structure

starter-agent/
├── .github/                    # CI/CD workflows
├── promptfoo_config/           # Evaluation configurations
│   ├── instructions_agent_config.yaml
│   └── ...
├── prompts/                    # Centralized prompt definitions
├── providers/                  # AI provider configurations
├── src/
│   ├── main.py                 # App entry point & observability init
│   ├── agents/                 # Agent logic implementation
│   │   ├── instructions_agent.py
│   │   ├── reasoning_agent.py
│   │   └── tools_agent.py
│   └── api/                    # FastAPI routes and schemas
├── tests/                      # Unit tests
├── redteam.yaml                # Red teaming configuration
├── Dockerfile                  # Container definition
└── pyproject.toml              # Dependencies

​
Observability

Uses configure_observability(fastapi_app=app, framework="agno", ...) in the FastAPI app. Set LANGFUSE_* in .env; extras: bb-ai-sdk[instrument-fastapi,instrument-agno]==0.1.9.
BB AI SDK Observability — integration steps.

​
Evaluation and Red teaming

The starter includes configuration for Promptfoo, enabling systematic testing and red teaming of your agents.
  • Evaluations: Defined in promptfoo_config/*.yaml.
  • Red Teaming: Security and safety testing configured in redteam.yaml.

​
Development

​
Run tests

source .env && uv sync --extra dev
uv run python -m pytest tests/ -v

​
Build Docker image

docker build -t starter-agent:local .

​
CI/CD

Standard workflows are pre-configured in .github/workflows:
  • PR Checks: Linting, testing, and validation.
  • Build and Publish: Docker image creation on merge.
  • Release: Automated versioning and release notes.
See CI/CD workflows for pipeline details.

​
Next steps