langchain-ai/deepagents · error · FleetImportError

AGENTS.md: missing required root prompt

Error message

AGENTS.md: missing required root prompt

What it means

FleetImportError raised by `import_fleet_zip` (libs/talon/deepagents_talon/fleet_import.py:147) when the uploaded archive does not contain a top-level 'AGENTS.md' entry. AGENTS.md is the required root prompt for an assistant fleet; without it the import would produce a home directory with no root agent definition, so the import is rejected before any files are written.

Source

Thrown at libs/talon/deepagents_talon/fleet_import.py:147

            subagents. Defaults to `target_dir`, keeping all writes under the
            explicit target.

    Returns:
        Summary of the materialized files and generated MCP configuration.

    Raises:
        FleetImportError: If the zip is structurally unsafe, missing required
            prompts, contains malformed `tools.json`, or cannot be written.
    """
    source = zip_path.expanduser()
    target = target_dir.expanduser()
    home = assistant_home.expanduser() if assistant_home is not None else target
    try:
        with zipfile.ZipFile(source) as archive:
            entries = _validated_entries(archive)
            if "AGENTS.md" not in entries:
                msg = "AGENTS.md: missing required root prompt"
                raise FleetImportError(msg)
            with tempfile.TemporaryDirectory(prefix="deepagents-talon-import-") as raw:
                staging = Path(raw)
                _materialize_staging(archive, entries, staging)
                summaries = _mcp_summaries(staging, source)
                notes = _format_setup_notes(source.name, summaries)
                mcp_config = _format_mcp_config(summaries)
                config_ignored = (staging / "config.json").is_file()
                _refresh_target(staging, target, home, notes, mcp_config)
    except zipfile.BadZipFile as exc:
        msg = f"{source}: invalid zip file"
        raise FleetImportError(msg) from exc
    except OSError as exc:
        msg = f"{target}: {exc}"
        raise FleetImportError(msg) from exc

    return FleetImportResult(
        target_dir=target,
        root_prompt_count=1,

View on GitHub (pinned to a1af029e6e)

Solutions

1. Rebuild the zip so AGENTS.md is at the archive root (zip the contents of the assistant home, not the folder itself).
2. Add the required AGENTS.md root prompt file to the archive.
3. Inspect the archive listing (`python -m zipfile -l fleet.zip`) to confirm 'AGENTS.md' appears at top level, not nested.

Example fix

// before (nested)
zip -r fleet.zip myfleet/          # contains myfleet/AGENTS.md
// after (root-level)
cd myfleet && zip -r ../fleet.zip . # contains AGENTS.md at root

import zipfile
def zip_has_root_prompt(path) -> bool:
    with zipfile.ZipFile(path) as z:
        names = {n.split("/")[0] if "/" in n else n for n in z.namelist()}
        return "AGENTS.md" in z.namelist()

from deepagents_talon.fleet_import import import_fleet_zip, FleetImportError
try:
    result = import_fleet_zip(source, target)
except FleetImportError as exc:
    if "missing required root prompt" in str(exc):
        raise SystemExit("archive must contain AGENTS.md at its root") from exc
    raise

When it happens

Trigger: Calling `import_fleet_zip(source, ...)` (directly or via `_run_import_fleet_command`) with a zip built without AGENTS.md at its root — e.g. only subagent files, or AGENTS.md nested in a subdirectory (validated entries are normalized, so nested paths do not count).

Common situations: Zipping a subdirectory instead of the assistant home root (so AGENTS.md lands at 'myfleet/AGENTS.md'); manually assembling archives with only .claude/agent files; exporting from a tool that omits the root prompt.

Related errors

• Invalid class_path '{class_path}' for provider '{provider}':
• {source}: invalid zip file
• {name}: symlink entries are not supported
• {name}: zip entry uncompressed size exceeds limit
• {path}: unsafe subagent name {name!r}

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/0ce7e03d3d8ca8e4. Report an issue: GitHub.