Integrando Agentes Externos

Edison Watch proporciona APIs y SDKs para integrar agentes de IA externos, permitiéndole rastrear llamadas a herramientas, hacer cumplir políticas de seguridad y monitorear la actividad de agentes en tiempo real.

Prerrequisitos

Antes de integrar su agente:

1. Servidor Edison Watch debe estar ejecutándose y ser accesible
2. Clave API del panel de control (Configuración → API Keys)
3. Python 3.8+ (para SDK de Python) o cliente HTTP (para API directa)

Inicio Rápido (Python/LangGraph)

La forma más rápida de integrar es usando el SDK de Python edison-watch con el decorador @edison.track().

Instalación

pip install edison-watch langgraph langchain-openai

Variables de Entorno

Establezca estas variables de entorno (o páselas al constructor Edison):

export EDISON_WATCH_API_BASE="https://dashboard.edison.watch"  # Su URL del servidor Edison Watch
export EDISON_WATCH_API_KEY="your_api_key_here"
export OPENAI_API_KEY="your_openai_key"  # para ejemplos de LangChain

Integración Mínima

Añada solo 4 líneas para rastrear las llamadas a herramientas de su agente:

from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from edison_watch import Edison
 
# Inicializar Edison (lee EDISON_WATCH_API_KEY del entorno)
edison = Edison()
 
@tool
@edison.track()  # auto-nombra: agent_web_search
def web_search(query: str, max_results: int = 3) -> str:
    """Return up to N result URLs."""
    return "https://docs.python.org/3/"
 
@tool
@edison.track()  # auto-nombra: agent_fetch_url
def fetch_url(url: str, max_chars: int = 1000) -> str:
    """Fetch and return the first max_chars of the page."""
    import httpx
    return httpx.get(url, follow_redirects=True, timeout=10).text[:max_chars]
 
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
agent = create_react_agent(model=llm, tools=[web_search, fetch_url])
 
result = agent.invoke({
    "messages": [("user", "Fetch the first 1000 chars of the CPython docs homepage.")]
})
print(result["messages"][-1].content)

El decorador @edison.track() automáticamente:

• Envía metadatos de llamada a herramienta a Edison Watch antes de la ejecución
• Espera aprobación si la llamada activa políticas de seguridad
• Registra duración y resultado después de la ejecución
• Aparece en la línea de tiempo del panel de control

Registrando Agentes (Opcional)

Puede registrar opcionalmente agentes con nombre en Edison Watch para una mejor organización y rastreo. Esto es útil al gestionar múltiples tipos de agentes o roles.

Crear un Agente

curl -X POST https://dashboard.edison.watch/api/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "name": "hr_assistant",
    "agent_type": "hr"
  }'

Respuesta:

{
  "ok": true,
  "agent": {
    "id": 1,
    "name": "hr_assistant",
    "agent_id": "agent:a1b2c3d4e5f6...",
    "agent_type": "hr",
    "user_id": "user-uuid",
    "created_at": "2025-01-15T10:30:00",
    "updated_at": "2025-01-15T10:30:00"
  }
}

El agent_id se genera automáticamente en el formato agent:HEX (32 caracteres hexadecimales).

Listar Agentes

curl -X GET https://dashboard.edison.watch/api/agents \
  -H "Authorization: Bearer your_api_key"

Respuesta:

{
  "agents": [
    {
      "name": "hr_assistant",
      "agent_id": "agent:a1b2c3d4e5f6...",
      "agent_type": "hr",
      "created_at": "2025-01-15T10:30:00"
    }
  ]
}

Eliminar un Agente

curl -X DELETE https://dashboard.edison.watch/api/agents/hr_assistant \
  -H "Authorization: Bearer your_api_key"

Respuesta:

{
  "ok": true,
  "message": "Agent 'hr_assistant' deleted successfully"
}

Referencia del SDK de Edison

La clase Edison proporciona un SDK de Python para rastrear actividad de agentes.

