Crea y ejecuta un agente
Un agente es un modelo de lenguaje con un sistema de comandos, un conjunto de herramientas que puede utilizar y, opcionalmente, otros agentes a los que puede delegar tareas. Al interactuar con él, decide en cada paso si debe utilizar una herramienta, delegar parte de la tarea a un subagente o responder.
Esta guía te lleva desde un proyecto vacío hasta un agente implementado que has probado en Tiet · Studio y al que has llamado desde la API. El ejemplo práctico copia un agente de catálogo real, lo modifica y lo implementa.
Agente, flujo de trabajo o gráfico de agente
| Necesitas | Usar | Por qué |
|---|---|---|
| Una conversación o una tarea abierta en la que el modelo decide qué herramientas utilizar. | Agent (esta página) | Una solicitud, un modelo, herramientas elegidas en tiempo de ejecución. Transmite una respuesta de chat. |
| Los mismos pasos fijos cada vez, cableados por ti, sin que ningún modelo decida el orden. | Workflow en el Constructor: Crea cualquier flujo de trabajo | Nodos deterministas. Un flujo de trabajo aún puede contener un nodo Agent Executor cuando un paso requiere un modelo con herramientas. |
| Varias etapas del modelo con diferentes roles o modelos, fijadas por etapa, con un registro por paso. | Agent graph: Construir un grafo de agentes | Gráfico versionado de nodos LLM que se ejecuta como una sola instancia. Más lento y costoso que un solo agente. |
Empiece con un solo agente. Recurra a un gráfico solo cuando una sola instrucción no pueda contener la lógica, o cuando necesite diferentes modelos para cada etapa.
Cómo responde un agente
- Tools son acciones que el agente puede llamar, como
pubmed,medical-calculatoromemory. Usted las asigna en la pestaña Diseño. Una herramienta cuyo efecto está por encima del límite de autonomía de la ejecución no se ofrece al modelo en absoluto (consulte Agentes y gobernanza). - Sub-agents son otros agentes a los que el agente puede delegar. Cada uno se expone al padre como una herramienta llamada
agent_<tool_name>y se ejecuta con su propio indicador y sus propias herramientas. - Models provienen del registro en Tiet · Agentic → Agents → Models. La sección Model de la pestaña Diseño selecciona uno. Se pueden enrutar diferentes modelos a diferentes fases (ver más abajo).
- Agent type se establece al crear el agente: Conversational (conversación de varios turnos con memoria), Task (tarea de un solo disparo), Hybrid (conversación más tarea) o ReAct (bucle de razonamiento, acción y observación con herramientas). Utilice ReAct para un agente que dependa de herramientas.
Donde están las cosas
Abra Tiet · Agentic → Agents. La página tiene seis pestañas: Agents, Agent Graphs, Agent Catalog, Models, Tools y Skills. Solo verá las pestañas para las que tiene permiso. En la parte superior derecha están el selector Project, un selector Run in y New Agent. Run in elige el entorno que se ejecuta iniciado desde Studio execute in (el predeterminado de la organización a menos que elija otro). Un entorno que permite borradores ejecuta lo que el editor solicita; cualquier otro ejecuta solo las versiones implementadas en él. Consulte Entornos y promoción.
La barra lateral también tiene tres hermanos debajo de Tiet · Agentic → Agents:
- En el botón Agent Workspace puedes chatear con un agente o iniciar una misión.
- Monitor (Agent activity) enumera las ejecuciones recientes en cada agente y gráfico.
- Reviews (SEPL commit reviews) enumera los cambios propuestos en los agentes que esperan una decisión humana, en todos los agentes. Véase Agentes y gobernanza.
Crear un agente
Hay tres maneras de incorporar un agente a tu proyecto.
Comience con un agente de catálogo (recomendado).
El Agent Catalog contiene Tietai agente base gestionado. Se envían aproximadamente 110, que abarcan codificación y facturación, soporte para la toma de decisiones clínicas, documentación, enfermería, farmacia, atención especializada, operaciones y más. Son puntos de partida probados con indicaciones reales y listas de herramientas.
- Seleccione el Project en la esquina superior derecha. Necesita uno; sin él, no se podrá crear la copia.
- Abra la pestaña Agent Catalog o haga clic en New Agent → Start from a Tietai base agent.
- Encuentra al agente. El cuadro de búsqueda del catálogo dice "Buscar agentes por nombre, descripción o etiquetas...".
- Haz clic en Deploy to my org. Introduce el Agent Name, luego Deploy.
El resultado es una copia editable en tu proyecto, y el Diseñador se abre sobre ella. A pesar de la etiqueta del botón, la copia aún no está desplegada: está activa, el número de versión es el del agente base, las asignaciones de herramientas se copian y las referencias de los subagentes se copian por referencia. La copia recuerda de qué plantilla proviene, y la pestaña Historial muestra Review Changes cuando la plantilla se actualiza posteriormente.
Empezar desde el principio
- Haz clic en New Agent y luego Start from scratch ("Configura un agente en blanco con tus propios ajustes").
- Rellene el cuadro de diálogo New Agent:
| Campo | Significado | Ejemplo |
|---|---|---|
| Name | Requerido. | Discharge Summary Helper |
| Type | Conversacional, de tareas, híbrido o reactivo. Conversacional por defecto. | Reaccionar |
| Description | Opcional. | Drafts a discharge summary from a pasted note. |
| Project | Tomado del selector de proyectos. El cuadro de diálogo advierte "No hay ningún proyecto activo; seleccione uno primero" y el Create permanece deshabilitado hasta que haya uno. | Proyecto de demostración |
- Haz clic en Create. Se abrirá el Diseñador. Allí se configurarán el indicador del sistema, las herramientas y el modelo.
Duplicar un agente existente
En la tarjeta de un agente, abra el menú de acciones y seleccione Duplicate. La copia se denomina <name> (Copy) e incluye herramientas, habilidades y políticas. Se crea inactiva a propósito y nunca se copia como implementada o publicada en Inferencia. Si algunos elementos vinculados no se copian, verá el mensaje "... se creó, pero no se pudieron copiar N elementos de configuración vinculados. Revise la copia antes de usarla". El Diseñador no tiene una opción para volver a activar un agente inactivo, por lo que, para una copia que desee ejecutar, prefiera la opción del catálogo descrita anteriormente.
Trasladar agentes a otro proyecto
En la tarjeta de un agente, el menú de acciones muestra Move to project…. Marque las casillas de varias tarjetas (mantenga presionada la tecla Mayús y haga clic para seleccionar un rango) y use la barra de selección para moverlas juntas. Solo se modifica el proyecto. Los agentes base del catálogo y los agentes de otras organizaciones no se pueden mover, y se requiere permiso para actualizar los agentes. El destino debe ser un proyecto de la misma organización.
El Diseñador de Agentes
Haz clic en un agente para abrir el Diseñador. Las pestañas son:
| Pestaña | Lo que contiene |
|---|---|
| Design | La configuración: Identidad, Mensaje, Variables, Herramientas, Habilidades, Ejecución, Subagentes, Memoria, Modelo. Botones Guardar y Desplegar a la derecha. |
| Policies | Reglas de gobernanza para este agente. New Policy ofrece cinco tipos: IntentGuard (bloquear intenciones de usuario que coincidan con un activador), Playbook (insertar instrucciones paso a paso en el mensaje del sistema), ToolGuide (añadir guía a la descripción de una herramienta), ToolApproval (pausar para aprobación humana antes de llamar a una herramienta, con un tiempo de espera en minutos) y OutputFormatter (formatear instrucciones para la respuesta final). Activadores: palabra clave, semántico, nombre de herramienta o siempre. Cada política tiene una prioridad y un interruptor de habilitación. |
| Activity | Registro paso a paso de una sesión: seleccione una sesión, vea sus pasos y duraciones, y ábrala en el Explorador de trazas. Vacía hasta que se haya ejecutado el agente ("Aún no hay sesiones. Ejecute el agente para ver la actividad."). |
| Test | Chatea con el agente desplegado: Ask the Agent, Test Inputs (mensajes y archivos guardados con un resultado esperado opcional) y Execution History. |
| Validate | Run Validation comprueba la configuración y enumera los problemas por campo, por ejemplo prompt_template: system prompt is required y model_config: model configuration is required. |
| History | La lista de versiones. New draft version inicia un borrador con notas de cambio opcionales. |
| API | Claves API para este agente, el punto final de invocación, el esquema de solicitud y ejemplos de código en cURL, TypeScript, Python y Java. |
| Evolution | Mensajes autoevolutivos (SEPL): modo, Run Evolution, parámetros, revisiones pendientes e historial. Consulte Agentes y gobernanza. |
La barra superior muestra el nombre del agente, un selector de versión, una insignia Deployed cuando está activa y un botón Copilot que abre un panel de asistente junto a las pestañas. Los usuarios con el rol de administrador de plataforma también ven Publish to Catalog.
Las secciones de la pestaña Diseño
| Sección | Campos y controles |
|---|---|
| Identity | Nombre, Descripción, Versión, Etiquetas (escriba una etiqueta y pulse Intro), Tipo de agente. |
| Prompt | System Prompt: se envía al modelo al inicio de cada conversación. Escriba {{name}} para un valor que complete en cada llamada (la API de invocación llama a estos variables). Con el enrutamiento del modelo activado, esto se convierte en cuatro indicaciones por fase (Planificación, Llamada a la herramienta, Razonador, Síntesis) más una indicación predeterminada para fases vacías. |
| Variables | Declara lo que un llamador proporciona para cada {{name}} en el mensaje: nombre, tipo (cadena, texto, número o booleano), requerido y un ejemplo. Add variable o Declare N from the prompt para agregar los marcadores de posición que usa el mensaje y que no ha declarado. Como máximo 50. Las declaraciones se versionan con el agente y los preajustes de variables se verifican con respecto a ellas (un valor requerido faltante, un no número o una cadena de más de 1000 caracteres es rechazado; declare valores largos como text). El punto final de invocación en sí no los aplica. |
| Tools | Todas las herramientas disponibles para su organización, agrupadas por categoría. Haga clic en una para asignarla o eliminarla. Al asignar una herramienta con permisos de lectura, en lugar de solo de lectura, se abrirá primero un cuadro de diálogo de revisión de permisos. |
| Skills | La capacidad carga el modelo bajo demanda. El interruptor automático inyecta las instrucciones de una habilidad antes de la primera ronda del modelo. |
| Execution | Default Execution Mode (Rápido, Equilibrado, Preciso), Auto Variable Tracking, Auto Planning, Model Routing (un modelo por fase), Shortlister (clasifica las herramientas por relevancia; necesita Qdrant) y Code-Act Mode. |
| Sub-Agents | Add Sub-Agent. Para cada uno: Agent ID, Tool Name, Invocation (sequential, parallel, fire-and-forget) y Description ("Cuándo delegar a este agente"). |
| Memory | Enable memory, luego Tipo de memoria (episódica, semántica, procedimental, de trabajo), Backend de memoria y una Estrategia de recuperación para el backend de Memora. |
| Model | Model selector (con "clave configurada" o "sin clave" para el modelo seleccionado), Temperature, Max Tokens (256 a 128000), Enable streaming y Manage model credentials. |
La columna de la derecha tiene Save Changes, Deploy, una casilla de verificación Publish to Inference (que convierte al agente en una plantilla en la página de Inferencia Médica) y un panel Status (Activo, Desplegado, Publicado, Actualizado).
El valor Invocation se guarda con cada referencia de subagente. En la ruta de chat e invocación, cada subagente se registra como una herramienta invocable llamada agent_<tool_name> y el modelo decide cuándo llamarla; nada en esa ruta se ramifica en sequential, parallel o fire-and-forget. No confíe en el modo para cambiar la forma en que se ejecuta la delegación.
Una delegación se detiene con un error que el proceso padre interpreta como una llamada a herramienta fallida después de 20 llamadas al modelo o 10 turnos de llamada a la herramienta, por defecto. Una conversación también está limitada a 30 delegaciones por hora por proceso de servidor. Si no se establece max_sub_agent_depth, el límite de profundidad es 2.
Versiones: borrador, despliegue, congelada
- Un agente que no está desplegado se edita en el lugar. Save Changes solicita notas de cambio opcionales y aumenta la versión del parche (por ejemplo,
1.1.0a1.1.1). - El Deploy registra la configuración actual como una versión desplegada y marca el agente como activo. La pestaña Prueba, el Espacio de trabajo del agente y la API de invocación ejecutan la versión desplegada.
- Una versión desplegada está congelada. Al intentar guardar cualquier cambio, se rechaza el código HTTP 409 y el código
AGENT_DEPLOYED_IMMUTABLE, y el Diseñador indica: «Esta versión está desplegada y es inmutable. Cree una nueva versión para modificarla». El nombre, la descripción, las etiquetas, el proyecto y la configuración de inferencia permanecen editables. - Para cambiar un agente desplegado, haga clic en New version (o New draft version en el historial). Editará el borrador; el agente en ejecución no cambia. Save draft, luego Deploy vX.Y.Z. Discard draft lo descarta.
- Todas las versiones se mantienen legibles. Para revertir la versión, inicie un borrador a partir de una versión anterior ("Nueva versión a partir de esta") y despliéguela.
- Las asignaciones de herramientas y habilidades no forman parte de una versión. Se pueden editar en tiempo real y no están fijas con ella. Los valores declarados como Variables forman parte de la versión.
El Diseñador no tiene botón Undeploy, aunque la API tiene POST /api/agents/{id}/undeploy.
Ejemplo práctico: copiar, ajustar, probar, desplegar, llamar
Copiarás el agente de catálogo Laboratory Results Interpreter, agregarás una regla y lo llamarás. Su definición de catálogo: tipo react, modelo gemini-2.5-pro (proveedor google), temperatura 30, tokens máximos 8192, compliance_level: hipaa, herramientas medical-calculator, pubmed, memory y ui, sin subagentes. Su mensaje interpreta los resultados de laboratorio en comparación con los rangos de referencia, detecta valores críticos y problemas preanalíticos como la hemólisis, y escribe secciones Markdown como ## Result Summary y ## Critical Value Screen.
Utilice únicamente datos sintéticos.
1. Cópialo
- Seleccione un proyecto.
- Tiet · Agentic → Agents → Agent Catalog. Buscar "Laboratorio".
- En Laboratory Results Interpreter, haga clic en Deploy to my org, establezca Agent Name en
Lab Interpreter (Demo Hospital)y haga clic en Deploy.
Llegas al Diseñador. La barra superior muestra v1.1.0 y no hay ninguna insignia Deployed En Tools (4), las cuatro herramientas están marcadas.
2. Ajústalo
- Design → Identity: cambia Description por
Interprets lab results for Demo Hospital clinicians. - Policies → New Policy → Playbook. Nómbralo
Units on every value, configura el activador en siempre y en Instructions (Markdown) escribe1. Print every value with the unit exactly as reported by the source laboratory.Haz clic en Create Policy. - Design → Save Changes, agregue la nota
Demo Hospital descriptiony confirme. La versión se convierte en1.1.1.
Una política de Playbook inserta tus instrucciones en el indicador del sistema sin que tengas que editar el indicador del catálogo, que es extenso y tiene su propio contrato de salida. Las políticas no forman parte de una versión, por lo que puedes modificarlas después de la implementación.
3. Validar e implementar
- Validate → Run Validation. Deberías ver Agent is valid. Si no, cada problema nombra el campo.
- Design → Deploy. Aparece la insignia Deployed y la pestaña Prueba se vuelve utilizable.
4. Pruébalo
-
Abra la pestaña Test Antes de la implementación, aparecerá el mensaje "Agente no implementado. Implemente el agente desde la pestaña Diseño para comenzar las pruebas".
-
En Ask the Agent, enviar:
Test Patient A, 54 years old. Potassium 6.4 mmol/L, creatinine 2.1 mg/dL.
The specimen is marked hemolyzed. Interpret these results. -
Debería ver el flujo de respuestas, con las llamadas a la herramienta que realizó el agente. Compruebe que detecta un valor crítico, plantea la hemólisis como una posible causa preanalítica e imprime las unidades.
-
Abra el Activity para ver la misma sesión paso a paso y Test → Execution History para ver el registro de la ejecución.
Para guardar un mensaje para más tarde, use Test Inputs: ingrese un Input name, el Message, archivos adjuntos opcionales y un Expected result opcional.
5. Chatea con él en el espacio de trabajo del agente.
- Tiet · Agentic → Agents → Agent Workspace. El lanzador muestra tus agentes y gráficos activos como tarjetas, ordenadas por nombre. Un agente conversacional, híbrido o ReAct está en modo Ask; un agente de tarea está en modo Tool.
- Abre la tarjeta de tu agente y pulsa Start conversation. Escribe "Solicitar seguimiento, pegar un enlace o adjuntar un archivo…". En la pantalla aparecerá la nota "Solo para apoyo en la toma de decisiones clínicas".
6. Llámala desde la API.
-
Abra la pestaña API y haga clic en Generate Key. Complete Name, opcionalmente Description, Expires in (30 días, 90 días, 1 año o Nunca), Rate limit (solicitudes por minuto, 0 es ilimitado) y un opcional IP whitelist (uno por línea). La clave está limitada a este agente (
agent:<agent id>:execute). -
Copie el token inmediatamente: "Guarde este token; no se mostrará de nuevo".
-
Llama al punto final. A través de la puerta de enlace, la ruta es
/api/v1/hydra-platform/v1/agents/{id}/invoke:curl -X POST https://api.tiet.ai/api/v1/hydra-platform/v1/agents/AGENT_ID/invoke \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Test Patient A. Potassium 6.4 mmol/L, hemolyzed specimen. Interpret.",
"stream": false
}'
La pestaña API rellena automáticamente los nombres AGENT_ID y el nombre {{variable}} que usted elija.
| Campo de solicitud | Tipo | Notas |
|---|---|---|
message | cadena | Obligatorio a menos que envíe attachments. |
variables | objeto de cadenas | Valores para los marcadores de posición {{name}} en la solicitud. |
stream | booleano | true devuelve eventos enviados por el servidor (data: {...} fotograma). El ejemplo de transmisión de la pestaña API agrega Accept: text/event-stream. |
history | matriz de {role, content} | Turnos anteriores, si tú mismo mantienes la conversación. |
attachments | formación | Archivos del modelo; enviados en lugar de, o junto con, un mensaje. |
Con stream: false la respuesta es un objeto JSON. Incluye content (la respuesta), input_tokens y output_tokens, y cuando se ejecutaron las herramientas, tool_calls y tool_trace. Con stream: true el flujo termina con un marco que tiene "done": "true", los recuentos de tokens y final_content; un error lo termina con {"type": "error", ...}.
7. Cámbialo después de la implementación.
- Abra el agente y la pestaña Design Un banner indica que la configuración en ejecución no se puede editar directamente.
- Haz clic en New version, edita el borrador, Save draft, luego Deploy v1.1.2.
- Ahora, la opción History muestra las versiones anteriores y la nueva. Las versiones implementadas anteriormente aún se pueden leer.
Supervisa lo que hacen los agentes.
Tiet · Agentic → Agents → Monitor ("Actividad del agente: ejecuciones recientes en todos los gráficos de agentes y subagentes") muestra mosaicos para Runs, Success rate, Failed, Running now, Avg duration y Cost, filtros por tipo, estado, período, agente y nombre, y una tabla Executions con agente, tipo, estado, iniciado, duración, tokens, costo, activado por y un enlace al rastreo. La llamada a la API de invocación del paso 6 aparece aquí.
Límites
- La pestaña Prueba solo ejecuta un agente implementado.
- Las asignaciones de herramientas y habilidades se realizan en tiempo real y no están sujetas a versiones.
- Los modos del subagente Invocation se almacenan, no se aplican en la ruta de chat (ver la nota anterior).
- La reserva de modelos, las ejecuciones duraderas y la protección contra bucles pertenecen a los nodos del gráfico de agentes, no a un solo agente. Consulte Agentes y gobernanza.
- Los agentes base del catálogo son de solo lectura para usted. Solo un administrador de plataforma puede editarlos, y los cambios que realice afectarán a todas las organizaciones.
Solución de problemas
| Verás | Causa y solución |
|---|---|
| La Create está desactivada y el cuadro de diálogo dice "No hay ningún proyecto activo; seleccione primero un proyecto". | Seleccione un proyecto en el selector de proyectos situado en la parte superior derecha. |
| Falta el botón New Agent | No tienes permiso para crear agentes. Ponte en contacto con un administrador de la organización. |
| Pestaña de prueba: "Agente no desplegado" | Haz clic en Deploy en la pestaña Diseño (guarda primero; la opción Implementar está desactivada mientras haya cambios sin guardar). |
"Esta versión está desplegada y es inmutable. Cree una nueva versión para modificarla." (409 AGENT_DEPLOYED_IMMUTABLE) | Haz clic en New version, edita el borrador y despliégalo. |
Validación: system prompt is required o model configuration is required | Rellena la sección de "Indicación" o elige un modelo en la sección "Modelo". |
| La sección de modelos dice "No hay modelos configurados" o "no hay clave". | Registre el modelo y su clave en Tiet · Agentic → Agents → Models. |
Invoke devuelve 400 message or attachments required | El cuerpo no tiene message. |
Invoke devuelve 403 Access denied o Agent is not active | La clave pertenece a otra organización o el agente está inactivo (por ejemplo, un duplicado sin modificar). |
Invoke devuelve 404 Agent not found | ID de agente incorrecto en la URL. |
| La delegación falla con el mensaje "Se ha alcanzado el límite de delegación del subagente". | La conversación consumió sus 30 delegaciones para la hora. Inicie una nueva conversación o reduzca la delegación. |
Relacionado
¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..