Starter agent

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"}'

curl -X POST "http://localhost:8001/run/reasoning_agent" \
  -H "Content-Type: application/json" \
  -d '{"query": "Explain why caching improves performance"}'

curl -X POST "http://localhost:8001/run/tools_agent" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is happening in tech today?"}'

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

Create Your First Agent: Deploy to a runtime
Multi-Agent Starter: Upgrade to agent teams
MCP Agent: Integrate with MCP servers
Knowledge Agent: Add RAG capabilities

Overview

Architecture and technology

Agent Development Lifecycle

Get started

Starter kits

BB AI SDK

MCP support

CI/CD workflows

GitHub repository

Prerequisites

Quick start

1. Clone and install UV

2. Set up environment

3. Configure credentials

4. Install dependencies and run

Available agents

Instructions agent

Reasoning agent

Tools agent

API usage

Project structure

Observability

Evaluation and Red teaming

Development

Run tests

Build Docker image

CI/CD

Next steps

GitHub repository

​Prerequisites

​Quick start

​1. Clone and install UV

​2. Set up environment

​3. Configure credentials

​4. Install dependencies and run

​Available agents

Instructions agent

Reasoning agent

Tools agent

​API usage

​Project structure

​Observability

​Evaluation and Red teaming

​Development

​Run tests

​Build Docker image

​CI/CD

​Next steps

Prerequisites

Quick start

1. Clone and install UV

2. Set up environment

3. Configure credentials

4. Install dependencies and run

Available agents

API usage

Project structure

Observability

Evaluation and Red teaming

Development

Run tests

Build Docker image

CI/CD

Next steps