Constructor

from edison_watch import Edison
 
edison = Edison(
    api_base: str | None = None,           # Lee de EDISON_WATCH_API_BASE si no se provee
    api_key: str | None = None,             # Lee de EDISON_WATCH_API_KEY si no se provee
    timeout_s: float = 30.0,                 # Tiempo de espera de aprobación
    healthcheck: bool = True,                # Verificaciones de salud en segundo plano
    healthcheck_timeout_s: float = 3.0,      # Tiempo de espera de verificación de salud
    agent_name: str | None = None,          # Identidad del agente (ej. 'hr_assistant')
    agent_type: str | None = None,           # Tipo/rol del agente (ej. 'hr', 'engineering')
    session_id: str | None = None            # ID de sesión fijo (auto-generado si es None)
)

Variables de Entorno:

• EDISON_WATCH_API_BASE: URL del servidor (requerido - establezca esto a su servidor Edison Watch)
• EDISON_WATCH_API_KEY: Clave API para autenticación (requerido)

Si no se proporcionan como argumentos del constructor, estos valores se leen de las variables de entorno.

Decorador de Rastreo

El decorador @edison.track() envuelve funciones para rastrear su ejecución:

@edison.track()
def my_tool(arg1: str, arg2: int) -> str:
    """Tool description."""
    return "result"

Parámetros:

• session_id: Anular el ID de sesión para esta llamada
• name: Anular el nombre de la herramienta (por defecto es el nombre de la función)

Comportamiento:

• Llama a /agent/begin antes de la ejecución (control + espera de aprobación)
• Ejecuta la función
• Llama a /agent/end después de la ejecución con estado, duración y resumen del resultado
• Lanza PermissionError si está bloqueado y no aprobado

Envolviendo Herramientas LangChain

Para herramientas LangChain, use wrap_tools():

from langchain_core.tools import tool
 
@tool
def search_codebase(query: str) -> str:
    """Search the codebase."""
    return "results..."
 
tools = [search_codebase]
tracked_tools = edison.wrap_tools(tools)

O use bind_tools() para envolver y vincular en un paso:

llm = ChatOpenAI()
llm_with_tools = edison.bind_tools(llm, tools)

Gestión de Sesiones

Las sesiones agrupan llamadas a herramientas relacionadas. Por defecto, cada instancia de Edison crea un ID de sesión único, pero puede compartir sesiones:

# Compartir sesión a través de múltiples instancias Edison
shared_session = str(uuid.uuid4())
 
edison1 = Edison(session_id=shared_session, agent_name="agent1")
edison2 = Edison(session_id=shared_session, agent_name="agent2")

También puede anular la sesión por llamada:

@edison.track(session_id="custom-session-id")
def my_tool():
    pass

API HTTP Directa (No-Python)

Si no está usando Python, puede integrar directamente vía endpoints HTTP.

Iniciar Rastreo de una Llamada a Herramienta

curl -X POST https://dashboard.edison.watch/agent/begin \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "session_id": "optional-session-id",
    "name": "web_search",
    "args_summary": "query: '\''python docs'\''",
    "timeout_s": 30.0,
    "agent_name": "hr_assistant",
    "agent_type": "hr"
  }'

Respuesta:

{
  "ok": true,
  "session_id": "uuid-here",
  "call_id": "call-uuid-here",
  "approved": true,                         # false si está bloqueado, null en error
  "error": null                             # Mensaje de error si ok=false
}

Códigos de Estado:

• 200 OK: Solicitud procesada (verifique campo approved)
• 400 Bad Request: Cuerpo de solicitud inválido
• 401 Unauthorized: Clave API faltante o inválida

Importante: Si approved es false, la llamada a la herramienta fue bloqueada por políticas de seguridad. Espere aprobación manual en el panel, o maneje el error apropiadamente.

Completar Rastreo

Después de ejecutar la herramienta, llame a /agent/end:

