ai-agent-deep-dive-teaching-framework

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ai-agent-deep-dive-teaching-framework

Skill by ara.so — AI Agent Skills collection.

Overview

概述

ai-agent-deep-dive

is a teaching-focused Python project that demonstrates how to build a minimal AI Agent from scratch. It includes:

A core Agent loop implementation
A swappable LLM interface (currently using a fake LLM for teaching)
A skill discovery and loading system
CLI interface for interaction
Educational documentation and reports on AI Agent architecture

The project is designed to keep complexity minimal while showing the essential components every AI Agent needs. It's ideal for learning agent architecture before building production systems.

ai-agent-deep-dive

是一个以教学为核心的Python项目，演示如何从零开始构建一个极简AI Agent。它包含：

核心Agent循环实现
可替换的LLM接口（当前为教学使用模拟LLM）
技能发现与加载系统
用于交互的CLI接口
关于AI Agent架构的教学文档与报告

本项目旨在将复杂度降至最低，同时展示每个AI Agent所需的核心组件。非常适合在构建生产系统前学习Agent架构。

Installation

安装

The project uses Poetry for dependency management.

bash

undefined

本项目使用Poetry进行依赖管理。

bash

undefined

Clone the repository

git clone https://github.com/tvytlx/ai-agent-deep-dive.git cd ai-agent-deep-dive

Install dependencies

poetry install

Verify installation

poetry run agt --help

undefined

poetry run agt --help

undefined

Core Architecture

核心架构

The teaching agent consists of three main components:

Agent Core (
```
src/agt/agent.py
```
) - Main loop and execution logic
CLI Interface (
```
src/agt/cli.py
```
) - Command-line entry point
Skills System - Pluggable capabilities loaded from a skills directory

教学Agent包含三个主要组件：

Agent核心 (
```
src/agt/agent.py
```
) - 主循环与执行逻辑
CLI接口 (
```
src/agt/cli.py
```
) - 命令行入口
技能系统 - 从技能目录加载的可插拔功能

CLI Commands

CLI命令

Basic Usage

基础用法

bash

undefined

bash

undefined

Run agent with a simple query

使用简单查询运行Agent

poetry run agt "hello world"

List available skills

列出可用技能

poetry run agt --skills-dir ./skills --list-skills

Specify custom skills directory

指定自定义技能目录

poetry run agt --skills-dir /path/to/skills "your query"

undefined

poetry run agt --skills-dir /path/to/skills "your query"

undefined

CLI Options

CLI选项

```
query
```
- The input query for the agent (positional argument)
```
--skills-dir
```
- Path to directory containing skill modules (default:
```
./skills
```
)
```
--list-skills
```
- Display all discovered skills and exit

```
query
```
- Agent的输入查询（位置参数）
```
--skills-dir
```
- 包含技能模块的目录路径（默认值：
```
./skills
```
）
```
--list-skills
```
- 显示所有已发现的技能并退出

Code Examples

代码示例

Basic Agent Usage

基础Agent用法

python

from agt.agent import Agent

python

from agt.agent import Agent

Initialize agent with default fake LLM

使用默认模拟LLM初始化Agent

agent = Agent()

Run agent with a query

运行Agent并传入查询

response = agent.run("What can you help me with?") print(response)

undefined

response = agent.run("What can you help me with?") print(response)

undefined

Understanding the Agent Loop

理解Agent循环

python

from agt.agent import Agent

python

from agt.agent import Agent

The agent loop follows this pattern:

Agent循环遵循以下模式:

1. Receive user input

1. 接收用户输入

2. Send to LLM (currently fake)

2. 发送至LLM（当前为模拟）

3. Stream response back

3. 流式返回响应

4. Execute any triggered skills

4. 执行触发的技能

agent = Agent(skills_dir="./skills") result = agent.run("Calculate 2+2")

undefined

agent = Agent(skills_dir="./skills") result = agent.run("Calculate 2+2")

undefined

Custom LLM Interface

自定义LLM接口

The project uses a fake LLM for teaching. To replace with a real LLM:

python

from agt.agent import Agent

class RealLLM:
    """Replace the fake LLM with real API calls"""
    
    def __init__(self, api_key=None):
        self.api_key = api_key or os.getenv("OPENAI_API_KEY")
    
    def stream_response(self, prompt: str):
        """Stream tokens from real LLM"""
        # Implementation would call actual API
        # and yield tokens as they arrive
        pass

本项目为教学使用模拟LLM。如需替换为真实LLM：

python

from agt.agent import Agent

