Разгортванне агента LangGraph у AWS Bedrock AgentCore крок за крокам

Большая колька агентаў LangGraph добра працуюць на ноутбуку, але зупыняюцца на этапы пераходу да практычнага вікорыстоўвання. AWS Bedrock AgentCore усуне гэтыя проблемы за дапамой хостынгу без сервераў, які можа масштабавацца і не выклікае патрэбы ў перадзяле коду. У наступных раздзелах практычна паказана, як адаптаваць існуючы агент для AgentCore, стварыць праект, запусціць яго локальна, выкласты на AWS і вызваць пасля таго, як ён будзе працаваць.

Што такое AgentCore

AgentCore — гэта хоставаны сервіс ад AWS, дзе агенты размешчаюцца, масштабуюцца і запускаюцца без неабяжнай адпаведнае керування серверамі. Фрэймворкі такія як LangGraph, Strands, CrewAI і LlamaIndex, а таксама мадэлі ад OpenAI, Google і Anthropic, працуюць у яму, таму код агента застаецца незменным. Ізоляцыя сесій, стойкая памяць, можлівасць аналізу дзеяння і керування ідэнтычнасцю ёсць вбудованымі функцыямі.

Усё керуецца прыемнікам AgentCore CLI. Гэта програма на Node.js, якая стварае каркас праекта, запускае агента локальна і выкладзе яго на AWS за дапамою CDK, які працюе пад канопам.

Пярэшкоды

• Python 3.12 або новейшая версія
• uv або pip для керавання пакетамі Python
• Node.js 20 або новейшая версія, адколькі прыемнік распространяецца праз npm
• AWS CDK, установлены ў глобальным рэжыме за дапамою npm install -g aws-cdk
• Абанк AWS з крантэнтамі, настроенымі локальна за дапамою aws configure
• Ўжытны код LangGraph, які стварае скомпіляваны StateGraph

Шаг 1: установка прыемніка

Усё керуецца аднам інструментам у лініі команд: стварэнне праекта, запуск прыкладнення локальна і выкладка на AWS.

npm install -g @aws/agentcore

Паказваце, чы гэтыя установкі працавалі:

agentcore --help

Шаг 2: дадзенне залежнасцей

Два пакеты трэба дадзець да залежнасцей агента. bedrock-agentcore — гэта Python SDK, які суплячае клас-обгортку BedrockAgentCoreApp, а aws-opentelemetry-distro — гэта версія інструментарыя OpenTelemetry для Python, створаная AWS.

# pyproject.toml
[project]
name = "my-agent"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "aws-opentelemetry-distro==0.17.0",
 "bedrock-agentcore>=1.6.3",
    "boto3>=1.42.0",
    "langgraph>=1.1.0",
    "langchain-core>=1.2.0",
    # ... your other existing dependencies
]

З’явіце якім бы ні было способам, якія звычайна для праекта:

uv sync
# or: pip install -e .

Шаг 3: запісаце точку запуску ў main.py

AgentCore чакае аднае файла на Python як точку запуску, які мае маціць экзанпляр BedrockAgentCoreApp і функцыю, дэкораваную @app.entrypoint. Логіка LangGraph практычна не зменшваецца — яна проста ўкладваецца ў маленькую точку запуску пад час выканання.

# main.py
from langchain_core.messages import HumanMessage
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from graphs.my_agent_graph import build_my_agent  # your existing graph builder

# 1. Instantiate the AgentCore app and logger
app = BedrockAgentCoreApp()
log = app.logger

# 2. Build your graph at module load time (startup)
#    AgentCore initialises the module once, then handles concurrent invocations.
#    Any failure here will prevent a broken agent from going live.
def create_agent():
    log.info("Initialising agent...")
    graph = build_my_agent()   # returns your compiled LangGraph StateGraph
    log.info("Agent ready")
    return graph
try:
    graph = create_agent()
except Exception as e:
    log.error(f"Critical failure during agent initialisation: {e}")
    raise  # fail fast - don't let a broken agent start serving requests

