Agent Runtime está diseñado para ser independiente del framework de la aplicación. Si eliges implementar tu agente con un contenedor personalizado o un Dockerfile, el contenedor debe cumplir con el contrato de entorno de ejecución para entregar consultas de forma correcta.
Para obtener más información sobre los métodos de implementación, consulta Implementa un agente.
Restricciones y requisitos
Para implementar un contenedor personalizado en Agent Runtime, el contenedor debe escuchar las solicitudes HTTP en 0.0.0.0 en el puerto 8080.
En el siguiente diagrama de secuencia, se muestra el flujo de solicitudes entre el cliente, el plano de control de Agent Runtime y tu contenedor personalizado:
Descripción de texto: Diagrama de secuencia del flujo de solicitudes
En el diagrama, se ilustran dos flujos de solicitudes entre el cliente (cliente, SDK o consola), el plano de control de Agent Runtime (API de la plataforma de Gemini y plano de control) y el contenedor del usuario que escucha en 0.0.0.0:8080:
- Flujo de consulta unaria:
- El cliente envía
POST /v1/projects/.../reasoningEngines/...:queryal plano de control de Agent Runtime. - El plano de control de Agent Runtime reenvía
POST /api/reasoning_enginecon un sobre JSON al contenedor del usuario (0.0.0.0:8080). - El contenedor del usuario devuelve
HTTP 200 OKcon un sobre JSON al plano de control de Agent Runtime. - El plano de control de Agent Runtime devuelve la carga útil del resultado al cliente.
- El cliente envía
- Flujo de consultas de transmisión:
- El cliente envía
POST /v1/projects/.../reasoningEngines/...:streamQueryal plano de control de Agent Runtime. - El plano de control de Agent Runtime reenvía
POST /api/stream_reasoning_enginecon un sobre JSON al contenedor del usuario (0.0.0.0:8080). - El contenedor del usuario devuelve
HTTP 200 OKcon fragmentos de transmisión de NDJSON al plano de control de Agent Runtime. - El plano de control de Agent Runtime transmite eventos de respuesta de SSE al cliente.
- El cliente envía
Extremos (opcional)
Tu contenedor puede exponer cualquier extremo HTTP personalizado. Puedes invocar estos extremos personalizados enviando solicitudes a la API subyacente del agente implementado. Para obtener más información, consulta Usa agentes implementados a través de su API subyacente.
Si bien estos extremos son opcionales a nivel de API, implementarlos habilita las siguientes funciones de integración:
- Compatibilidad con el SDK de Python: Implementar
/api/reasoning_enginey/api/stream_reasoning_enginete permite usar el agente implementado a través del SDK de Python de Gemini Enterprise Agent Platform. - Compatibilidad con Playground: Es obligatorio implementar
/api/stream_reasoning_enginesi quieres interactuar con tu agente a través de la zona de pruebas de la consola deGoogle Cloud . Para obtener más información, consulta Asistencia de Playground. - Sondeos de estado: Asegurarte de que tu contenedor se vincule a
0.0.0.0:8080y responda con HTTP200 OKen las solicitudes de verificación de estado (por ejemplo,GET /) habilita el sondeo de actividad y preparación por parte del plano de control.
Si quieres usar estas funciones, debes implementar los siguientes extremos:
/api/reasoning_engine: Se usa para entregar consultas enviadas a la API de REST dereasoningEngines/queryo a los métodos de consulta síncronos y asíncronos del SDK de Python./api/stream_reasoning_engine: Se usa para entregar consultas enviadas a la API de REST dereasoningEngines/streamQueryo a los métodos de consulta de transmisión del SDK de Python.
Métodos de clase y modos de ejecución
Cuando implementas un contenedor personalizado, debes declarar los métodos de clase admitidos en la lista classMethods de la especificación de Deployment. Estos métodos de clase corresponden a las operaciones que definiste cuando desarrollaste tu agente (consulta Registra métodos personalizados y Consulta al agente con operaciones compatibles). Cada método declarado tiene un name y un api_mode que determinan cómo se enruta:
| Modo de API | Tipo de ejecución | Extremo de enrutamiento |
|---|---|---|
"" (cadena vacía) o "async" |
Unario (solicitud-respuesta) | /api/reasoning_engine |
"stream" o "async_stream" |
Transmisión | /api/stream_reasoning_engine |
Cuando un cliente invoca un método, el servicio de Agent Runtime envía una solicitud POST al extremo de enrutamiento correspondiente en tu contenedor. El cuerpo JSON de la solicitud contiene el campo class_method (que coincide con el nombre del método) y el campo input.
Métodos obligatorios para la integración
Para usar el SDK de Python o la zona de pruebas de la consola de Google Cloud , tu contenedor debe implementar los métodos específicos que esperan estas integraciones:
- Consulta estándar del SDK: Requiere
query(modo""o"async") ystream_query(modo"stream"o"async_stream"). - Playground: Requiere
stream_query(modo"stream"o"async_stream").
Integración del ADK
Si implementas un agente creado con el Kit de desarrollo de agentes (ADK), puedes crear tu propio contenedor de proxy en el lenguaje de programación y el framework de servidor que elijas. Para admitir el conjunto completo de funciones del ADK, tu contenedor debe implementar los métodos definidos por el contrato del ADK. Para obtener más información, consulta Cómo usar un agente del ADK y Cómo registrar y administrar un agente del ADK.
Puedes consultar la plantilla de AdkApp como una implementación de referencia. Para obtener más información, consulta la documentación de referencia de AdkApp y el código fuente de AdkApp.
Si quieres que Google controle las actualizaciones automáticamente cuando actualices tu versión de ADK, debes usar las herramientas que proporciona ADK para implementar agentes en lugar de escribir tu propio servidor de API. Para obtener más información, consulta la documentación de implementación del ADK.
Especificaciones de la API
Tanto /api/reasoning_engine como /api/stream_reasoning_engine reciben solicitudes HTTP POST con un cuerpo JSON que contiene los siguientes campos:
class_method(cadena): Es el nombre del método del agente subyacente que se invocará (por ejemplo,queryostream_query).input(objeto JSON): Son los argumentos que se pasarán al método de clase especificado.
/api/reasoning_engine (unaria)
- Método de solicitud:
POST - Cuerpo de la solicitud:
json { "class_method": "query", "input": { "message": "What is the capital of France?" } } - Respuesta: Es un objeto JSON que contiene el resultado de la ejecución del agente.
json { "output": "The capital of France is Paris." }
/api/stream_reasoning_engine (transmisión)
- Método de solicitud:
POST - Cuerpo de la solicitud:
json { "class_method": "stream_query", "input": { "message": "Tell me a short story." } } - Respuesta: Un flujo de JSON delimitado por líneas (ndjson), en el que cada línea es un fragmento de la respuesta codificado en JSON.
json {"output": "Once"} {"output": " upon"} {"output": " a time..."}
Extremo del sondeo de keep-alive (opcional)
Si configuras keep_alive_probe en tu implementación, Agent Runtime sondea periódicamente el extremo http_get.path configurado mientras la instancia no tiene solicitudes activas para verificar si las tareas en segundo plano o el estado en la memoria requieren mantener el contenedor activo (hasta max_seconds, un máximo de 3600 segundos después de que se complete la última solicitud).
- Método de solicitud:
GETenhttp_get.path(por ejemplo,/is_busy) enhttp_get.port(el puerto predeterminado es8080). Se sondea cada 10 segundos con un tiempo de espera de solicitud de 1 segundo mientras la instancia está inactiva. - Respuesta de ocupado (
2xx): Devolver cualquier código de estado HTTP200–299indica que el contenedor aún está ocupado y evita la reducción de escala por inactividad hasta que transcurramax_secondsdespués de que se complete la última solicitud.json { "status": "busy" } - Respuesta inactiva (no
2xx): Si se devuelve cualquier código de estado que no sea2xx(por ejemplo,412 Precondition Failedo503 Service Unavailable) o se agota el tiempo de espera de 3 sondeos consecutivos, la instancia inactiva se marca como apta para la reducción de escala. Si falla un sondeo de keep-alive, no se finaliza el procesamiento de solicitudes activas.json { "status": "idle" }
Servidor de la API de ejemplo (Python)
A continuación, se muestra un ejemplo de un servidor de FastAPI en Python que implementa el
contrato de entorno de ejecución de Agent Platform. Este servidor une un agente de ejemplo
(SimpleAgent) y controla el enrutamiento y la codificación. Puedes reemplazar
SimpleAgent por tu propia implementación de agente.
Para ejecutar este ejemplo, asegúrate de tener instalados fastapi, uvicorn y pydantic.
import inspect
import json
import logging
import os
import uvicorn
from fastapi import FastAPI, encoders, responses
from pydantic import BaseModel
app = FastAPI()
# Define the request body structure
class QueryRequest(BaseModel):
input: dict | None = None
class_method: str
# Example Agent implementation
class SimpleAgent:
def query(self, message: str) -> str:
return f"Echo: {message}"
async def stream_query(self, message: str):
words = message.split()
for word in words:
yield {"output": word + " "}
agent = SimpleAgent()
def _encode_chunk_to_json(chunk):
"""Encodes a chunk to a JSON string with a newline."""
try:
json_chunk = encoders.jsonable_encoder(chunk)
return json.dumps(json_chunk) + "\n"
except Exception:
logging.exception("Failed to encode chunk")
return None
async def json_generator(output):
async for chunk in output:
encoded_chunk = _encode_chunk_to_json(chunk)
if encoded_chunk is None:
break
yield encoded_chunk
async def _invoke_callable_or_raise(invocation_callable, invocation_payload):
if inspect.iscoroutinefunction(invocation_callable):
return await invocation_callable(**invocation_payload)
else:
return invocation_callable(**invocation_payload)
@app.get("/")
def health_check():
"""Health check endpoint for container readiness."""
return {"status": "ok"}
@app.post("/api/reasoning_engine")
async def query_endpoint(request: QueryRequest) -> responses.JSONResponse:
try:
method = getattr(agent, request.class_method)
except AttributeError:
return responses.JSONResponse(
status_code=400,
content={"error": f"Method {request.class_method} not found on agent"}
)
output = await _invoke_callable_or_raise(method, request.input or {})
try:
json_serialized_content = encoders.jsonable_encoder({"output": output})
except ValueError as encoding_error:
logging.exception("Failed to JSON-encode response: %s", encoding_error)
raise encoding_error
return responses.JSONResponse(content=json_serialized_content)
@app.post("/api/stream_reasoning_engine")
async def stream_query_endpoint(request: QueryRequest) -> responses.StreamingResponse:
try:
method = getattr(agent, request.class_method)
except AttributeError:
return responses.StreamingResponse(
content=iter([json.dumps({"error": f"Method {request.class_method} not found"})]),
status_code=400,
media_type="application/json"
)
output = await _invoke_callable_or_raise(method, request.input or {})
return responses.StreamingResponse(
content=json_generator(output),
media_type="application/json",
)
@app.get("/is_busy")
def keep_alive_endpoint() -> responses.JSONResponse:
"""Optional keep-alive probe endpoint for background tasks."""
if getattr(agent, "has_active_background_tasks", False):
return responses.JSONResponse(status_code=200, content={"status": "busy"})
return responses.JSONResponse(status_code=412, content={"status": "idle"})
if __name__ == "__main__":
# The container must listen on 0.0.0.0 and port 8080
uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))