class RealLLM:
    """Replace the fake LLM with real API calls"""
    
    def __init__(self, api_key=None):
        self.api_key = api_key or os.getenv("OPENAI_API_KEY")
    
    def stream_response(self, prompt: str):
        """Stream tokens from real LLM"""
        # 实现需调用真实API
        # 并在令牌到达时生成
        pass

Extend Agent class to use real LLM

扩展Agent类以使用真实LLM

class ProductionAgent(Agent): def init(self, **kwargs): super().init(**kwargs) self.llm = RealLLM()

undefined

class ProductionAgent(Agent): def init(self, **kwargs): super().init(**kwargs) self.llm = RealLLM()

undefined

Creating Custom Skills

创建自定义技能

Skills are Python modules placed in the skills directory:

python

undefined

技能是放置在技能目录中的Python模块：

python

undefined

skills/calculator.py

def add(a: int, b: int) -> int: """Add two numbers together""" return a + b

def multiply(a: int, b: int) -> int: """Multiply two numbers""" return a * b

def add(a: int, b: int) -> int: """Add two numbers together""" return a + b

def multiply(a: int, b: int) -> int: """Multiply two numbers""" return a * b

Skills metadata (optional)

技能元数据（可选）

SKILL_METADATA = { "name": "calculator", "description": "Basic arithmetic operations", "functions": ["add", "multiply"] }

undefined

SKILL_METADATA = { "name": "calculator", "description": "Basic arithmetic operations", "functions": ["add", "multiply"] }

undefined

Programmatic Agent Interaction

程序化Agent交互

python

from agt.agent import Agent
import os

python

from agt.agent import Agent
import os

Initialize with environment configuration

使用环境配置初始化

agent = Agent( skills_dir=os.getenv("AGENT_SKILLS_DIR", "./skills") )

Process multiple queries

处理多个查询

queries = [ "Hello, what can you do?", "Calculate something", "List your capabilities" ]

for query in queries: print(f"\nUser: {query}") response = agent.run(query) print(f"Agent: {response}")

undefined

queries = [ "Hello, what can you do?", "Calculate something", "List your capabilities" ]

for query in queries: print(f"\nUser: {query}") response = agent.run(query) print(f"Agent: {response}")

undefined

Configuration

配置

Environment Variables

环境变量

bash

undefined

bash

undefined

Example .env file

示例.env文件

AGENT_SKILLS_DIR=./skills OPENAI_API_KEY=your-api-key-here # For when you replace fake LLM LOG_LEVEL=INFO

undefined

AGENT_SKILLS_DIR=./skills OPENAI_API_KEY=your-api-key-here # 替换模拟LLM时使用 LOG_LEVEL=INFO

undefined

Agent Configuration

Agent配置

python

from agt.agent import Agent

agent = Agent(
    skills_dir="./custom_skills",  # Custom skills location
    verbose=True,                   # Enable detailed logging
    max_iterations=10               # Limit agent loop iterations
)

python

from agt.agent import Agent

agent = Agent(
    skills_dir="./custom_skills",  # 自定义技能位置
    verbose=True,                   # 启用详细日志
    max_iterations=10               # 限制Agent循环迭代次数
)

Project Structure

项目结构

ai-agent-deep-dive/
├── src/
│   └── agt/
│       ├── agent.py      # Core agent implementation
│       ├── cli.py        # CLI entry point
│       └── __init__.py
├── skills/               # Skill modules directory
├── docs/                 # Teaching documentation
├── pyproject.toml       # Poetry dependencies
└── README.md

ai-agent-deep-dive/
├── src/
│   └── agt/
│       ├── agent.py      # 核心Agent实现
│       ├── cli.py        # CLI入口
│       └── __init__.py
├── skills/               # 技能模块目录
├── docs/                 # 教学文档
├── pyproject.toml       # Poetry依赖配置
└── README.md

Common Patterns

常见模式

Pattern 1: Agent with Skill Discovery

模式1：带技能发现的Agent

python

from agt.agent import Agent
import os

python

from agt.agent import Agent
import os

Agent automatically discovers skills in directory

Agent自动发现目录中的技能

agent = Agent(skills_dir="./skills")

Skills are loaded and available during agent execution

技能已加载，可在Agent执行期间使用

response = agent.run("Use available skills to help me")

undefined

response = agent.run("Use available skills to help me")

undefined

Pattern 2: Streaming Response Handler

模式2：流式响应处理器

python

from agt.agent import Agent

agent = Agent()

python

from agt.agent import Agent

agent = Agent()

The fake LLM demonstrates streaming pattern

模拟LLM演示流式模式

Real implementation would stream from API

真实实现需从API流式获取

