Baicha

Learn agent engineering through a real Python project.

Baicha is an open-source Python project for studying how real agent systems are structured. It is meant to be a learning repo for people who want to move beyond simple LLM demos and understand the engineering behind agent loops, tools, context, and runtime behavior.

Who It Is For

This repo is for:

• students preparing for software, AI, or agent-related roles,
• early-career engineers who want a more serious portfolio project,
• builders who want to understand how real agent systems are structured,
• learners who want a codebase they can study, modify, and later discuss in interviews.

Why It Is Worth Studying

Many AI tutorials focus on prompts or thin wrappers around model APIs. Baicha is meant to be more useful than that: a real codebase you can read to understand how agent systems are assembled.

It is also the kind of project that can help you build a stronger project story. If you want to talk clearly about architecture, trade-offs, and how agent systems work, studying a repo like this is more valuable than only showing prompt usage.

What You Will Learn

By studying Baicha, you can learn how to:

• understand the shape of an agent loop,
• trace how tools, runtime state, and context fit together,
• see how skills, approvals, and interaction layers affect agent behavior,
• study an agent codebase like an engineer,
• turn technical learning into a stronger project story.

How Baicha Is Structured

Baicha is evolving as an ecosystem with:

• a shared foundation layer for core agent abstractions,
• runtime capabilities such as agent loops, tool execution, and context management,
• shared capabilities such as skills, approvals, configuration, and task tracking,
• product-oriented layers that can later specialize into different agent experiences.

This matters because modern agent systems are composed systems, not just single model calls.

How to Run It

Baicha currently targets Python 3.13 or newer.

Before running the project, create a local .env file in the repository root and add your own provider credentials. The CLI loads environment variables from .env, and the default OpenAI-compatible provider expects at least OPENAI_API_KEY.

Example:

OPENAI_API_KEY=your_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

Do not commit your .env file.

Basic setup:

uv sync
python cli/main.py

Follow the Project

If you want to learn from a real agent project, build from it, or use it as inspiration for your own portfolio work, follow the repository as it evolves.