# 3. Async helper that drives the LangGraph streaming loop
async def run_agent(user_input: str, session_id: str = "default-session") -> str:
    responses = []
    config = {"configurable": {"thread_id": session_id}}
    async for chunk in graph.astream(
        {"messages": [HumanMessage(content=user_input)]},
        config=config,
        stream_mode="values",
    ):
        messages = chunk.get("messages", [])
        if messages:
            last = messages[-1]
            if getattr(last, "type", None) == "ai":
                responses.append(last)
    if not responses:
        return "No response"
    content = getattr(responses[-1], "content", "")
    return content if isinstance(content, str) else str(content)

# 4. The entrypoint - this is what AgentCore calls on every invocation
@app.entrypoint
async def invoke(payload, context):
    try:
        log.info("Invoke received")
        user_input = payload.get("prompt", "")
        session_id = payload.get("session_id", "default-session")
        if not user_input.strip():
            return {"error": "Prompt cannot be empty"}
        response = await run_agent(user_input, session_id)
        return {"response": response}
    except Exception as e:
        log.error(f"Error: {e}")
        return {"error": str(e)}

# 5. Run the app (only executed when running locally using agentcore dev)
if __name__ == "__main__":
    app.run()

Што мае значэнне ў тым файле

• BedrockAgentCoreApp() стварае аб’ект рабочага прыемніка: HTTP-сервер, маршруты для перагляду стану і структураваныя логі, усе гэта ужо падключанае.
• Граф ствараецца на рэвэлі модуля, адразу пасля імпорту, а не з кожнага вызову. Таму будзь-яя проблема пад час запуску практычна мгнова стае відна, а несправны прыемнік ніколі не отрымае трафіку.
• @app.entrypoint пазначае прыемнік для прыходзячых вызоваў. Ям даецца payload — дэкодаваны тэла JSON, а таксама context для запіту AgentCore. Рэзультат, які ён вяртае, павінен быць звычным слоўнікам, які можа быць серыялізаваны ў JSON. Простая строка чы адзін створаны клас не падходзяць.
• Прыходзячы session_id стае thread_id у LangGraph, таму MemorySaver зберагае околачынную памяць окрэма для кожнай сесіі.

Крок 4: стварэнне праекта

Далей йдзе план праекта. Запускайце візард ініцыялізацыі з чыстага корневага папкі і дазвольце яму стварыць каркас:

agentcore create

Візард запітвае працоўнікі пра такі дэталі, як назва праекту, мова, версія Python і файл входу. Файл входу і версія Python павінны падходзіць аплікацыі. Пасля чаго у папцы agentcore з’яўляецца файл agentcore.json, які паведамляе AgentCore, дзе знаходзіцца код і як яго запускаць.

{
  "name": "MyAgentOnAgentcore",
    "runtimes": [
    {
      "name": "my-agent",
      "build": "CodeZip",
      "entrypoint": "main.py",
      "codeLocation": "app/my-agent/",
      "runtimeVersion": "PYTHON_3_12",
      "networkMode": "PUBLIC",
      "protocol": "HTTP",
	  "envVars": []
	}
  ]
}

Шаг 5: размясціце код там, дзе шукае AgentCore

Перыявіце або скопіюйце код агента ў каталог, названы codeLocation у файле agentcore.json. Легка памыліцца, і неправільная локацыя прызводзіць да непатрэбных труднасцяў пад час развяртання. Частая памылка — падкладкі коду працоўна ў самы каталог agentcore, што можа забраць багато часу. Структура должна выглядаць так:

MyAgentOnAgentcore/
├──agentcore
	└── agentcore.json
├──app/
	└──my-agent/          			 ← codeLocation
		├── main.py                  ← entrypoint (matches agentcore.json)
		├── pyproject.toml           ← or requirements.txt
		├── src/
		│   └── my_agent_graph.py    ← your LangGraph graph builder
		│   └── tools.py             ← your tools, utilities, etc.
		└── .env					 ← your configuration variables

