Skip to main content
Current Version: v0.1.12
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. Setup 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)
UV_INDEX_BACKBASE_USERNAME[email protected]
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
export $(cat .env | grep -v '^#' | xargs) && 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

The starter automatically integrates with Langfuse via the bb-ai-sdk.
  • Automatic Tracing: Captures full traces for agent runs and LLM calls.
  • OpenAI Instrumentation: Automatically instruments Agno’s OpenAI calls.
  • Configuration: Managed via LANGFUSE_* environment variables.
This starter is integrated with bb-ai-sdk to connect with observability tools (Langfuse) and AI Gateway. See BB AI SDK Observability for advanced configuration and custom tracing.

​
Evaluation & 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

export $(cat .env | grep -v '^#' | xargs) && 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 & Publish: Docker image creation on merge.
  • Release: Automated versioning and release notes.
See CI/CD Workflows for pipeline details.

​
Next Steps