Agent from Scratch

A comprehensive collection of patterns, building blocks, and workflows for building AI agents from the ground up using Python. This repository serves as a practical guide to understanding and implementing core agentic design patterns.

Key Features

• Building Blocks: Core components including basic prompting, tool integration, knowledge retrieval (RAG), and structured outputs.
• Agentic Workflows: Implementation of common agent patterns:
  • Prompt Chaining: Sequential execution of LLM calls.
  • Routing: Dynamic decision-making to direct queries to specific handlers.
  • Parallelization: Running multiple LLM tasks concurrently for efficiency.
  • Orchestration: Managing complex tasks through a central controller.
• Example Agents: End-to-end examples like a web search agent.

Repository Structure

.
├── agents/             # End-to-end agent implementations
│   └── web-search-agent.py
├── building-blocks/    # Fundamental agent components
│   ├── tools.py        # Tool definition and execution
│   ├── retrieval.py    # Knowledge base integration
│   └── structured.py   # Schema-based outputs
├── workflows/          # High-level agentic patterns
│   ├── 1-prompt-chaining.py
│   ├── 2-routing.py
│   ├── 3-parallization.py
│   └── 4-orchestrator.py
├── .env.example        # Example local environment configuration
└── pyproject.toml      # Project metadata and dependencies

🛠️ Getting Started

Prerequisites

• Python 3.10+
• An API endpoint for either OpenAI or cliproxyapi

Installation

1. Clone the repository:

   git clone <repository-url>
   cd agent-from-scratch

2. Install dependencies with uv:

   uv sync

3. Configure your environment variables: Copy the example file and fill in the values you want to use locally:

   cp .env.example .env

   For direct OpenAI access:

   OPENAI_API_KEY=your_key_here
   OPENAI_MODEL=gpt-5-nano
   WEATHER_API_KEY=your_key_here

   Or, to route requests through cliproxyapi by default:

   CLIPROXYAPI_BASE_URL=http://127.0.0.1:8317/v1
   CLIPROXYAPI_API_KEY=your_key_here
   CLIPROXYAPI_MODEL=claude-sonnet-4-6

Provider Selection

• If CLIPROXYAPI_BASE_URL is set, the LLM examples use cliproxyapi by default.
• If CLIPROXYAPI_BASE_URL is not set, the examples fall back to OPENAI_API_KEY.
• WEATHER_API_KEY is only needed for the weather demos.

Usage

Each file in the workflows/ or building-blocks/ directory is a standalone example. You can run them directly:

uv run python workflows/1-prompt-chaining.py

You can also run the LangChain example from the repo root:

uv run python agents/basic-agent.py

Publishing Notes

• Keep .env uncommitted. It is ignored by Git so local secrets stay local.
• Commit .env.example, pyproject.toml, and uv.lock so others can install and run the project consistently.