curl -X POST https://dashboard.edison.watch/agent/end \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "session_id": "uuid-from-begin",
    "call_id": "call-uuid-from-begin",
    "status": "ok",
    "duration_ms": 125.5,
    "result_summary": "Found 3 results..."
  }'

Respuesta:

{
  "ok": true
}

Normalización de Nombre de Herramienta

Los nombres de herramientas se prefijan automáticamente con agent_ si no comienzan ya con builtin_ o agent_:

• web_search → agent_web_search
• agent_my_tool → agent_my_tool (sin cambios)
• builtin_system → builtin_system (sin cambios)

Ejemplo: Integración Completa

async function trackToolCall(toolName, args, executeFn) {
  // EDISON_WATCH_API_BASE debe establecerse en su entorno
  const apiBase = process.env.EDISON_WATCH_API_BASE;
  if (!apiBase) {
    throw new Error('EDISON_WATCH_API_BASE environment variable is required');
  }
  const apiKey = process.env.EDISON_WATCH_API_KEY;
 
  // Begin tracking
  const beginResponse = await fetch(`${apiBase}/agent/begin`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      name: toolName,
      args_summary: JSON.stringify(args),
      agent_name: 'my_agent',
      agent_type: 'custom'
    })
  });
 
  const beginData = await beginResponse.json();
 
  if (!beginData.ok || !beginData.approved) {
    throw new Error(`Tool call blocked: ${beginData.error}`);
  }
 
  const startTime = performance.now();
  let status = 'ok';
  let result;
 
  try {
    // Execute the tool
    result = await executeFn();
  } catch (error) {
    status = 'error';
    throw error;
  } finally {
    const duration = performance.now() - startTime;
 
    // End tracking
    await fetch(`${apiBase}/agent/end`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        session_id: beginData.session_id,
        call_id: beginData.call_id,
        status: status,
        duration_ms: duration,
        result_summary: JSON.stringify(result).substring(0, 1000)
      })
    });
  }
 
  return result;
}
 
// Usage
const result = await trackToolCall(
  'web_search',
  { query: 'python docs' },
  async () => {
    // Your tool implementation
    return 'search results...';
  }
);

Configuración Multi-Agente

Al ejecutar múltiples agentes con diferentes roles o permisos, cree instancias Edison separadas con agent_name y agent_type distintos:

from edison_watch import Edison
import uuid
 
# HR Assistant
edison_hr = Edison(
    agent_name="hr_assistant",
    agent_type="hr",
    session_id=str(uuid.uuid4()),
    api_key=api_key,
    api_base=api_base
)
 
# Engineering Copilot
edison_eng = Edison(
    agent_name="eng_copilot",
    agent_type="engineering",
    session_id=str(uuid.uuid4()),
    api_key=api_key,
    api_base=api_base
)
 
# Use diferentes instancias para diferentes agentes
@edison_hr.track()
def hr_get_employee_profile(employee_id: str) -> str:
    """HR tool."""
    return f"Profile for {employee_id}"
 
@edison_eng.track()
def eng_search_codebase(query: str) -> str:
    """Engineering tool."""
    return f"Code search results for {query}"

La actividad de cada agente será rastreada por separado en el panel de control, y puede configurar diferentes permisos por tipo de agente a través de la configuración de permisos del panel.

Configuración de Permisos

Las herramientas rastreadas se nombran con el prefijo agent_ en el sistema de permisos. Configúrelas a través del panel de control de Edison Watch:

1. Navegue a Servers en el panel
2. Encuentre o cree el servidor agent (las herramientas rastreadas vía el SDK aparecen bajo este servidor)
3. Haga clic en cada herramienta para configurar sus permisos

Ajustes de Permiso:

Para cada herramienta, puede configurar:

