Создаём агента с инструментами на Strands Agents

В этом материале соберём минимального агента, который работает через Amazon Bedrock, обращается к API правил и запускает собственную Python-функцию броска костей. Затем проверим журнал, чтобы увидеть, какие инструменты модель действительно вызвала.
agent.py, виртуальное окружение Python и команда запуска.
Пример показывает структуру интеграции; фактический ответ модели и порядок вызовов
зависят от выбранной модели, запроса и настроек AWS.
Как устроен пример
У агента будет два инструмента:
http_request— готовый инструмент для HTTP-запроса к API правил;roll_dice— наша функция на Python, которую Strands передаст модели как инструмент.
Пользовательский запрос попросит агента найти правило и бросить несколько костей. Модель сама решит, нужно ли вызвать один инструмент, оба или ни одного. Важно: инструменты не вызываются обычным Python-кодом напрямую из текста запроса — решение принимает модель в рамках цикла агента.
1. Подготовьте окружение
Нужны Python 3.10 или новее, аккаунт AWS с доступом к Amazon Bedrock и настроенные учётные данные AWS. Секреты не записывайте в исходный файл и не вставляйте в команду, которую собираетесь публиковать.
mkdir strands-tools-demo
cd strands-tools-demo
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install strands-agents strands-agents-tools boto3
В Windows PowerShell активация окружения выглядит так:
.venv\Scripts\Activate.ps1
Настройте регион и проверьте AWS-профиль через стандартный механизм AWS CLI:
aws configure
aws sts get-caller-identity
Команда aws sts get-caller-identity должна вернуть сведения о текущей
IAM-идентичности. Если в аккаунте ещё не разрешён выбранный foundation model,
включите доступ к нему в консоли Amazon Bedrock и проверьте доступность модели в нужном
регионе.
2. Напишите собственный инструмент
Декоратор @tool превращает обычную Python-функцию в инструмент. Strands
использует имя функции, аннотации типов и docstring, чтобы сформировать описание,
которое увидит модель.
Создайте файл agent.py и добавьте функцию броска костей:
import logging
import random
from strands import Agent, tool
from strands_tools import http_request
@tool
def roll_dice(number: int = 1, sides: int = 20) -> str:
"""Бросить указанное количество одинаковых игральных костей.
Args:
number: Количество костей от 1 до 10.
sides: Количество граней у каждой кости от 2 до 100.
"""
if not 1 <= number <= 10:
return "Ошибка: number должен быть от 1 до 10."
if not 2 <= sides <= 100:
return "Ошибка: sides должен быть от 2 до 100."
rolls = [random.randint(1, sides) for _ in range(number)]
return f"Результаты бросков d{sides}: {rolls}; сумма: {sum(rolls)}"
Ограничения на входе нужны не только для удобства. Они не дают модели запросить чрезмерное количество операций и делают поведение инструмента предсказуемым. Результат броска намеренно не является криптографически защищённым случайным числом: это демонстрация обычного игрового броска.
3. Подключите API-инструмент
В примере используется готовый http_request из пакета инструментов Strands.
Он позволяет агенту выполнить HTTP-запрос, когда это необходимо. В качестве API правил
возьмём публичный API правил Dungeons & Dragons 5e. Это внешний сервис для примера,
поэтому его доступность и формат ответа могут измениться.
Передадим агенту адрес API в системной инструкции и явно опишем безопасные границы: только чтение, только GET-запрос, без передачи секретов.
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s %(levelname)s %(name)s: %(message)s",
)
agent = Agent(
tools=[
http_request,
roll_dice,
],
system_prompt=(
"Ты помощник по настольным играм. "
"Если нужно узнать правило, используй http_request только методом GET "
"к API https://www.dnd5eapi.co. "
"Не отправляй POST, PUT, PATCH или DELETE. "
"Не передавай в запросах секреты и персональные данные. "
"Если пользователь просит бросок костей, используй roll_dice. "
"Не утверждай, что инструмент был вызван, если в журнале нет подтверждения."
),
)
if __name__ == "__main__":
prompt = (
"Найди в API правило с кратким объяснением про состояния персонажа, "
"а затем брось две двадцатигранные кости. "
"Раздели ответ на: источник правила и результаты броска."
)
result = agent(prompt)
print(result)
Вызов Agent(...) собирает инструменты в единый список. Для модели
http_request и roll_dice становятся доступными действиями,
но код функции выполняется только после соответствующего tool call.
4. Запустите агента и проверьте журнал
Запустите программу:
python agent.py
Точный текст ответа заранее неизвестен: он зависит от модели Bedrock и содержимого ответа API. Проверяйте не формулировку, а признаки правильного потока:
- агент получил запрос;
- модель запросила HTTP-инструмент с методом GET;
- модель запросила
roll_diceс допустимыми аргументами; - инструменты вернули результаты;
- модель сформировала итоговый ответ.
Если стандартного уровня логирования недостаточно, временно включите более подробный журнал для отладки:
logging.getLogger("strands").setLevel(logging.DEBUG)
Не публикуйте DEBUG-логи целиком: в них могут попасть параметры запросов, фрагменты контекста или данные, которые нельзя отдавать третьим лицам. Для production лучше настроить фильтрацию, маскирование и ограниченный срок хранения журналов.
Как отличить вызов инструмента от обычного текста
Фраза модели «я обратился к API» сама по себе не доказывает, что HTTP-запрос был выполнен. Надёжнее сопоставлять три источника:
- сообщение о вызове инструмента в журнале Strands;
- параметры вызова, например URL, метод и аргументы костей;
- результат выполнения инструмента.
Для собственного инструмента полезно добавить короткий лог непосредственно перед вычислением. Не записывайте туда содержимое пользовательского запроса, если оно может содержать персональные данные:
logger = logging.getLogger(__name__)
@tool
def roll_dice(number: int = 1, sides: int = 20) -> str:
"""Бросить указанное количество одинаковых игральных костей."""
logger.info("roll_dice called: number=%s, sides=%s", number, sides)
# проверки и бросок остаются без изменений
Типовые ошибки
AccessDeniedException или ошибка доступа к модели
Проверьте IAM-права, регион AWS и доступ к конкретной модели в Amazon Bedrock. У разных моделей и регионов могут быть разные условия доступа. Не расширяйте права вслепую: начните с политики, разрешающей только необходимые действия.
Модель не вызывает инструмент
Уточните запрос: назовите действие явно — «получи правило через API» или «брось две
d20». Также проверьте, что инструмент передан в список tools, а его
docstring описывает назначение и параметры.
HTTP-инструмент возвращает ошибку
Проверьте URL, сетевой доступ и статус внешнего API. Публичный сервис может временно недоступен или изменить схему ответа. Для production добавьте таймауты, ограничение доменов, обработку кодов 4xx/5xx и собственный кэш там, где это допустимо.
Не находится strands_tools
Убедитесь, что активировано то же виртуальное окружение, в которое установлены пакеты.
Затем обновите пакет инструментов командой python -m pip show strands-agents-tools.
API и состав готовых инструментов могут меняться между версиями, поэтому сверяйте
импорт с документацией установленной версии.
Ограничения примера
- Публичный API правил не является частью вашего приложения и не даёт гарантии доступности.
- Случайность Python-функции подходит для демонстрации, но не для азартных игр или безопасности.
- Модель сама выбирает момент вызова инструмента; для критичных операций добавляйте явные проверки и подтверждение пользователя.
- Сетевой инструмент расширяет поверхность риска: ограничивайте домены, методы, таймауты и объём ответа.
- Стоимость и задержка зависят от модели Bedrock, количества итераций и размера контекста.
Итог
Мы подключили к одному агенту два разных типа возможностей: готовый HTTP-инструмент для обращения к API и собственную типизированную функцию Python. Ключ к проверке — не только итоговый текст, а журнал вызовов с параметрами и результатами. На этой основе можно добавлять внутренние API, базы данных и другие инструменты, сохраняя отдельные проверки для каждого внешнего действия.
Для продолжения смотрите другие практические гайды и глоссарий терминов.