def handle_stream(query: str): for chunk in agent.stream_query(query): print(chunk, end="", flush=True) print() # Newline after stream completes

undefined

def handle_stream(query: str): for chunk in agent.stream_query(query): print(chunk, end="", flush=True) print() # 流结束后换行

undefined

Pattern 3: Extending the Agent

模式3：扩展Agent

python

from agt.agent import Agent

class CustomAgent(Agent):
    """Extended agent with custom behavior"""
    
    def pre_process(self, query: str) -> str:
        """Custom preprocessing"""
        return query.strip().lower()
    
    def post_process(self, response: str) -> str:
        """Custom postprocessing"""
        return response.upper()
    
    def run(self, query: str) -> str:
        query = self.pre_process(query)
        response = super().run(query)
        return self.post_process(response)

python

from agt.agent import Agent

class CustomAgent(Agent):
    """带自定义行为的扩展Agent"""
    
    def pre_process(self, query: str) -> str:
        """自定义预处理"""
        return query.strip().lower()
    
    def post_process(self, response: str) -> str:
        """自定义后处理"""
        return response.upper()
    
    def run(self, query: str) -> str:
        query = self.pre_process(query)
        response = super().run(query)
        return self.post_process(response)

Learning Resources

学习资源

The repository includes extensive documentation:

PDF Reports: Deep dive analysis of AI Agent architectures
- ```
ai-agent-deep-dive-v2.1.pdf
```
  - Includes memory systems chapter
- ```
ai-agent-deep-dive-v2.pdf
```
  - Core agent analysis
Teaching Docs:
```
/docs
```
directory with architectural explanations

本仓库包含丰富的文档：

PDF报告：AI Agent架构深度分析
- ```
ai-agent-deep-dive-v2.1.pdf
```
  - 包含内存系统章节
- ```
ai-agent-deep-dive-v2.pdf
```
  - 核心Agent分析
教学文档：
```
/docs
```
目录下的架构说明文档

Troubleshooting

故障排除

Skills Not Loading

技能未加载

python

undefined

python

undefined

Verify skills directory exists and has valid Python modules

验证技能目录存在且包含有效的Python模块

import os

skills_dir = "./skills" if not os.path.exists(skills_dir): os.makedirs(skills_dir)

import os

skills_dir = "./skills" if not os.path.exists(skills_dir): os.makedirs(skills_dir)

List skills to debug

列出技能以调试

from agt.cli import main

Run: poetry run agt --list-skills

运行：poetry run agt --list-skills

undefined

undefined

Import Errors

导入错误

bash

undefined

bash

undefined

Ensure you're in the project directory

确保处于项目目录

cd ai-agent-deep-dive

Reinstall dependencies

重新安装依赖

poetry install

Verify installation

验证安装

poetry run python -c "from agt.agent import Agent; print('OK')"

undefined

poetry run python -c "from agt.agent import Agent; print('OK')"

undefined

Poetry Not Found

未找到Poetry

bash

undefined

bash

undefined

Install poetry

安装Poetry

curl -sSL https://install.python-poetry.org | python3 -

Or via pip

或通过pip安装

pip install poetry

Verify

验证

poetry --version

undefined

poetry --version

undefined

Next Steps

下一步

This teaching framework uses a fake LLM to demonstrate structure. To build a production agent:

Replace the fake LLM with real API calls (OpenAI, Anthropic, etc.)
Implement proper error handling and retries
Add memory/context management
Enhance skill execution with function calling
Add logging and monitoring

Example Real LLM Integration:

python

import os
from openai import OpenAI

class OpenAILLM:
    def __init__(self):
        self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
    
    def stream_response(self, prompt: str):
        stream = self.client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": prompt}],
            stream=True
        )
        for chunk in stream:
            if chunk.choices[0].delta.content:
                yield chunk.choices[0].delta.content

This teaching project provides the architectural foundation — real integrations follow the same patterns but with production-grade implementations.

本教学框架使用模拟LLM来演示结构。如需构建生产级Agent：

将模拟LLM替换为真实API调用（OpenAI、Anthropic等）
实现完善的错误处理与重试机制
添加内存/上下文管理
通过函数调用增强技能执行
添加日志与监控

真实LLM集成示例：

python

import os
from openai import OpenAI

class OpenAILLM:
    def __init__(self):
        self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
    
    def stream_response(self, prompt: str):
        stream = self.client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": prompt}],
            stream=True
        )
        for chunk in stream:
            if chunk.choices[0].delta.content:
                yield chunk.choices[0].delta.content

本教学项目提供了架构基础——真实集成遵循相同模式，但需采用生产级实现。