• Enabled: Si la herramienta tiene permitido ejecutarse
• Write Operation: La herramienta puede modificar datos (ej. enviar email, crear archivo)
• Read Private Data: La herramienta accede a datos internos sensibles
• Read Untrusted Public Data: La herramienta procesa contenido externo/no confiable
• ACL: Nivel de control de acceso (PUBLIC, PRIVATE, SECRET, TOP_SECRET)

Configuración de Ejemplo:

Para una herramienta web_search rastreada como agent_web_search:

• Enabled: ✓
• Write Operation: ✗
• Read Private Data: ✗
• Read Untrusted Public Data: ✓
• ACL: PUBLIC

Para una herramienta send_email rastreada como agent_send_email:

• Enabled: ✓
• Write Operation: ✓
• Read Private Data: ✗
• Read Untrusted Public Data: ✗
• ACL: SECRET

Banderas de Seguridad:

• write_operation: La herramienta puede modificar datos (ej. enviar email, crear archivo)
• read_private_data: La herramienta accede a datos internos sensibles
• read_untrusted_public_data: La herramienta procesa contenido externo/no confiable

Lethal Trifecta: Si una llamada a herramienta combina las tres banderas (datos privados + contenido no confiable + escritura), Edison Watch pausará para aprobación manual.

Niveles ACL:

• PUBLIC: Datos no sensibles
• PRIVATE: Datos confidenciales o internos
• SECRET: Datos altamente sensibles

Cumplimiento: Los datos no pueden fluir de un ACL más alto a uno más bajo (ej. SECRET → PUBLIC).

Vea Estableciendo Permisos para guía detallada de configuración.

Manejo de Errores

Llamadas a Herramientas Bloqueadas

Si una llamada a herramienta es bloqueada por políticas de seguridad:

try:
    result = my_tracked_tool()
except PermissionError as e:
    # Tool was blocked and not approved
    print(f"Blocked: {e}")
    # Wait for approval in dashboard, or handle gracefully

Errores de Red

El SDK maneja los errores de red con gracia y los registra. Si Edison Watch es inalcanzable:

• La ejecución de la herramienta continúa (rastreo de mejor esfuerzo)
• Los errores se registran pero no lanzan excepciones
• Las verificaciones de salud se ejecutan en segundo plano para detectar conectividad

Manejo de Tiempo de Espera

Si la aprobación manual excede el tiempo de espera (por defecto: 30 segundos):

edison = Edison(timeout_s=60.0)  # Increase timeout to 60 seconds

El parámetro timeout_s controla cuánto tiempo esperar por aprobación antes de lanzar PermissionError.

Mejores Prácticas

1. Use nombres de agentes descriptivos: hr_assistant, eng_copilot, finance_analyst
2. Establezca tipos de agentes: Agrupe agentes por rol para una gestión más fácil
3. Comparta sesiones apropiadamente: Use el mismo session_id para llamadas a herramientas relacionadas en una conversación
4. Maneje aprobaciones con gracia: Las llamadas bloqueadas deben esperar aprobación o fallar con gracia
5. Configure permisos por adelantado: Configure permisos de herramientas en el panel antes de desplegar agentes
6. Monitoree el panel: Revise la actividad de agentes y ajuste permisos según sea necesario

Solución de Problemas

401 Unauthorized

• Verifique que EDISON_WATCH_API_KEY esté configurada correctamente
• Verifique que la clave API esté activa en el panel

Llamadas a herramientas bloqueadas

• Verifique permisos de herramientas en el panel (Servers → agent → Tools)
• Verifique que el nombre de la herramienta coincida (con prefijo agent_)
• Apruebe llamadas bloqueadas en el panel si es necesario

Llamadas a herramientas no aparecen en el panel

• Verifique que el servidor Edison Watch se esté ejecutando
• Verifique la conectividad de red a api_base
• Revise los registros del servidor en busca de errores

Fallas de verificación de salud

• Asegúrese de que Edison Watch sea accesible en api_base
• Verifique configuraciones de firewall/red
• Verifique que el servidor se esté ejecutando: curl https://dashboard.edison.watch/health