Самое важное из мира AI — в канале MAX AgentLabОтдельные разборы, инструменты и практические схемы Читайте Agent Lab в Telegram Разборы, кейсы и новости о практических AI-агентах без лишней воды.
Практика Python До 12 минут

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

Создаём агента с инструментами на Strands Agents
Temporary fallback cover; replace in editorial pass.

В этом материале соберём минимального агента, который работает через Amazon Bedrock, обращается к API правил и запускает собственную Python-функцию броска костей. Затем проверим журнал, чтобы увидеть, какие инструменты модель действительно вызвала.

Что получится. Один файл agent.py, виртуальное окружение Python и команда запуска. Пример показывает структуру интеграции; фактический ответ модели и порядок вызовов зависят от выбранной модели, запроса и настроек AWS.

Как устроен пример

У агента будет два инструмента:

Пользовательский запрос попросит агента найти правило и бросить несколько костей. Модель сама решит, нужно ли вызвать один инструмент, оба или ни одного. Важно: инструменты не вызываются обычным 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. Проверяйте не формулировку, а признаки правильного потока:

  1. агент получил запрос;
  2. модель запросила HTTP-инструмент с методом GET;
  3. модель запросила roll_dice с допустимыми аргументами;
  4. инструменты вернули результаты;
  5. модель сформировала итоговый ответ.

Если стандартного уровня логирования недостаточно, временно включите более подробный журнал для отладки:

logging.getLogger("strands").setLevel(logging.DEBUG)

Не публикуйте DEBUG-логи целиком: в них могут попасть параметры запросов, фрагменты контекста или данные, которые нельзя отдавать третьим лицам. Для production лучше настроить фильтрацию, маскирование и ограниченный срок хранения журналов.

Как отличить вызов инструмента от обычного текста

Фраза модели «я обратился к API» сама по себе не доказывает, что HTTP-запрос был выполнен. Надёжнее сопоставлять три источника:

Для собственного инструмента полезно добавить короткий лог непосредственно перед вычислением. Не записывайте туда содержимое пользовательского запроса, если оно может содержать персональные данные:

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 и состав готовых инструментов могут меняться между версиями, поэтому сверяйте импорт с документацией установленной версии.

Ограничения примера

Итог

Мы подключили к одному агенту два разных типа возможностей: готовый HTTP-инструмент для обращения к API и собственную типизированную функцию Python. Ключ к проверке — не только итоговый текст, а журнал вызовов с параметрами и результатами. На этой основе можно добавлять внутренние API, базы данных и другие инструменты, сохраняя отдельные проверки для каждого внешнего действия.

Для продолжения смотрите другие практические гайды и глоссарий терминов.

Источники и документация