main.py павінен знаходзіцца на верхнім рэвэлі codeLocation і абсалютна ўзмацаваць пункт запуску з agentcore.json.

Зменныя сяродавішча

AgentCore можа перадаць зменныя сяродавішча контэйнеру часу выканання. У локальных умовах найпростым спосабам ёсць файл .env. У прымэтнай експлуатацыі значэнні можна размістыць у agentcore.json пад роздзелам envVars, хоць файл .env таксама падходзіць. Таёмныя даны, такія як паролі і ключы API, лепшая зберагаць у AWS Secrets Manager і завантажваць ў час выканання; у такім случае ролі выканання AgentCore павінна маты права на ўзяцце ў чытанне. Заўважыце, што envVars — гэта маса об’ектаў JSON, кожны з якіх мае поля name і value.

Шаг 6: перакананне

Перш чым запускаць ўсё, нехай CLI пераканае конфігурацыю:

agentcore validate

Простыя проблемы, такія як відсутній файл входу чыраг пасёвы пацеку у налашчэннях, выявляюцца самэўсёлкі.

Шаг 7: запуск і тэставанне на месцы

Запускайце локальны рантайм за дапамою:

agentcore dev

Ён запускае локальны сервер HTTP, які точная адпаведніца серверу для рэальных умоў. Калі все налажана правільна, у рэзультатах паказваецца, што прыкладна програма готова і прыёмле прыёмы на локальным порту.

Выклік локальнага сервера

Выклік можа здзейсніцца праз CLI:

agentcore invoke "Summarise last month sales"

альбо за дапамою curl:

curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarise last month sales", "session_id": "test-001"}'

Хораша адказва — гэта JSON, у яком усерэдзін адказ агента:

{"response": "Last month, total sales were $1.2M across 3 regions..."}

Шаг 8: развяроць на AWS

Калі локальныя тэсты практычна завершаны, развяроць на AgentCore Runtime:

agentcore deploy

У закрытых умовах CLI пакетавае код, стварае кантэйнер S3 для безпаснага размешчэння коду, стварае ролю выканання IAM і размешчае AgentCore Runtime за дапамою CDK. Перша разметка займае калькі мінут, а наступныя зазвычай выкананы быстрэй.

Калі ўсё завершыцца, пераканайцеся ў статусе рантайму. У рэзультатах паказваецца ARN рантайму і HTTP-адрэс для запуску размешчанага агента.

agentcore status

Шаг 9: запуск агента, які быў розмішчаны

CLI — гэты найпросты спосаб прыступіць да версіі, якая была розмішчана:

agentcore invoke --prompt "Who are the top 5 customers by revenue?" --session-id "session-id-with-length-greater-than-or-equal-33"

Для вызова праз HTTP неабяжна падпісваець запіта за дапамою AWS SigV4:

curl -X POST "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn-of-MyAgentOnAgentcore-xxxx/invocations" \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  --aws-sigv4 "aws:amz:us-east-1:bedrock-agentcore" \
  -H "Content-Type: application/json" \
  -H "x-amzn-bedrock-agentcore-runtime-session-id: session-id-with-length-greater-than-or-equal-33" \
  -d '{"prompt": "Who are the top 5 customers by revenue?"}'

Існавайце HTTP-адрэсу з agentcore status.

Для вызоў з іншага коду на Python, SDK зазвычай яўляецца найболей прыдатным выборам. Зберагуйце ARN часу выканання ў зменнай сераўіса, перадайце запіт і зноў адправляйце ID пярэдней сесіі з кожным наступным вызам.

# invoke_agent.py
import json
import boto3
import os
from dotenv import load_dotenv

load_dotenv()

client = boto3.client("bedrock-agentcore", region_name="us-east-1")
runtime_arn = os.getenv("AGENTCORE_RUNTIME_ARN")

