Construye un agente profundo

Actualizar dependencias

Para crear un agente profundo, agregue el paquete deepagents al archivo pyproject.toml de su proyecto:

dependencies = [
    "deepagents==0.5.3",
    ... # other dependencies
]

El paquete deepagents es una dependencia opcional del paquete agent-engine-sdk-langgraph. El SDK importa el paquete deepagents solo cuando la aplicación llama a la función App.deep_agent(), por lo que debe declararlo explícitamente en su proyecto.

Actualizar indicadores de características

Habilite las funciones avanzadas del agente en su agent.yaml agregando la siguiente bandera a su archivo agent.yaml:

features:
  deep_agent: true
  ... # other features

Esta bandera indica al entorno aislado de la herramienta que registre el sistema de archivos integrado y los controladores de shell en los que se basan los agentes profundos.

Parámetros

El método App.deep_agent() acepta los siguientes parámetros:

Crea un agente profundo con habilidades

Para crear un agente profundo que invoque habilidades, pase una lista de rutas de directorios de habilidades al parámetro skills del método App.deep_agent().

El siguiente ejemplo modifica la función decorada con @app.entrypoint para crear un agente profundo con una sola herramienta y un directorio de habilidades:

from agent_engine_sdk_langgraph import App
app = App()
@app.entrypoint
def build_agent():
    return app.deep_agent(
        llm=my_llm,
        tools=[my_tool],
        subagents=[],
        skills=["skills/security-review"],
    )

Validaciones de seguridad

En el momento de la inicialización, el método App.deep_agent() ejecuta las siguientes comprobaciones y genera un error si alguna de ellas falla:

• Comprueba si hay referencias a modelos de cadena en la clase SubAgent: Cada atributo SubAgent.model debe ser una instancia de LLM y no una cadena. Los nombres de modelos de cadena omiten la clase SecureWrappedLLM y la plataforma rechaza al agente. El método comprueba hasta 10 niveles de anidamiento.

• Comprueba si se ha proporcionado manualmente el parámetro backend: La plataforma es propietaria del entorno aislado y aplica la clase AgentEngineToolSandboxBackend como backend. Proporcionar un backend personalizado omite el entorno aislado de la plataforma y esta lo rechaza.

Además de estas comprobaciones, el método App.deep_agent() envuelve automáticamente la instancia LLM pasada al parámetro llm y todos los atributos SubAgent.model en la clase SecureWrappedLLM antes de que la biblioteca deepagents compile el gráfico.

Estructura del directorio de habilidades

Las habilidades se encuentran dentro de la siguiente estructura de directorios, donde el nombre del directorio coincide con el campo name en el frontmatter:

<workspace-directory>/
└── skills/
    └── <skill-name>/
        └── SKILL.md

Las rutas de habilidades que se pasan al parámetro skills son relativas al directorio del espacio de trabajo de su agente, que es el directorio que contiene su archivo agent.yaml.

Formato SKILL.md

Un archivo SKILL.md válido debe comenzar con un encabezado YAML. El siguiente ejemplo es una plantilla para un archivo SKILL.md válido:

---
name: <skill-name>
description: <one-sentence description for LLM discovery>
---
# Skill Title
Detailed instructions or reference material for the agent...

Debe incluir los siguientes campos en el encabezado YAML:

Transmitir habilidades al agente

El siguiente ejemplo pasa una lista de rutas de directorios de habilidades al método App.deep_agent():

agent = app.deep_agent(
    llm=my_llm,
    tools=[],
    skills=["skills/security-review", "skills/style-guide"],
)

Operaciones compatibles

Las operaciones de la clase AgentEngineToolSandboxBackend son invocadas automáticamente por el agente en tiempo de ejecución y no son llamadas directamente por los autores del agente. La clase AgentEngineToolSandboxBackend admite las siguientes operaciones, cada una expuesta al LLM como una herramienta filesystem_* o shell_execute correspondiente:

Error Handling

El sistema backend clasifica todos los errores antes de mostrarlos al gráfico del agente para que este pueda decidir si reintentar la operación. La siguiente tabla muestra las posibles clasificaciones de errores y sus causas:

La plataforma elimina todas las rutas internas del espacio de trabajo de todos los mensajes de error antes de que se muestren al agente.

Filesystem Sandbox

Los agentes profundos operan dentro de un sistema de archivos aislado. El entorno aislado contiene las siguientes capas:

• Espacio de trabajo editable (WORKSPACE_DIR): Por defecto, utiliza el directorio /tmp/agent-workspace. Durante las sesiones de la zona de pruebas del agente, esta limita el acceso del agente a la ruta WORKSPACE_DIR/.sessions/<session-hash>/ para que las sesiones concurrentes permanezcan aisladas. Utilice rutas relativas o rutas dentro del directorio /tmp para los archivos generados.

• Raíces de recursos de solo lectura (READONLY_RESOURCE_ROOTS): Se rellenan a partir de la variable de entorno AGENTIC_AGENT_WORKDIR y el directorio skills/. Esta capa permite al agente leer archivos SKILL.md dentro y fuera del espacio de trabajo de cada sesión, de modo que pueda cargar contenido de habilidades bajo demanda.

# .env
AGENTIC_AGENT_WORKDIR=/app
# Do NOT add: WORKSPACE_DIR=/app