Un agente es la unidad que AiHummer pone al frente de una conversación. Cada agente tiene una personalidad, su propio modelo, un prompt estructurado y un conjunto de habilidades, y cada cambio en él se versiona. Los agentes se gestionan desde la interfaz de administración web y a través de la API de administración bajo /v1/admin/agents/*.
Esta página cubre de qué está hecho un agente, cómo se ensambla el prompt estructurado “G3” y cómo un agente puede editar su propio perfil de manera segura.
El registro de agentes
El registro es un catálogo completo de agentes con operaciones CRUD. Para cada agente defines una identidad, una persona, el modelo en el que se ejecuta y las habilidades que puede usar. Debido a que la puerta de enlace es multitenant, los agentes viven dentro de un espacio de trabajo y están aislados como cualquier otro dato de inquilino.
Persona — la voz y el comportamiento del agente, transformados en un establo,
capa del prompt del sistema amigable con la caché.
Modelo por agente — cada agente puede fijar su propio modelo y proveedor, así que un
Un agente barato y un agente principal pueden coexistir en el mismo espacio de trabajo.
Habilidades — las habilidades por agente y compartidas convierten un bloque de “Habilidades” en el
solicitud; describen capacidades, no pesos.
[!NOTE]
Un modelo por agente es independiente del enrutamiento. Enrutamiento a nivel de modelo (simple /
estándar / complejo) elige una clase de modelo para un turno, mientras que el por-agente
el modelo es el predeterminado del propio agente. Ver
Enrutamiento.
Versiones, reversión y clon
Cada cambio significativo en un agente se captura como un versión. Esto hace que la configuración del agente sea auditables y reversible: puedes revisar lo que cambió, revertir a una versión anterior, o clonar un agente para usarlo como punto de partida para uno nuevo. Los recursos de versión y perfil se encuentran bajo /v1/admin/agents/* (perfil, secciones, habilidades, versiones).
[!TIP]
Clona un agente que funcione antes de una reescritura importante de persona o indicación. Si el nuevo
si la dirección no resulta, el original todavía está a un retroceso de distancia.
El aviso estructurado “G3”
En lugar de un solo aviso de sistema de texto libre, AiHummer utiliza un perfil de agente estructurado (internamente “G3”). La identidad es descompuesto en campos en lugar de estar enterrado en prosa, y el resto del aviso se construye a partir de nombres secciones más un incorporación bloque. El orquestador convierte estos en el aviso del sistema por capas, manteniendo las partes estables (identidad, personalidad, secciones) en un prefijo que se puede almacenar en caché y añadiendo los datos volátiles al final.
La estructura hace que un perfil sea fácil de editar campo por campo, fácil de diferenciar entre versiones y predecible de representar — no hay sopa de indicaciones oculta.
Se puede permitir a un agente editar su propio perfil uso de herramientas de autoedición — por ejemplo, para refinar una sección o actualizar su incorporación. Esto está deliberadamente protegido:
Las autoediciones pasan por el puerta de aprobación: se registra un cambio propuesto y
debe ser aprobado por un humano antes de que entre en vigor. Un cambio rechazado nunca
aplicado.
El cambio se captura como uno nuevo versión, por lo que una autoedición es igualmente auditable
y reversible como cualquier edición manual.
[!WARNING]
La autoedición es poderosa. Mantenla detrás del portal de aprobación para que un agente no pueda
reescriba silenciosamente su propia identidad. Revise las autoediciones propuestas de la misma manera que usted
revisar cualquier cambio privilegiado.
Las contraseñas del correo van a la bóveda
Si la configuración de un agente incluye credenciales de correo (para el mail herramienta), la contraseña se escribe en el bóveda de credenciales encriptada, no se almacena en el perfil ni se incorpora al aviso. Los secretos nunca ingresan al contexto del modelo.
Política de ejecución: contexto, sesiones y agentes hijos
Desde la versión 1.3 un agente tiene una política de ejecución — el campo
runtime_policy de la API de administración (/v1/admin/agents al crear y
actualizar). Es un objeto JSON estrictamente validado con "version": 1: un
{} vacío restaura los valores por defecto, omitir el campo al actualizar
conserva la política anterior, y los campos desconocidos o los valores fuera de
rango se rechazan. La política no concede herramientas ni amplía derechos: solo
fija presupuestos y plazos. Clonar un agente y traspasarle un turno la heredan.
context — el presupuesto de historial: max_tokens, reserve_tokens
y history_share deciden cuánto historial entra en una solicitud;
max_history_messages acota la ventana de mensajes, bootstrap_max_chars el
tamaño del bloque de perfil. Con un contexto explícito, los mensajes antiguos
se compactan en un resumen por lotes antes de construir la solicitud actual.
pruning — limpieza de resultados de herramientas obsoletos: por
antigüedad (ttl_seconds), protegiendo las últimas respuestas
(keep_last_assistants), con recorte suave (soft_trim_ratio,
head_chars, tail_chars) y sustitución completa por el texto
placeholder por encima de hard_clear_ratio. El texto del usuario, las
imágenes y el historial completo en la base de datos no se tocan.
memory_flush — antes de la compactación, un agente sin herramientas
escribe una nota breve sobre objetivos, decisiones y asuntos pendientes
(soft_threshold_tokens); las tres últimas notas del mismo diálogo se
mezclan en el contexto como referencia no revisada.
session — el ciclo de vida del diálogo: idle_reset_minutes abre un
contexto nuevo tras una pausa (el historial bruto se conserva),
index_prune_after_days e index_max_entries retiran los diálogos antiguos
de la lista por defecto sin borrarlos. scope = per-peer (un diálogo por
usuario verificado en todos los canales) o per-channel-peer (un diálogo
aparte por canal).
children — agentes hijos: max_depth (hasta 4), max_concurrent
(hasta 8 por árbol de ejecución), max_per_parent (hasta 5),
timeout_seconds (hasta 48 horas, nunca más que el padre) y
archive_after_minutes — cuándo las ejecuciones terminadas salen de la lista
por defecto. Estos valores sustituyen para este agente los globales
AIHUMMER_SUBAGENT_MAX_DEPTH y AIHUMMER_SUBAGENT_TIMEOUT_SEC.
max_iterations (1–256) — el límite de pasos del bucle de llamada de
funciones para escenarios revisados con muchas delegaciones.
app — solo para la aplicación AiHummer: reasoning_effort,
service_tier y el modo de respuesta corta direct_completion (auto o
always con max_tokens hasta 4096 y timeout_ms hasta 60 000).
interaction — permisos explícitos sobre sesiones: user_ids,
session_agent_ids, spawn_agent_ids, la visibilidad session_visibility
(self, agent o granted), session_send, prohibiciones de
herramientas para llamadas hijas (child_tool_deny, child_leaf_tool_deny)
y elevated_telegram_user_ids — un subconjunto de user_ids autorizado a
pedir una ejecución code_exec explícitamente elevada (las aprobaciones no se
eluden). No hay comodines ni permisos para todo el inquilino.
API de administración
Los agentes y sus perfiles estructurados se gestionan a través de la API de administración, que está protegida por OIDC y auditada:
Un **agente** es la unidad que AiHummer pone al frente de una conversación. Cada agente tiene una personalidad, su propio modelo, un prompt estructurado y un conjunto de habilidades, y cada cambio en él se versiona. Los agentes se gestionan desde la interfaz de administración web y a través de la API de administración bajo `/v1/admin/agents/*`.
Esta página cubre de qué está hecho un agente, cómo se ensambla el prompt estructurado "G3" y cómo un agente puede editar su propio perfil de manera segura.
## El registro de agentes
El registro es un catálogo completo de agentes con operaciones CRUD. Para cada agente defines una identidad, una persona, el modelo en el que se ejecuta y las habilidades que puede usar. Debido a que la puerta de enlace es multitenant, los agentes viven dentro de un espacio de trabajo y están aislados como cualquier otro dato de inquilino.
- **Persona** — la voz y el comportamiento del agente, transformados en un establo,
capa del prompt del sistema amigable con la caché.
- **Modelo por agente** — cada agente puede fijar su propio modelo y proveedor, así que un
Un agente barato y un agente principal pueden coexistir en el mismo espacio de trabajo.
- **Habilidades** — las habilidades por agente y compartidas convierten un bloque de “Habilidades” en el
solicitud; describen capacidades, no pesos.
> [!NOTE]
> Un modelo por agente es independiente del enrutamiento. Enrutamiento a nivel de modelo (simple /
> estándar / complejo) elige una clase de modelo para un turno, mientras que el por-agente
> el modelo es el predeterminado del propio agente. Ver
> [Enrutamiento](/es/v1.0/concepts/routing).
## Versiones, reversión y clon
Cada cambio significativo en un agente se captura como un **versión**. Esto hace que la configuración del agente sea auditables y reversible: puedes revisar lo que cambió, **revertir** a una versión anterior, o **clonar** un agente para usarlo como punto de partida para uno nuevo. Los recursos de versión y perfil se encuentran bajo `/v1/admin/agents/*` (perfil, secciones, habilidades, versiones).
> [!TIP]
> Clona un agente que funcione antes de una reescritura importante de persona o indicación. Si el nuevo
> si la dirección no resulta, el original todavía está a un retroceso de distancia.
## El aviso estructurado "G3"
En lugar de un solo aviso de sistema de texto libre, AiHummer utiliza un **perfil de agente estructurado** (internamente "G3"). La identidad es **descompuesto en campos** en lugar de estar enterrado en prosa, y el resto del aviso se construye a partir de nombres **secciones** más un **incorporación** bloque. El orquestador convierte estos en el aviso del sistema por capas, manteniendo las partes estables (identidad, personalidad, secciones) en un prefijo que se puede almacenar en caché y añadiendo los datos volátiles al final.
La estructura hace que un perfil sea fácil de editar campo por campo, fácil de diferenciar entre versiones y predecible de representar — no hay sopa de indicaciones oculta.
```text
G3 profile
├── identity fields (decomposed: name, role, ...)
├── sections (named, ordered prompt blocks)
└── onboarding (first-run guidance)
```
## Autoedición detrás de una puerta de aprobación
Se puede permitir a un agente **editar su propio perfil** uso de herramientas de autoedición — por ejemplo, para refinar una sección o actualizar su incorporación. Esto está deliberadamente protegido:
- Las autoediciones pasan por el **puerta de aprobación**: se registra un cambio propuesto y
debe ser aprobado por un humano antes de que entre en vigor. Un cambio rechazado nunca
aplicado.
- El cambio se captura como uno nuevo **versión**, por lo que una autoedición es igualmente auditable
y reversible como cualquier edición manual.
> [!WARNING]
> La autoedición es poderosa. Mantenla detrás del portal de aprobación para que un agente no pueda
> reescriba silenciosamente su propia identidad. Revise las autoediciones propuestas de la misma manera que usted
> revisar cualquier cambio privilegiado.
### Las contraseñas del correo van a la bóveda
Si la configuración de un agente incluye credenciales de correo (para el `mail` herramienta), la contraseña se escribe en el **bóveda de credenciales encriptada**, no se almacena en el perfil ni se incorpora al aviso. Los secretos nunca ingresan al contexto del modelo.
## Política de ejecución: contexto, sesiones y agentes hijos
Desde la versión 1.3 un agente tiene una **política de ejecución** — el campo
`runtime_policy` de la API de administración (`/v1/admin/agents` al crear y
actualizar). Es un objeto JSON estrictamente validado con `"version": 1`: un
`{}` vacío restaura los valores por defecto, omitir el campo al actualizar
conserva la política anterior, y los campos desconocidos o los valores fuera de
rango se rechazan. La política no concede herramientas ni amplía derechos: solo
fija presupuestos y plazos. Clonar un agente y traspasarle un turno la heredan.
- **`context`** — el presupuesto de historial: `max_tokens`, `reserve_tokens`
y `history_share` deciden cuánto historial entra en una solicitud;
`max_history_messages` acota la ventana de mensajes, `bootstrap_max_chars` el
tamaño del bloque de perfil. Con un contexto explícito, los mensajes antiguos
se compactan en un resumen por lotes antes de construir la solicitud actual.
- **`pruning`** — limpieza de resultados de herramientas obsoletos: por
antigüedad (`ttl_seconds`), protegiendo las últimas respuestas
(`keep_last_assistants`), con recorte suave (`soft_trim_ratio`,
`head_chars`, `tail_chars`) y sustitución completa por el texto
`placeholder` por encima de `hard_clear_ratio`. El texto del usuario, las
imágenes y el historial completo en la base de datos no se tocan.
- **`memory_flush`** — antes de la compactación, un agente sin herramientas
escribe una nota breve sobre objetivos, decisiones y asuntos pendientes
(`soft_threshold_tokens`); las tres últimas notas del mismo diálogo se
mezclan en el contexto como referencia no revisada.
- **`session`** — el ciclo de vida del diálogo: `idle_reset_minutes` abre un
contexto nuevo tras una pausa (el historial bruto se conserva),
`index_prune_after_days` e `index_max_entries` retiran los diálogos antiguos
de la lista por defecto sin borrarlos. `scope` = `per-peer` (un diálogo por
usuario verificado en todos los canales) o `per-channel-peer` (un diálogo
aparte por canal).
- **`children`** — agentes hijos: `max_depth` (hasta 4), `max_concurrent`
(hasta 8 por árbol de ejecución), `max_per_parent` (hasta 5),
`timeout_seconds` (hasta 48 horas, nunca más que el padre) y
`archive_after_minutes` — cuándo las ejecuciones terminadas salen de la lista
por defecto. Estos valores sustituyen para este agente los globales
`AIHUMMER_SUBAGENT_MAX_DEPTH` y `AIHUMMER_SUBAGENT_TIMEOUT_SEC`.
- **`max_iterations`** (1–256) — el límite de pasos del bucle de llamada de
funciones para escenarios revisados con muchas delegaciones.
- **`app`** — solo para la aplicación AiHummer: `reasoning_effort`,
`service_tier` y el modo de respuesta corta `direct_completion` (`auto` o
`always` con `max_tokens` hasta 4096 y `timeout_ms` hasta 60 000).
- **`interaction`** — permisos explícitos sobre sesiones: `user_ids`,
`session_agent_ids`, `spawn_agent_ids`, la visibilidad `session_visibility`
(`self`, `agent` o `granted`), `session_send`, prohibiciones de
herramientas para llamadas hijas (`child_tool_deny`, `child_leaf_tool_deny`)
y `elevated_telegram_user_ids` — un subconjunto de `user_ids` autorizado a
pedir una ejecución `code_exec` explícitamente elevada (las aprobaciones no se
eluden). No hay comodines ni permisos para todo el inquilino.
## API de administración
Los agentes y sus perfiles estructurados se gestionan a través de la API de administración, que está protegida por OIDC y auditada:
| Recurso | Propósito |
|---|---|
| `/v1/admin/agents` | Listar, crear, actualizar, eliminar agentes (CRUD) |
| `/v1/admin/agents/.../profile` | El perfil G3 estructurado (campos de identidad) |
| `/v1/admin/agents/.../sections` | Secciones de indicaciones nombradas |
| `/v1/admin/agents/.../skills` | Habilidades por agente |
| `/v1/admin/agents/.../versions` | Historial de versiones, reversión y clonación |
## ¿A dónde vamos ahora?
- Entiende cómo los agentes ejecutan un turno y generan ayudantes en
[Orquestación y subagentes](/es/v1.0/concepts/orchestration-subagents).
- Ve cómo un mensaje entrante llega a un agente específico en
[Enrutamiento](/es/v1.0/concepts/routing).
- Dale a tus agentes memoria a largo plazo con
[Memoria (Einstein)](/es/v1.0/concepts/memory-einstein).
