Resumen
Hace poco hice el curso de Agentes de la Academia GEAR de Google, donde experimenté con sesiones, state, tools, modelos locales y ejecución de código. En este artículo comparo Google ADK con Strands Agents a partir de un mismo caso real, un pipeline multiagente que construye un knowledge graph. También muestro cómo desplegarlo en Amazon Bedrock AgentCore con Terraform, cómo invocarlo y los resultados.
Introducción
Google ADK y Strands Agents (cuyo SDK hoy la documentación llama Strands Harness SDK) son dos frameworks open source para construir agentes de IA en Python, y los dos corren en AWS. La diferencia está en cómo piensan el problema: ADK pone primero la estructura (un grafo de nodos y aristas que se define en código) y trae un entorno de desarrollo visual, mientras que Strands parte de un agente que decide con el modelo y suma patrones (Graph, Swarm, Workflow) cuando hace falta estructura.
En este artículo comparo los dos con un caso real, el mismo pipeline multiagente que construí con Strands en una serie anterior, reescrito con ADK 2.12.0 y Amazon Nova vía Bedrock, y desplegado en AgentCore.
Conceptos clave de ADK
ADK (Agent Development Kit) es el framework open source de Google para construir, evaluar y desplegar agentes. Tiene SDKs en Python, TypeScript, Go, Java y Kotlin, está optimizado para Gemini y admite otros modelos mediante integraciones como LiteLLM, Ollama o vLLM.
➡ Construir un agente con ADK
Un agente mínimo se crea en una carpeta con un agent.py que define root_agent, el único elemento obligatorio. Las tools son funciones Python con type hints y docstring. ADK las envuelve solo en un FunctionTool, y en ADK Python no existe el decorador @tool.
Para programar y ejecutar un ejemplo funcional en Python hacen falta tres cosas:
- Python 3.12 o superior.
- Un entorno virtual, para no mezclar dependencias con otros proyectos.
- Acceso a un modelo, que puede ser una API key de Gemini (se crea en Google AI Studio), un modelo local o Amazon Bedrock vía LiteLLM.
python -m venv .venv
source .venv/bin/activate # Windows (Git Bash): source .venv/Scripts/activate
pip install google-adk
Según lo que se use, hay extras que se instalan aparte:
-
pip install "google-adk[eval]"paraadk evaly la pestaña Eval deadk web. -
pip install "google-adk[extensions]"paraLiteLlm(Bedrock, Ollama y otros modelos que no son Gemini).
El comando adk create mi_agente crea una estructura mínima. Pregunta qué modelo se va a usar y guarda la configuración en el .env:
mi_agente/
├── __init__.py
├── agent.py # defines root_agent
└── .env
GOOGLE_API_KEY=tu_key_real
GOOGLE_GENAI_USE_VERTEXAI=FALSE
Con GOOGLE_GENAI_USE_VERTEXAI=TRUE, ADK ignora la API key y pide credenciales de Vertex AI. Para probar, ejecutar desde la carpeta padre adk run mi_agente (consola) o adk web (navegador). Ambos cargan el .env solos; si en cambio se corre un script propio, hay que llamar a load_dotenv() antes de importar el agente.
from google.adk.agents import Agent
def get_capital_city(country: str) -> dict:
"""Retrieves the capital city for a given country."""
return {"status": "success", "capital": "Paris"}
root_agent = Agent(
model="gemini-flash-latest",
name="geo_agent",
instruction="Answer questions about country capitals.",
tools=[get_capital_city],
)
Para usar un modelo que no es Gemini, como Amazon Nova en Bedrock, solo se cambia el model por un LiteLlm (requiere el extra [extensions]). Las credenciales salen de la cadena estándar de AWS. Si el agente corre en tu máquina, usa el perfil configurado en la AWS CLI. Si está desplegado en AWS, usa el rol IAM que tiene asignado.
from google.adk.models.lite_llm import LiteLlm
root_agent = Agent(
model=LiteLlm(model="bedrock/us.amazon.nova-2-lite-v1:0"),
...
)
Las piezas que más se usan al pasar del prototipo a algo real:
| Concepto | Qué es y cómo se usa |
|---|---|
Agente (LlmAgent) |
Agente que razona con un LLM. Se declara un model, instruction y tools
|
| Runner | Motor que ejecuta el flujo de eventos entre agentes, modelo y tools. En scripts se usa run_async y create_session con await
|
| Sesión y state | Historial y datos de la conversación. Prefijos de alcance: sin prefijo (sesión), user:, app:, temp: (un turno) |
output_key |
Guarda la respuesta del agente en el state. Otro agente la lee con {clave} en su instruction
|
output_schema |
Respuesta JSON validada con un esquema Pydantic |
| Servicios de sesión |
InMemorySessionService (no persiste), SQLite (el que usa adk web en local), DatabaseSessionService (base SQL) y VertexAiSessionService. Misma interfaz |
| Callbacks | Hooks antes y después de llamar al modelo. Sirven de guardrails (before_model_callback, after_model_callback) |
Estos tres detalles los descubrí realizando pequeñas pruebas:
- En las plantillas de
instruction,{topic}lanzaKeyErrorsi la clave no existe en el state y{topic?}la reemplaza por vacío (state). - La tool
google_searches grounding de Gemini: ADK valida que el modelo sea Gemini antes de usarla (con otro modelo no funciona). - ADK permite combinar
output_schemacontools, pero con Nova vía LiteLLM el modelo respondió directamente con el JSON sin llamar a la tool.LiteLlmdeclara que el modelo soporta las dos cosas juntas, así que ADK envía el esquema y las tools en la misma petición, y el modelo eligió el formato. Si un agente necesita usar tools, conviene que otro nodo se encargue de la salida estructurada.
➡ Sesiones asíncronas
En ADK, el servicio de sesiones y el Runner son asíncronos. Mi primer script de prueba en el curso lo escribí con hábitos síncronos y no funcionaba por dos motivos:
-
create_sessiones una corrutina: sinawaitdevuelve un objeto pendiente y la sesión nunca se crea. - La sesión que devuelve el servicio es una copia (
InMemorySessionServicehacedeepcopy). Leersession.statede esa variable después de ejecutar el agente muestra el state viejo.
# Wrong: synchronous habits
session = session_service.create_session(app_name=APP, user_id=USER, session_id=SID) # coroutine, never awaited
...
print(session.state) # stale copy: does not show what the agent wrote
# Right: create, run and read the session again
await session_service.create_session(app_name=APP, user_id=USER, session_id=SID)
async for event in runner.run_async(user_id=USER, session_id=SID, new_message=message):
...
session = await session_service.get_session(app_name=APP, user_id=USER, session_id=SID)
print(session.state) # fresh copy, includes the agent's writes
En Strands con Python, invocar un agente es una llamada síncrona (agent("...")) y el session manager que se le pasa al crearlo guarda la conversación y el state por su cuenta. En ADK el control es explícito: se crea la sesión, se ejecuta y se vuelve a leer.
➡ State: el prefijo define cuánto dura cada dato
El state de una sesión es un diccionario que comparten agentes, tools y nodos. El prefijo de la clave define su alcance:
| Prefijo | Alcance | Ejemplo de uso |
|---|---|---|
| Sin prefijo | La sesión actual | El progreso de una tarea o un resultado que se va acumulando |
user: |
Todas las sesiones del mismo usuario | Preferencias o datos del perfil |
app: |
Todos los usuarios y sesiones de la app | Configuración global |
temp: |
Una sola invocación | Datos intermedios que no hace falta guardar |
def accumulate_graph(ctx: Context, node_input):
ctx.state["kg_accumulated"] = graph # session: the next message extends it
ctx.state["user:last_paper"] = title # user: shared across this user's sessions
ctx.state["temp:partial_graphs"] = parts # temp: discarded after this invocation
Con InMemorySessionService, todo esto vive en la memoria del proceso. Para que user: y app: sobrevivan a un reinicio hace falta un servicio persistente, como DatabaseSessionService.
➡ adk web: la herramienta que marca la diferencia
adk web es una interfaz de desarrollo local, se levanta una app estilo chat en el navegador que muestra, para cada mensaje, el grafo del workflow, el state de la sesión, los eventos y las trazas con tokens y tiempos. En la documentación de Strands no hay un equivalente. Más abajo muestro cómo se visualiza con el caso práctico.
Multiagente: grafos en ADK y patrones en Strands
ADK 2.x ofrece varias formas de coordinar agentes (workflows):
-
Workflows basados en grafos (
Workflow): nodos y aristas definidos en código. Un nodo puede ser un agente LLM, una función Python o una tool, y las aristas pueden tener rutas condicionales. Es la forma recomendada en ADK 2.x (graphs). -
Workflows dinámicos: la orquestación se escribe en código y los nodos se lanzan con
ctx.run_node, por ejemplo uno por cada fragmento de un documento. -
Delegación guiada por el LLM: el agente padre transfiere el control a un sub-agente, o llama a otro agente como tool con
AgentTool.
Las clases de plantilla SequentialAgent, ParallelAgent y LoopAgent todavía funcionan, pero en el código de ADK 2.12 están marcadas como deprecated. Si se arranca un proyecto nuevo, usar Workflow.
Strands ordena lo mismo en patrones: Agents as tools, Graph, Swarm y Workflow, más un wrapper para implementar A2A que permite usar un agente remoto igual que uno local. Lo que los distingue de acuerdo a mis prácticas, es cómo se determina el camino de ejecución: en Graph se definen nodos y aristas con condiciones opcionales, en Swarm los agentes se pasan el control por su cuenta de manera autonoma, y Workflow es un grafo de tareas con dependencias.
Para comparar los dos frameworks conviene ordenar sus mecanismos con una sola pregunta: ¿quién decide el siguiente paso? En un extremo lo decide el código escrito por el desarrollador; en el otro, el modelo en tiempo de ejecución.
Posición orientativa según la documentación oficial de cada framework.
- AgentTool (ADK) y Agents as tools (Strands) son el mismo patrón. El agente principal llama a un especialista como si fuera una tool, recibe su respuesta y sigue al mando. El modelo decide a quién llamar, pero el control vuelve siempre al orquestador.
-
La transferencia (ADK) y Swarm (Strands) van un paso más allá, el agente cede la conversación a otro y deja de participar. En ADK, el LLM lo hace llamando a una tool interna,
transfer_to_agent, y elige el destino según la descripción de cada sub-agente. En Swarm, los agentes se pasan el control entre sí sin un orquestador central.
| Mecanismo | En ADK | En Strands | Quién decide |
|---|---|---|---|
| Orden fijo con dependencias |
Workflow (grafo) |
Workflow, Graph | El código |
| Orden decidido en código durante la ejecución | Workflow dinámico (ctx.run_node) |
Graph con condiciones | El código, con datos de la ejecución |
| Un agente consulta a otro y retoma el control | AgentTool |
Agents as tools | El modelo elige a quién consultar |
| Un agente cede la conversación a otro | Transferencia (transfer_to_agent) |
Swarm | El modelo |
Caso de uso: un knowledge graph con ADK y Strands
Para comparar con algo concreto, reescribí en ADK el pipeline de mi artículo sobre Graph en Strands: el ejemplo toma el abstract de un paper y lo convierte en un knowledge graph, una lista de entidades y relaciones sujeto → predicado → objeto. Sirve para resumir quién hizo qué en un texto, conectar conocimiento entre documentos o alimentar una base de grafos.
📦 El código Python original en Strands está en strands-graph.
📦 El repositorio de la versión ADK está en adk-knowledge-graph.
Todo el detalle (instalación, pruebas, evals, despliegue con Terraform, costos y limpieza) está en el README del repositorio.
La topología es la misma en los dos frameworks: tres extractores en paralelo, un agregador que une sus resultados y un validador que puede devolver el borrador para revisión.
Cada agente LLM tiene su color; los nodos de código (funciones y JoinNode) tienen borde punteado.
En ADK, el grafo completo se declara en un solo lugar:
root_agent = Workflow(
name="kg_pipeline",
edges=[
("START", split_text),
*[(split_text, extractor, join_extractions) for extractor in extractors],
(join_extractions, aggregator, validator, route_verdict),
# Back-edge: a cycle needs at least one routed edge
(route_verdict, {"revise": aggregator, "publish": publish_graph}),
],
)
Qué resuelve ADK de otra manera
| Necesidad | Strands (Graph, Python) | ADK (Workflow) |
|---|---|---|
| Esperar a los 3 extractores | El default es OR: el nodo se dispara cuando termina cualquier predecesor. Hay que escribir una condición all_dependencies_complete() en cada arista del grafo |
JoinNode espera a todos los predecesores |
| Pasos que no necesitan un LLM | El coordinator y el publisher eran agentes |
split_text, route_verdict y publish_graph son funciones Python: deterministas y sin tokens |
| Salir del loop de revisión | Condiciones en las aristas que leen la salida del validador | Un nodo de código que emite Event(route="revise") o Event(route="publish")
|
| Ver qué pasó | Logs y trazas | Cada ejecución lleva su número de iteración (aggregator@2) y adk web muestra el grafo |
En Strands con TypeScript el default de Graph es AND, así que el problema del join es propio del SDK de Python.
Lo que aprendí construyendo el knowledge graph con ADK
El repositorio tiene dos versiones del multiagente: la del pipeline fijo de tres extractores (kg_pipeline), que es la que se compara con Strands, y una versión ampliada para textos largos (kg_pipeline_docs), que divide el documento en fragmentos, lanza un extractor por fragmento y va acumulando el grafo entre mensajes. La versión ampliada es la que después despliego en AWS.
En el pipeline fijo (kg_pipeline)
-
El código decide, el LLM propone. En una corrida, el validador (Nova 2 Lite) aprobó con
consistent: trueun grafo con 4 entidades usadas en relaciones pero ausentes de la lista.route_verdictlo detectó con un chequeo en código, devolvió el borrador al agregador con el problema puntual y la segunda pasada lo corrigió. Un validador LLM chico no alcanza: los controles críticos van en código. - No pedirle a un LLM que copie JSON. El publisher como agente corrompía el grafo; como función es determinista y no gasta tokens.
- Un modelo más grande no siempre rinde más. Con el mismo abstract, Nova Pro extrajo menos relaciones que Nova 2 Lite (30 frente a 44) y generó más entidades compuestas. El diseño del grafo y los controles en código pesaron más que el modelo.
En la versión ampliada para textos largos (kg_pipeline_docs)
-
El paralelismo puede ser estático o dinámico. Con tres extractores fijos, el paralelismo está en el grafo y se ve en el diagrama. La versión ampliada lanza un extractor por fragmento con
ctx.run_node, ese paralelismo no aparece en el diagrama, solo en las trazas. -
Una respuesta vacía del modelo llega como
None, sin error. ADK no lanza una excepción, y un fragmento se perdía en silencio. La solución fue tratarNonecomo fallo, reintentar una vez y, si persiste, registrar el fragmento como fallido. -
Un LLM buscando alias libremente inventa uniones. Nova 2 Lite propuso unir
deep learningconai researchymilaconmontreal. La solución fue que el código genere los candidatos con reglas genéricas y el LLM solo confirme o descarte cada par. -
El state permite un grafo incremental. La versión ampliada guarda el grafo en el state de la sesión, sin prefijo (ver la sección sobre state en Conceptos clave), así que cada mensaje en la misma sesión amplía el grafo de los anteriores. En una prueba local, al enviar el abstract y después la introducción del mismo paper, el grafo pasó de 5 a 32 relaciones y unió las entidades que aparecían en los dos textos. Una sesión nueva empieza de cero; con el prefijo
user:el grafo se podría retomar en otra sesión. - Fragmentos más chicos dieron pocas relaciones más. En la introducción del paper, bajar de 350 a 150 palabras por fragmento aumentó las relaciones un 24%, con 2,5 veces más llamadas al modelo.
ADK Web: testing sin construir un frontend
adk web levanta una interfaz en el navegador (por defecto en http://localhost:8000) para conversar con los agentes y ver qué hacen por dentro (interfaz web). Se ejecuta desde el directorio padre de la carpeta del agente.
Con un Workflow, la interfaz dibuja el grafo y resalta el nodo del evento seleccionado en el panel de eventos. Además muestra el state de la sesión y una vista de trazas con cada llamada al modelo, sus tokens y su duración.
En la traza se ve el paralelismo: los tres extractores corren al mismo tiempo, unos 2 segundos cada uno, y la ejecución completa tarda 5 segundos. En la primera ejecución de cada proceso no es así: un extractor arranca y los otros dos esperan unos 7 segundos, mientras se inicializa el cliente de Bedrock (LiteLLM, boto3, credenciales y conexión TLS).
ADK Web es solo para desarrollo, por eso escucha en
127.0.0.1por defecto. Para producción se usaadk api_servero un servicio propio. En la documentación de Strands no hay una interfaz local equivalente: la observabilidad se resuelve con trazas OpenTelemetry que se exportan a la herramienta que se prefiera. Es la diferencia de experiencia de desarrollo más grande entre los dos frameworks.
Evaluación
Los dos frameworks evalúan con el mismo esquema: casos de prueba, el agente que se ejecuta y un evaluador que puntúa el resultado. Cambia dónde vive cada parte:
| ADK | Strands | |
|---|---|---|
| Paquete | Incluido en google-adk (extra [eval]) |
SDK aparte (strands-agents-evals) |
| Casos de prueba | Archivo JSON (evalset); también se crean desde la pestaña Eval de adk web, guardando una conversación correcta |
Objetos Case en Python, dentro de un Experiment
|
| Cómo se ejecuta |
adk eval o la interfaz web |
Código Python o la CLI strands-evals run
|
| Evaluadores | Criterios configurables: coincidencia con la respuesta esperada, trayectoria de tools, juez LLM (en la doc. como experimental) | Familias de evaluadores: calidad, seguridad, uso de tools, deterministas y propios |
Lo que probé en cada uno:
-
En Strands (mi repo de Graph) usé
OutputEvaluatorcon una rúbrica y métricas propias de precisión y recall. ElCorrectnessEvaluatorque quería usar pide un objetoSessionde Strands, que no encajaba con un grafo multiagente, así que lo reemplacé por un segundoOutputEvaluatorcon rúbrica de referencia. -
En ADK armé un evalset con el resultado esperado y corrí
adk evalcon un modelo de Bedrock como juez ("judge_model": "bedrock/..."). El caso pasó, y el reporte sumó llamadas al modelo, tokens y duración.
Principales diferencias: ADK vs Strands
| Aspecto | Google ADK | Strands |
|---|---|---|
| Origen | Google, open source | AWS, open source (publicado en mayo de 2025, nacido en los equipos de Amazon Q Developer) |
| Lenguajes | Python, TypeScript, Go, Java, Kotlin | Python y TypeScript |
| Filosofía | Grafo de nodos y aristas definido en código | Orquestación guiada por el modelo, con patrones opcionales |
| Multiagente |
Workflow (grafos y dinámicos), AgentTool, transferencia a sub-agentes |
Agents as tools, Graph, Swarm, Workflow y A2A |
| Definir una tool | Función Python con type hints y docstring | Decorador @tool
|
| State | Integrado: output_key, plantillas {clave} y prefijos user:, app:, temp:
|
agent.state; en Graph y Swarm, invocation_state compartido |
| Sesiones e invocación | Asíncronas: await create_session, runner.run_async y volver a leer la sesión. Servicios en memoria, SQLite, base SQL o Vertex AI; ADK 2.12 no incluye uno sobre S3 ni DynamoDB |
Invocación síncrona (agent("...")) y un session manager que persiste solo: SnapshotSessionManager con almacenamiento local o S3 (FileSessionManager y S3SessionManager para Graph y Swarm) |
| Interfaz de desarrollo |
adk web con chat, grafo, state, eventos, trazas y evaluación |
Trazas con OpenTelemetry |
| Modelos | Gemini primero; otros vía LiteLLM, Ollama, vLLM | Amazon Bedrock primero; admite otros proveedores |
| Despliegue documentado | Agent Runtime, Cloud Run, GKE y cualquier contenedor | AgentCore, Lambda, Fargate, App Runner, EKS, EC2, Docker, Kubernetes, Terraform |
| Interoperabilidad | Protocolo A2A y MCP | Protocolo A2A y MCP |
Dónde gana ADK
En todo lo que muestra la tabla "Qué resuelve ADK de otra manera": el join sin código extra, la lógica determinista dentro del grafo, los loops con salida en código y adk web para depurar.
Dónde gana Strands
- Menos código para empezar: un agente con tools y el modelo decide.
- Integración nativa con AWS: Bedrock como modelo por defecto y una guía oficial por cada destino de despliegue, incluido AgentCore (despliegue de Strands).
- Sesiones persistentes en archivos o en S3 de fábrica, sin manejar la sesión a mano: el session manager guarda todo al invocar el agente.
Lo que cuesta de ADK
- La curva de aprendizaje de entrada: sesiones asíncronas, un state que se lee como copia y plantillas con reglas propias.
- Algunas tools integradas dependen de Gemini (
google_search,BuiltInCodeExecutor). - La documentación de despliegue está escrita para Google Cloud.
- La documentación todavía muestra las clases de plantilla que el código ya marca como deprecadas.
Cómo implementar ADK en AWS
ADK es una librería, no un servicio de Google. La documentación oficial indica que el agente se puede empaquetar y ejecutar en cualquier entorno que admita contenedores. En AWS hay tres destinos naturales:
| Destino | Cuándo elegirlo | Qué cuidar |
|---|---|---|
| Bedrock AgentCore Runtime | Agentes con sesiones, tráfico bajo o en ráfagas, sin servidores que administrar | El paquete corre en linux/arm64; cada sesión vive en su propia microVM con un tiempo límite |
| AWS Lambda (imagen de contenedor) | Invocaciones puntuales y sin estado |
google-adk supera el límite de 250 MB del zip: hay que usar una imagen en ECR (hasta 10 GB). Detrás de API Gateway, el límite general es de 29 s |
| ECS Fargate con ALB | Tráfico alto y constante, ejecuciones largas | Un contenedor siempre encendido, con health check y escalado |
Para el knowledge graph elegí AgentCore Runtime, y desplegué la versión ampliada para textos largos (kg_pipeline_docs), porque es la que acumula el grafo entre mensajes. Pensé en cómo se usaría el agente: un investigador abre un proyecto, pega secciones de un paper y ve crecer el grafo. Son pocos usuarios, cada pedido tarda entre 5 y 20 segundos y el grafo tiene que durar mientras trabaja. Un contenedor encendido todo el día no se justifica, y AgentCore resuelve las sesiones por su cuenta.
Una aclaración sobre la comparación con Strands: mi versión en Strands (strands-graph) la construí para aprender orquestación y la probé solo en local, así que no la desplegué en AgentCore. Lo que se afirma sobre el despliegue de Strands se apoya en su documentación oficial, no en una prueba propia.
Cómo encaja la sesión de ADK con la de AgentCore
AgentCore ejecuta cada runtimeSessionId en su propia microVM y mantiene el contexto entre invocaciones. Si ese id se usa como session_id de ADK, el InMemorySessionService vive en la memoria de esa microVM y el grafo incremental crece entre llamadas, sin base de datos.
Rol IAM acotado para todo el recorrido: leer el zip, invocar solo Nova 2 Lite y escribir logs.
El adaptador sigue el ejemplo oficial de AWS para ADK (Use any agent framework). Lo único propio es usar el id de sesión de AgentCore:
app = BedrockAgentCoreApp()
sessions = InMemorySessionService() # lives as long as the AgentCore session microVM
runner = Runner(agent=root_agent, app_name=APP_NAME, session_service=sessions)
@app.entrypoint
async def invoke(payload, context):
text = validate_prompt(payload) # rejects empty or oversized input
session_id = context.session_id # AgentCore runtimeSessionId -> ADK session
if await sessions.get_session(app_name=APP_NAME, user_id=USER_ID, session_id=session_id) is None:
await sessions.create_session(app_name=APP_NAME, user_id=USER_ID, session_id=session_id)
message = types.Content(role="user", parts=[types.Part(text=text)])
async for _ in runner.run_async(user_id=USER_ID, session_id=session_id, new_message=message):
pass
session = await sessions.get_session(app_name=APP_NAME, user_id=USER_ID, session_id=session_id)
return build_response(session.state) # graph, unlinked entities, texts processed
app.run()
La infraestructura: un zip y tres recursos en Terraform
AgentCore admite dos formas de desplegar: una imagen de contenedor en ECR o un zip con el código en S3 (despliegue directo de código). Elegí el zip porque no hace falta Docker y el paquete entra holgado en el límite de 250 MB: pesa unos 72 MB.
Terraform crea:
- un bucket S3 privado y con versionado para el zip;
- un rol IAM que solo puede leer ese zip, invocar Nova 2 Lite y escribir logs y trazas;
- el runtime de AgentCore (
aws_bedrockagentcore_agent_runtime).
El recurso del runtime es el centro de la configuración:
resource "aws_bedrockagentcore_agent_runtime" "agent" {
agent_runtime_name = "kg_pipeline_docs"
role_arn = aws_iam_role.runtime.arn
agent_runtime_artifact {
code_configuration {
entry_point = ["opentelemetry-instrument", "agentcore_app.py"]
runtime = "PYTHON_3_13"
code {
s3 {
bucket = aws_s3_bucket.code.id
prefix = aws_s3_object.package.key
version_id = aws_s3_object.package.version_id # a new zip version updates the runtime
}
}
}
}
environment_variables = {
MODEL_PROVIDER = "bedrock"
BEDROCK_MODEL_ID = var.bedrock_model_id
AWS_REGION_NAME = var.region # read by LiteLLM for Bedrock calls
# Unified telemetry: spans go to the "spans" stream of the runtime log group (needs ADOT >= 0.18)
UNIFIED_TRACES_DESTINATION_ENABLED = "true"
}
lifecycle_configuration {
idle_runtime_session_timeout = 900 # 15 min without activity
max_lifetime = 3600 # 1 h at most
}
network_configuration {
network_mode = "PUBLIC"
}
}
Dos detalles de esa configuración. El provider de AWS debe ser ~> 6.22: el recurso existe desde la 6.17, pero code_configuration (el despliegue con zip) llegó en la 6.22, y con una versión anterior el código no compila. Y network_mode = "PUBLIC" es lo que usé en la prueba; no probé el modo VPC, que sería lo que habría que evaluar antes de llevar algo así a producción.
La seguridad del rol vale una mirada más detallada, porque es lo que el plan permite revisar. Dos extractos de main.tf:
# Only AgentCore resources of this account can assume the role (confused-deputy protection)
condition {
test = "StringEquals"
variable = "aws:SourceAccount"
values = [local.account_id]
}
# The role can invoke only the Nova 2 Lite inference profile and the model it routes to
statement {
sid = "BedrockNovaInvocation"
actions = ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"]
resources = [
"arn:aws:bedrock:${var.region}:${local.account_id}:inference-profile/${var.bedrock_model_id}",
"arn:aws:bedrock:*::foundation-model/${local.foundation_model_id}",
]
}
Para ser más específica en cuanto a lo "acotado" del rol, este lee un único objeto de S3 y solo invoca ese modelo, pero X-Ray usa resources = ["*"] y PutMetricData va con * limitado por el namespace bedrock-agentcore. Son comodines que la documentación de AgentCore permite en esos servicios, pero no son un mínimo privilegio absoluto. Y quien invoca el runtime también necesita permisos IAM propios: el script de invocación del repositorio invoke.py usa boto3, así que las credenciales del usuario deben permitir bedrock-agentcore:InvokeAgentRuntime.
Inconvenientes con los que me encontré
Las dependencias se instalan para Linux arm64 aunque el zip se arme en Windows o macOS, con
pip install --platform manylinux2014_aarch64 --only-binary=:all:. Pero pip genera los scripts de consola para la máquina donde corre: en Windows, archivos.exeque no sirven en AgentCore. El script de empaquetado los regenera como lanzadores de Linux.El log group del runtime queda con retención indefinida. Lo crea AgentCore con el id del runtime en el nombre, así que Terraform no puede crearlo antes, y la retención a nivel cuenta exige un mínimo de 30 días. La solución fue un terraform_data que, creado el runtime, fija la retención en 1 día con la AWS CLI y borra el log group en terraform destroy.
Observar el recorrido de los agentes en AgentCore
ADK ya genera trazas de OpenTelemetry (spans) por cada nodo, agente y llamada al modelo: las mismas que muestra adk web. Para verlas en la consola de AgentCore no hace falta escribir código de trazas, alcanzó con dos pasos:
- incluir ADOT en el paquete (
aws-opentelemetry-distro) y arrancar el agente con el prefijoopentelemetry-instrument, como en elentry_pointde arriba - activar CloudWatch Transaction Search en la cuenta, una sola vez por región. Sin esto, el agente genera la telemetría pero los spans no se guardan y el dashboard queda vacío.
Los nodos del workflow aparecen con los mismos nombres que en el código, con el modelo y los tokens de cada llamada.
El resultado
En la prueba con la versión ampliada, tres textos del mismo paper llevaron el grafo de 9 a 40 y a 74 relaciones, y la tercera invocación, hecha en un comando aparte, conservó las 40 anteriores. La limitación: AgentCore cierra la microVM tras 15 minutos sin actividad (o 1 hora de vida, según la configuración), y una invocación posterior con el mismo id empieza con el grafo vacío. Para conservarlo hay que guardarlo fuera de la sesión, por ejemplo en S3 o con AgentCore Memory. El costo de la prueba fue mínimo: unos USD 0,01 en tokens por texto largo y menos de USD 0,01 por sesión de AgentCore.
Conclusiones
-
Elegir ADK cuando el flujo tiene pasos, joins y loops que se quieren controlar en código, con funciones deterministas dentro del grafo, y cuando sirve depurar con
adk websin armar un frontend. - Elegir Strands cuando se busca el camino más corto en AWS: un agente con tools, Bedrock como modelo y una guía de despliegue por cada destino.
- Se pueden combinar. AgentCore Runtime no depende del framework y A2A permite que un agente ADK y uno Strands se hablen como servicios separados.
⭐ La lección se repite después de construir el mismo pipeline con ADK y Strands: el framework importa menos que el harness determinista que rodea a los agentes. En este caso de uso, ese harness son los nodos de código que dividen la entrada, validan la salida, deciden las rutas y cortan los bucles. El modelo propone, pero es el harness el que decide qué se acepta.



Top comments (0)