def invoke(prompt: str, session_id: str) -> str:
    payload = json.dumps({"prompt": prompt, "session_id": session_id})
    response = client.invoke_agent_runtime(
        agentRuntimeArn=runtime_arn,
        payload=payload,
        contentType="application/json"
    )
    body = json.loads(response["response"].read().decode())
    return body["response"]

if __name__ == "__main__":
    session_id = ""
    print("Ready. Type 'exit' to quit.")

    while True:
        prompt = input("Your question: ").strip()
        if prompt == "exit":
            break

        if not prompt:
            continue

        params = {
            "agentRuntimeArn": runtime_arn,
            "payload": json.dumps({"prompt": prompt}),
            "contentType": "application/json"
        }
        if session_id:
            params["runtimeSessionId"] = session_id

        try:
            response = client.invoke_agent_runtime(**params)
            body = json.loads(response["response"].read().decode())
            session_id = response.get("runtimeSessionId", session_id)
            print(f"Agent: {body['response']}\n")
        except Exception as e:
            print(f"Error: {e}")

Установіце AGENTCORE_RUNTIME_ARN у файле .env:

AGENTCORE_RUNTIME_ARN=arn:aws:bedrock-agentcore:us-east-1:123456789012:agent-runtime/MyAgentOnAgentcore-xxxx

Зберагчыце стан сэсіі між вызамі

Паглядзіце на runtimeSessionId у прыкладзе boto3. AgentCore вяртае яго з кожнай адпаведзю. Яго адправка ў наступны запіт дазволяе направляць наступныя запіты ў той самы кантэкст сэсіі, і ў поўнай зусіллі разам з MemorySaver з LangGraph агент мае можлівасць зберагчыць всю памяць размовы між аднальнымі HTTP-запытамі.

Пашыльныя проблемы

• Праця агента не запускаецца намеравана. Калі create_agent() выклікае памылку пад час імпорту, AgentCore не запускае рэнтайм-сервіс. Такая поведэнцыя заходзіць ад некорэктна настроюванага агента, напрыклад, такога, у якога няма неабходных крантэнаў або некарэктны URL базы дадзенаў, каб ён могаў працаваць без проблем.
• Патронам не хачацца дадаць. Ролю выканання AgentCore трэба стварыць з явным правам на доступ да будзь-якіх служб AWS, якія вікорыстоўвае агент, уключаючы Secrets Manager і S3. Дадзіце гэтыя патроны пасля першага развертвання.
• Версіі должны састаць адпаведнымі. Будзь-яя версія Python, якую зазначае pyproject.toml, должна састаць адпаведной настройцы часу выканання ў agentcore.json.
• Павінны вяртаць звычныя слоўнікі. Калі точка входу вяртае строку або спецыяльны об’ект, механізм часу выканання яго адхіляе.

Што на самай працы змініцца

Ёжы з местнага агента LangGraph да AgentCore патрабуе толькі калькі змян: установіць два дапаможныя пакеты, абгорнуць граф у BedrockAgentCoreApp, стварыць праект, працаваць локальна, а пасля размістыць і запусціць яго. Граф, інструменты, вызовы модэляў і настройкі памяці застаюцца па-большайшай частцы незмяненымі. AgentCore керуе інфраструктурным аспектам, а логіка агента застаецца у веданні LangGraph.

Супаўзвязаныя матэрыялы

• Your Agent Graph Belongs in YAML: Compiling a 17-Agent LangGraph at Startup — Як маленькі рантайм компілюе спецыфікацыю у фармаце YAML у LangGraph StateGraph: генераваны стан, плагіны importlib, маршрутызаторы пазначэнняў, адаптываныя вызовы і змены вузлаў за сесіяй.

Шлюзы адміністрацыі і мнагаагентны маршрутызацыя для бота падтрымкі LangGraph — Дае можлівасць дадаць дэтэрміністычныя шлюзы бізнес-логікі, самакорэктуючыся цыкл адміністрацыі і керуючы элемент з трыма спецыялістскімі сабграфамі для агента LangGraph у сферэ е-камеры.