Documentación para desarrolladores de AgentShelf

Construye sobre el runtime de agentes externos de AgentShelf.

SDK de agentes externos

@agentshelf/external-agents-sdk es el SDK público para integrar un agente de AgentShelf en una aplicación que tú controlas. Gestiona el ciclo de vida de la sesión pública, la negociación de políticas, las conversaciones, el streaming, los archivos y los artefactos — siempre mediante refs públicas.

El SDK es un cliente. Nunca crea ni firma una aserción de arranque: eso lo hace tu backend de confianza, que le entrega al SDK un callback para obtenerla. Esa separación es lo que mantiene tus credenciales de AgentShelf fuera del cliente.

import { createExternalAgentClient } from '@agentshelf/external-agents-sdk';

const client = createExternalAgentClient({
  externalAgentRef: 'ext_agent_public_12345678',
  apiBase: 'https://api.agentshelf.ai',
  getBootstrapAssertion: async () => {
    const response = await fetch('/api/agentshelf/bootstrap-assertion');
    return response.text();
  },
});

await client.ensure();

Por dónde empezar

Si quieres…	Lee
Conectar un cliente con el runtime	Primeros pasos
Conservar sesiones entre recargas	Sesiones y almacenamiento
Saber qué puede hacer tu agente	Políticas y capacidades
Dar al agente un espacio de trabajo	Espacios de trabajo
Enviar un turno y mostrar la respuesta	Conversaciones y streaming
Subir archivos o leer artefactos	Archivos y artefactos
Consultar un tipo o método exacto	Referencia de la API

Solo refs públicas

Todo valor que devuelve el SDK es una ref pública. El runtime proyecta su modelo interno antes de que llegue a ti, así que los IDs internos de workspace, runtime y almacenamiento, los nombres de bucket y los IDs de tool binding de AgentShelf nunca se exponen a un cliente. Diseña tu integración en torno a los valores *Ref que recibes: son el contrato estable.