Реализация AI-агента на Python
Прежде чем погружаться в код, давайте четко определимся: думайте об ИИ-агенте как оинтеллектуальной программе с мозгом, руками и ногами。
- Мозг (ядро): a, который может понимать, рассуждать и принимать решения, — этомодель (например, большая языковая модель LLM). Он отвечает за обработку информации и составление планов.
- Восприятие (ввод): Агент получает внешнюю информацию через органы чувств, например пользовательские инструкции, результаты запросов к базе данных, веб-контент, данные сенсоров и т. д.
- Действие (вывод): Агент воздействует на внешний мир через руки и ноги, например вызывая функцию, отправляя электронное письмо, выводя текст на экран, управляя роботизированной рукой и т. д.
- Цель: Все поведение Агента вращается вокруг четкойцели, которая разворачивается, например: помоги мне узнать завтрашнюю погоду в Пекине.
Его основной рабочий процесс — это классическийцикл «Восприятие—Мышление—Действие», как показано на рисунке ниже:

Простой тест-кейс
agent-demo/ agent.py # 主实现(下面给出) tools.py # 工具实现(可单独文件) memory.py # 简单记忆实现(可单独文件) README.md
Пример
agent.py — минимальный прототип ИИ-агента (можно запустить напрямую)
Пояснение:
- Часть LLM имитируется очень простым «ответчиком на основе правил»; при реальном подключении к LLM замените LLMInterface.generate(...)
- Компоненты: абстракция LLM, мозг (разбор/принятие решений), планировщик, реестр инструментов, память, исполнитель
"""
from typing import Any, Dict, List, Callable
import time
# -----------------------------
# Память (очень лёгкая)
# -----------------------------
class Memory:
def __init__(self):
self.short = {} # Текущий контекст разговора
self.long = {} # Долгосрочные предпочтения/контакты и т. д.
def get_short(self, k, default=None):
return self.short.get(k, default)
def set_short(self, k, v):
self.short[k] = v
def get_long(self, k, default=None):
return self.long.get(k, default)
def set_long(self, k, v):
self.long[k] = v
# -----------------------------
# Абстракция LLM (точка замены)
# -----------------------------
class LLMInterface:
def generate(self, prompt: str) -> str:
"""
Здесь мы предоставляем очень простой симулированный ответчик на основе правил.
В реальном использовании: замените на код вызова OpenAI/другой модели и верните текст модели.
"""
# Минимальный пример парсинга: определить, нужно ли нам определять "дождь"
if "идет ли дождь" in prompt or "дождь" in prompt:
return "Сначала запросите погоду; если будет дождь, сгенерируйте напоминание и отправьте его целевому контакту."
if "Сгенерировать напоминание" in prompt:
return "Пожалуйста, напомни Сяо Вану: завтра в Пекине будет дождь, возьми с собой зонт."
return "Я понимаю."
# -----------------------------
# Регистрация инструментов и симулированные инструменты
# -----------------------------
class ToolRegistry:
def __init__(self):
self.tools: Dict[str, Callable[..., Any]] = {}
def register(self, name: str, fn: Callable[..., Any]):
self.tools[name] = fn
def call(self, name: str, *args, **kwargs):
if name not in self.tools:
raise ValueError(f"Инструмент не зарегистрирован: {name}")
return self.tools[name](*args, **kwargs)
# Имитация инструмента: запрос погоды (в реальных ситуациях был бы вызван погодный API)
def mock_weather_api(city: str, date: str) -> Dict[str, Any]:
# Простое правило: если city содержит "Beijing" и date содержит "tomorrow", вернуть пример дождя
if "Beijing" in city and "tomorrow" in date:
return {"city": city, "date": date, "cond": "rain", "precip_mm": 5}
return {"city": city, "date": date, "cond": "sunny", "precip_mm": 0}
# Имитация инструмента: отправка сообщения (в реальных ситуациях были бы вызваны SMS/электронная почта/WeCom и т. д.)
def mock_send_message(contact: str, message: str) -> bool:
print(f"[Отправить сообщение] to={contact} message={message}")
return True
# Имитированный инструмент: простой поиск (иллюстративный)
def mock_search(query: str) -> str:
return f"Симулированный результат поиска: информационная сводка о `{query}`."
# -----------------------------
# Планировщик / Исполнитель
# -----------------------------
class SimplePlanner:
def plan(self, goal: str) -> List[Dict[str, Any]]:
"""
Разложить цель на список шагов (очень упрощённая реализация)
Каждый шаг содержит: action (имя инструмента или внутреннее действие), params
"""
steps = []
# Пример: если запрос содержит "weather", сгенерировать два шага: запросить погоду, решить, отправлять ли напоминание
if "weather" in goal or "rain" in goal:
steps.append({"action": "query_weather", "params": {"city": "Beijing", "date": "tomorrow"}})
steps.append({"action": "decide_and_notify", "params": {"contact_name": "Xiao Wang"}})
else:
steps.append({"action": "search", "params": {"query": goal}})
return steps
class Executor:
def __init__(self, tools: ToolRegistry, memory: Memory, llm: LLMInterface):
self.tools = tools
self.memory = memory
self.llm = llm
def run_step(self, step: Dict[str, Any]):
action = step["action"]
params = step.get("params", {})
if action == "query_weather":
res = self.tools.call("weather", params["city"], params["date"])
self.memory.set_short("last_weather", res)
return res
if action == "decide_and_notify":
weather = self.memory.get_short("last_weather", {})
# Простое решение по правилу
if weather.get("cond") == "rain":
# Пусть LLM сгенерирует текст напоминания (пример)
prompt = f"На основе информации о погоде: {weather}, сгенерируй напоминание для {params['contact_name']}."
reminder = self.llm.generate(prompt)
# Получить контактную информацию из долговременной памяти
contact = self.memory.get_long(params["contact_name"]) или "13800000000"
ok = self.tools.call("send_message", contact, reminder)
return {"notified": ok, "message": reminder}
else:
return {"notified": False, "reason": "солнечная погода"}
if action == "search":
return self.tools.call("search", params["query"])
raise ValueError(f"Неизвестное действие: {action}")
# -----------------------------
# Ядро агента
# -----------------------------
class SimpleAgent:
def __init__(self):
self.memory = Memory()
self.tools = ToolRegistry()
self.llm = LLMInterface()
self.planner = SimplePlanner()
self.executor = Executor(self.tools, self.memory, self.llm)
# Зарегистрировать инструменты по умолчанию
self.tools.register("weather", mock_weather_api)
self.tools.register("send_message", mock_send_message)
self.tools.register("search", mock_search)
# Предположим, что контактная информация Сяо Вана хранится в долговременной памяти
self.memory.set_long("Xiao Wang", "13911112222")
def handle(self, user_prompt: str):
# 1) Разбор мозгом (абстрагировано с помощью LLM)
intent = self.llm.generate(user_prompt)
# 2) Планирование
steps = self.planner.plan(user_prompt)
# 3) Пошаговое выполнение
results = []
for step in steps:
r = self.executor.run_step(step)
results.append({"step": step, "result": r})
# 4) Объединение вывода
return {"intent": intent, "steps": results}
# -----------------------------
# Пример запуска
# -----------------------------
if __name__ == "__main__":
agent = SimpleAgent()
task = Проверь завтрашнюю погоду в Пекине; если будет дождь, напиши напоминание для меня и отправь его Сяо Вану.
out = agent.handle(task)
import json
print(json.dumps(out, ensure_ascii=False, indent=2))
Описание:
- Абстракция LLM:
LLMInterface.generate()Это заменяемое место. Просто замените его кодом, который подключается к OpenAI, Claude или локальной LLM. - ПланировщикОтвечает за разбиение целей, заданных на естественном языке, на упорядоченные шаги. Для начинающих можно использовать правила или шаблоны; в продвинутом варианте можно поручить LLM выводить шаги и преобразовывать их в действия.
- Слой инструментовКаждый инструмент — это независимая функция, единообразно регистрируемая в
ToolRegistryВ реальных проектах это могут быть HTTP-запросы, вызовы SDK, чтение/запись в базу данных и т. д. - Память: Различайте краткосрочную/долгосрочную. Краткосрочная используется для промежуточных результатов текущей задачи, долгосрочная — для контактов, предпочтений и т. д.
- ИсполнительСопоставляет шаги с вызовами инструментов и обрабатывает возвращаемые значения, сбои и логику повторных попыток.
Создайте своего первого ИИ-агента: ассистент по планированию задач
Мы создадимассистента по планированию задачЕго цель: на основе сложной задачи, заданной пользователем (например, я хочу путешествовать), автоматически разложить её на ряд упорядоченных, выполнимых конкретных шагов.
Структура каталогов выглядит следующим образом:

Шаг 1: Создание интеллектуального мозга
Мозгу агента нужна способность рассуждать. Мы будем использовать модель GPT от OpenAI (через вызовы API) в качестве мозга нашего агента.
Вам нужно подготовить ключ API OpenAI. Вы также можете использовать ключ API DeepSeek; он совместим.
В примерах тестирования этой главы используется ключ API DeepSeek. Сначала можно перейтиhttps://platform.deepseek.com/api_keysи подать заявку.
Вы также можете напрямую использовать пакеты Coding Plan от Bailian и Ark:https://www.example.com/claude-code/coding-plan.html。
Сначала установите необходимые библиотеки:
pip3 install openai
Вы можете использовать следующий код, чтобы проверить, успешно ли он запускается:
Пример
from openai import OpenAI
DEEPSEEK_API_KEY = "sk-xxxxxxx" # Укажите здесь ключ, который вы получили
DEEPSEEK_API_URL = "https://api.deepseek.com/v1"
client = OpenAI(
api_key = DEEPSEEK_API_KEY,
base_url = DEEPSEEK_API_URL)
response = client.chat.completions.create(
model="deepseek-v4-flash",
messages=[
{"role": "system", "content": "Вы — полезный помощник"},
{"role": "user", "content": "Привет"},
],
stream=False
)
print(response.choices[0].message.content)
Если установка и настройка пройдут успешно, будет выведено что-то вроде следующего:
Hello! How can I assist you today?
Затем давайте создадим простейший модуль мозга:
код файла brain.py
from openai import OpenAI
import os
DEEPSEEK_API_KEY = "sk-xxxxxxx" # Укажите здесь ключ, который вы получили
DEEPSEEK_API_URL = "https://api.deepseek.com/v1"
client = OpenAI(
api_key = DEEPSEEK_API_KEY,
base_url = DEEPSEEK_API_URL)
class AgentBrain:
Мозг агента, отвечающий за мышление и принятие решений
def __init__(self, model="deepseek-v4-flash"):
self.model = model
def think(self, prompt):
Основная функция мышления: получает промпт и возвращает результат мышления модели
try:
# Вызов Chat Completions API с использованием клиента (синтаксис версии v1.x)
response = client.chat.completions.create(
model=self.model,
messages=[{"role": "user", "content": prompt}],
temperature=0.5, # Управление креативностью: чем ниже, тем более сфокусированно
max_tokens=500 # Управление длиной ответа
)
# Извлечь текстовое содержимое, возвращаемое моделью (изменение пути атрибута в версии v1.x)
reasoning = response.choices[0].message.content
return reasoning.strip()
except Exception as e:
return f"Ошибка процесса мышления: {e}"
# Быстрый тест, чтобы проверить, работает ли мозг
if __name__ == "__main__":
brain = AgentBrain()
test_prompt = "Здравствуйте, пожалуйста, кратко представьтесь."
print("Тестовый вопрос:", test_prompt)
print("Ответ мозга:", brain.think(test_prompt))
При выполнении приведённого выше кода вывод примерно следующий:
测试提问: 你好,请简单介绍一下你自己。 大脑回复: 你好!我是DeepSeek,由深度求索公司创造的AI助手,很高兴认识你!😊 让我简单介绍一下自己: **我的特点:** **完全免费**:目前没有任何收费计划,你可以放心使用 **知识丰富**:知识截止到2024年7月,涵盖各个领域 **对话能力强**:支持128K上下文,可以进行长篇深入对话
Пояснение кода:
- Мы создали
AgentBrainкласс для инкапсуляции взаимодействия с LLM. thinkМетод является ядром, он принимает строкуprompt(prompt) и отправляет её в GPT API.temperatureЭтот параметр очень важен: установка его в 0.5 позволяет Агенту найти баланс между креативностью и стабильностью, что подходит для задач планирования.- Наконец, он возвращает текст, сгенерированный моделью, который является результатом размышлений Агента.
Шаг 2: Определение рук и ног: инструменты и действия
Агенту нужна способность выполнять действия. Мы определяем для него несколько простых инструментов (функций), чтобы он мог действовать.
Код файла tools.py
import datetime
class AgentTools:
"""Коллекция инструментов, которые может использовать Агент"""
@staticmethod
def search_web(query):
"""Имитированный инструмент веб-поиска (имитируется здесь)"""
mock_results = {
"Рекомендация туристического направления": "Париж, Токио, Мальдивы, Лицзян, Юньнань...",
"Погода в Пекине": "Завтра солнечно, температура 15-25°C, слабый ветер.",
"Руководство по Python": "Порекомендуйте сайты, похожие на Rookie Tutorial."
}
for key, value in mock_results.items():
if key in query:
return f"[Веб-поиск] Результаты для '{query}': {value}"
return f"[Веб-поиск] Не найдено четкой информации по запросу '{query}'."
@staticmethod
def make_schedule(steps):
"""Инструмент планирования расписания"""
schedule = "Сгенерированный план расписания:\n"
for i, step in enumerate(steps, 1):
schedule += f"{i}. {step}\n"
return schedule
@staticmethod
def get_current_time():
"""Инструмент получения текущего времени"""
now = datetime.datetime.now()
return f"[Системное время] Сейчас: {now.strftime('%Y-%m-%d %H:%M:%S')}"
@staticmethod
def calculate(expression):
"""Простой инструмент калькулятора (безопасная версия, исправление проблем совместимости)"""
try:
# 1. Строго фильтровать недопустимые символы (разрешить только цифры, базовые операторы, круглые скобки, пробелы)
allowed_chars = set("0123456789+-*/(). ")
if not all(c in allowed_chars for c in expression):
return "[Калькулятор] Выражение содержит недопустимые символы, отказываюсь вычислять."
# 2. Упростить проверку безопасности: удалить подверженную ошибкам логику ast.walk, вместо этого использовать базовую проверку синтаксиса
# Сначала замените пробелы, чтобы избежать пустых выражений
clean_expr = expression.strip().replace(" ", "")
if not clean_expr:
return "[Калькулятор] Выражение не может быть пустым."
# 3. Безопасно выполните вычисление (ограничьте встроенные функции, оставьте только базовые операции)
# Определите пользовательское безопасное глобальное окружение, разрешите только базовые математические операции
safe_globals = {
'__builtins__': {},
'pow': pow,
'abs': abs
}
# Использование eval со строгим ограничением окружения и фильтрацией недопустимых символов значительно снижает риск
result = eval(clean_expr, safe_globals)
return f"[Калькулятор] {expression} = {result}"
except ZeroDivisionError:
return "[Калькулятор] Ошибка: делитель не может быть нулём."
except SyntaxError:
return "[Калькулятор] Синтаксическая ошибка выражения (например, непарные скобки, ошибки операторов)."
except Exception as e:
return f"[Калькулятор] Ошибка вычисления: {str(e)}"
# Инструмент тестирования
if __name__ == "__main__":
print(AgentTools.search_web("Погода в Пекине"))
print(AgentTools.get_current_time())
print(AgentTools.calculate("3 + 5 * 2")) # Обычное вычисление
print(AgentTools.calculate("10 / 0")) # Ошибка деления на ноль
print(AgentTools.calculate("__import__('os').system('ls')")) # Фильтрация недопустимых символов
Анализ кода:
- Каждый
@staticmethodопределяет инструмент, который Агент может вызвать. search_webСейчас имитируется; в реальных сценариях необходимо интегрировать настоящий поисковый API.make_scheduleИспользуется для форматирования списка задач в план.- Важное примечание по безопасности:
calculateВ инструменте,eval()функция чрезвычайно опасна в реальных продуктах и должна быть заменена более безопасным подходом (например,ast.literal_eval) чтобы заменить или полностью удалить её. Это только для демонстрации того, как Агент вызывает функции.
Шаг 3: Соберите Агента: реализуйте основной цикл
Теперь мы соберём мозг и инструменты вместе и реализуем основной цикл принятия решений. Мы разработаем простое правило: пусть мозг решает, какой инструмент использовать, исходя из задачи.
Пример
from brain import AgentBrain
from tools import AgentTools
class SimpleAgent:
"""Простой ИИ-агент для планирования задач"""
def __init__(self):
self.brain = AgentBrain()
# Статический класс инструментов не требует создания экземпляра
self.tools = AgentTools
# Определите список инструментов, известных Агенту, и их описания, используемые для запроса к мозгу
self.tool_descriptions = """
Вы можете использовать следующие инструменты:
1. Инструмент поиска: Используйте, когда вам нужно получить новейшую, неизвестную информацию, например, 'search Beijing weather'.
2. Инструмент планирования: Используйте, когда вам нужно организовать несколько шагов в план, например, 'make plan [step1, step2]'.
3. Инструмент времени: Используйте, когда вам нужно узнать текущее время, команда — 'get time'.
4. Инструмент вычислений: используйте, когда нужно выполнить математические вычисления, например, 'вычислить 3+5*2'.
"""
def run(self, user_task):
"""Запуск основного цикла агента"""
print(f"🎯 Задача пользователя: {user_task}")
print("=" * 40)
# Шаг 1: Восприятие и предварительное мышление
initial_prompt = f"""
Ваша роль — помощник по планированию задач.
{self.tool_descriptions}
Задача пользователя: {user_task}
Пожалуйста, отвечайте строго в следующем фиксированном формате, не добавляйте никакого дополнительного содержимого:
Thought: [кратко проанализируй, что требует задача]
Tool: [выбери название инструмента для использования; если ни один не подходит, напиши 'None']
Инструкция: [конкретное содержимое инструкции, отправленное инструменту]
"""
initial_response = self.brain.think(initial_prompt)
print(🧠 Начальный результат размышления:)
print(initial_response)
print("-" * 20)
# Шаг 2: Разобрать результат размышления, извлечь инструменты и инструкции (оптимизация устойчивости)
lines = [line.strip() for line in initial_response.split('\n') if line.strip()]
tool_to_use = None
tool_instruction = ""
for line in lines:
if line.startswith(Thinking:):
continue # Пропустить строку размышлений
elif line.startswith(Tool:):
tool_to_use = line.replace(Tool:, "").strip()
elif line.startswith(Instruction:):
tool_instruction = line.replace(Instruction:, "").strip()
# Шаг 3: Выполнить действие
result = self._use_tool(tool_to_use, tool_instruction)
print(🛠️ Результат выполнения:)
print(result)
print("=" * 40)
# Шаг 4: Объединить результаты и предоставить обратную связь пользователю
final_prompt = f"""
Исходная задача пользователя: {user_task}
Вы уже подумали и использовали инструменты.
Процесс размышления: {initial_response}
Результат выполнения инструмента: {result}
Теперь, пожалуйста, сгенерируйте полный финальный ответ пользователю, сразу предложив полезный ответ или план, на естественном и дружелюбном языке.
"""
final_response = self.brain.think(final_prompt)
print(💡 Финальный ответ пользователю:)
print(final_response)
return final_response
def _use_tool(self, tool_name, instruction):
"""Вызвать конкретную функцию инструмента на основе имени инструмента"""
# Унифицированное сопоставление имён инструментов (без учёта регистра / с допуском лишних пробелов)
tool_name = tool_name.strip()
if tool_name == Search tool:
return self.tools.search_web(instruction)
elif tool_name == Planning tool:
# Совместимость с китайскими/английскими запятыми и скобками, обработка пустых инструкций
if not instruction:
return [Planning tool] Шаги планирования не предоставлены, невозможно сформировать расписание.
# Удалить скобки и разделить шаги (совместимо со скобками []/()/{})
clean_instr = instruction.strip('[](){}').strip()
# Также поддерживается разделение по китайским и английским запятым
steps = [s.strip() for s in clean_instr.replace(',', ',').split(',') if s.strip()]
return self.tools.make_schedule(steps)
elif tool_name == Инструмент времени:
return self.tools.get_current_time()
elif tool_name == Инструмент вычислений:
return self.tools.calculate(instruction)
elif tool_name == None:
return [System] Нет необходимости использовать инструменты, просто ответьте пользователю напрямую.
else:
return f[System] Неизвестный инструмент: {tool_name}, невозможно выполнить.
# Запускаем нашего агента!
if __name__ == "__main__":
print(🤖 Запуск SimpleAgent...)
my_agent = SimpleAgent()
# Тестируем несколько разных задач
test_tasks = [
Я хочу путешествовать, помоги мне спланировать, что мне нужно подготовить,
Сколько сейчас времени?,
Вычислите 15 в квадрате плюс одну треть от 20,
]
for task in test_tasks:
my_agent.run(task)
print("\n" + "#" * 50 + "\n")
Выполните код, вывод будет примерно таким:
启动 SimpleAgent... 用户任务: 我想去旅行,帮我规划一下需要准备什么 ======================================== 初始思考结果: 思考:用户需要规划旅行前的准备工作。这是一个通用任务,不需要最新信息或计算,但需要将多个准备步骤整理成一个清晰的计划。 工具:计划工具 指令:制定计划 [1. 确定目的地和旅行时间,2. 预订交通票(机票/火车票)和住宿,3. 准备旅行证件(身份证、护照、签证等),4. 安排行程和景点门票,5. 打包行李(衣物、洗漱用品、药品、充电器等),6. 安排家中事务(宠物、植物、邮件等),7. 兑换货币或准备支付方式,8. 购买旅行保险] -------------------- 执行结果: ...
Разбор кода и поток выполнения:
- Инициализация: Агент создал собственный мозг (
AgentBrain) и набор инструментов (AgentTools)。 - Получение задачи:
runМетод запускается, получаетuser_task(например, "Я хочу путешествовать"). - Фаза мышления: объедините описания задачи и инструментов в
initial_prompt, отправьте в мозг. Текст, возвращаемый мозгом, содержит "инструмент", который он выбрал, и "инструкции", данные инструменту. - Фаза действий:
_use_toolФункция вызывает соответствующую функцию инструмента на основе выбора мозга и возвращает результат. - Обратная связь и резюме: Снова отправьте исходную задачу, ход мыслей и результаты действий в мозг, чтобы он сгенерировал удобный для пользователя окончательный ответ.
Запустите эту программу, и вы увидите, как Агент анализирует задачи шаг за шагом, выбирает инструменты, выполняет действия и предоставляет ответы.
Практическое упражнение: улучшите своего агента
У вас уже есть работающий ИИ-агент! Но это только отправная точка. Попробуйте выполнить следующие упражнения, чтобы сделать его мощнее:
Упражнение 1: добавьте функцию памяти
- Цель: пусть Агент запоминает историю разговора.
- Подсказка: В
SimpleAgentкласс, добавьтеself.conversation_history = []список. Каждый раз, когда вы вызываетеbrain.think, не только отправляйте текущий промпт, но и отправляйте предыдущую историю разговора в качестве контекста. После выполнения добавьте новый ход разговора (ввод пользователя, размышления ИИ, результаты инструментов) в список истории.
Упражнение 2: Реализуйте автоматический выбор инструментов
- Цель: Сделать ответ мозга в стандартном формате JSON, чтобы программа могла легко автоматически его разбирать, а не полагаться на извлечение текста.
- Подсказка: Измените промпт так, чтобы мозг возвращал
{"thought": "…", "tool": "…", "instruction": "…"}строку JSON. Затем в коде используйтеjson.loads()для парсинга, повышая стабильность и точность.
Упражнение 3: Добавьте новый инструмент
- Цель: Пусть Agent обрабатывает задачи списка дел.
- Подсказка: В
AgentToolsclass, добавьтеtodo_list = []и два новых метода:add_todo(item)иshow_todos(). В описании инструмента расскажите мозгу об этом новом инструменте и обновите_use_toolметод для его вызова.
Итоги и перспективы
Поздравляем! Вы успешно создали базовый ИИ-агент с цикломвосприятие-мышление-действие. Давайте рассмотрим ключевые моменты:
- Ключевые концепции: ИИ-агент = Мозг (LLM) + Восприятие + Действие + Цель.
- Ключ к реализации:
- Мозг: Вызов LLM (например, GPT) через API для рассуждений.
- Инструменты: Инкапсулируйте конкретные возможности в функции, чтобы агент мог их вызывать.
- Цикл: Используйте логику кода для связи мышления, принятия решений и выполнения.
Это лишь верхушка айсберга в мире ИИ-агентов. Промышленные фреймворки, такие какLangChain、AutoGen, предоставляют более мощную интеграцию инструментов, управление памятью, мультиагентное сотрудничество и другие возможности. Для дальнейшего изучения рекомендуется:
Другие расширения