> ## Documentation Index
> Fetch the complete documentation index at: https://grandcentral.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Starter agent

> Level 0 - Basic agent with instructions, reasoning, and tools

<Info>
  **BB AI SDK:** `0.1.9` (see [Installation](/agentic-ai/bb-ai-sdk/installation)). **Starter repo version:** v0.1.12 (repository badge / `pyproject.toml`).
</Info>

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.

<Tip>
  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](/agentic-ai/getting-started/self-service)**.
</Tip>

<Card title="GitHub repository" icon="github" href="https://github.com/bb-ecos-agbs/starter-agent">
  View source code, releases, and issues
</Card>

## Prerequisites

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

## Quick start

### 1. Clone and install UV

```bash theme={"system"}
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

```bash theme={"system"}
# 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:

```ini theme={"system"}
# 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:

```bash theme={"system"}
# Export env vars (Linux/macOS) to authenticate with Artifactory
source .env && uv sync

# Run the server
uv run python -m src.main
```

<Warning>
  **VPN and Web Proxy**: Required for local development. Configure Aviatrix VPN and web proxy settings. See **[Onboarding Guide](/agentic-ai/getting-started/onboarding)** for setup instructions.
</Warning>

## Available agents

The starter exposes three specialized agent endpoints:

<CardGroup cols={3}>
  <Card title="Instructions agent" icon="list-check">
    Follows precise system prompts.
    Endpoint: `/run/instructions_agent`
  </Card>

  <Card title="Reasoning agent" icon="brain">
    Uses Chain-of-Thought (CoT) reasoning.
    Endpoint: `/run/reasoning_agent`
  </Card>

  <Card title="Tools agent" icon="wrench">
    Equipped with tools (e.g., Web Search).
    Endpoint: `/run/tools_agent`
  </Card>
</CardGroup>

## API usage

<CodeGroup>
  ```bash Instructions theme={"system"}
  curl -X POST "http://localhost:8001/run/instructions_agent" \
    -H "Content-Type: application/json" \
    -d '{"query": "Summarize AI in 3 points"}'
  ```

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

  ```bash Tools theme={"system"}
  curl -X POST "http://localhost:8001/run/tools_agent" \
    -H "Content-Type: application/json" \
    -d '{"query": "What is happening in tech today?"}'
  ```
</CodeGroup>

## Project structure

```text theme={"system"}
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`.

<Info>
  **[BB AI SDK Observability](/agentic-ai/bb-ai-sdk/observability#set-up-the-sdk)** — integration steps.
</Info>

## 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

```bash theme={"system"}
source .env && uv sync --extra dev
uv run python -m pytest tests/ -v
```

### Build Docker image

```bash theme={"system"}
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.

<Info>
  See **[CI/CD workflows](/agentic-ai/ci-cd-workflows/overview)** for pipeline details.
</Info>

## Next steps

* **[Create Your First Agent](/agentic-ai/getting-started/creating-first-agent)**: Deploy to a runtime
* **[Multi-Agent Starter](/agentic-ai/starter-kits/multi-agent)**: Upgrade to agent teams
* **[MCP Agent](/agentic-ai/starter-kits/mcp-starters)**: Integrate with MCP servers
* **[Knowledge Agent](/agentic-ai/starter-kits/knowledge-agent)**: Add RAG capabilities