{"record":{"id":"0ce7e03d3d8ca8e4","repo":"langchain-ai/deepagents","slug":"agents-md-missing-required-root-prompt","errorCode":null,"errorMessage":"AGENTS.md: missing required root prompt","messagePattern":"AGENTS\\.md: missing required root prompt","errorType":"exception","errorClass":"FleetImportError","httpStatus":null,"severity":"error","filePath":"libs/talon/deepagents_talon/fleet_import.py","lineNumber":147,"sourceCode":"            subagents. Defaults to `target_dir`, keeping all writes under the\n            explicit target.\n\n    Returns:\n        Summary of the materialized files and generated MCP configuration.\n\n    Raises:\n        FleetImportError: If the zip is structurally unsafe, missing required\n            prompts, contains malformed `tools.json`, or cannot be written.\n    \"\"\"\n    source = zip_path.expanduser()\n    target = target_dir.expanduser()\n    home = assistant_home.expanduser() if assistant_home is not None else target\n    try:\n        with zipfile.ZipFile(source) as archive:\n            entries = _validated_entries(archive)\n            if \"AGENTS.md\" not in entries:\n                msg = \"AGENTS.md: missing required root prompt\"\n                raise FleetImportError(msg)\n            with tempfile.TemporaryDirectory(prefix=\"deepagents-talon-import-\") as raw:\n                staging = Path(raw)\n                _materialize_staging(archive, entries, staging)\n                summaries = _mcp_summaries(staging, source)\n                notes = _format_setup_notes(source.name, summaries)\n                mcp_config = _format_mcp_config(summaries)\n                config_ignored = (staging / \"config.json\").is_file()\n                _refresh_target(staging, target, home, notes, mcp_config)\n    except zipfile.BadZipFile as exc:\n        msg = f\"{source}: invalid zip file\"\n        raise FleetImportError(msg) from exc\n    except OSError as exc:\n        msg = f\"{target}: {exc}\"\n        raise FleetImportError(msg) from exc\n\n    return FleetImportResult(\n        target_dir=target,\n        root_prompt_count=1,","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/talon/deepagents_talon/fleet_import.py#L129-L165","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Rebuild the zip so AGENTS.md is at the archive root (zip the contents of the assistant home, not the folder itself).","Add the required AGENTS.md root prompt file to the archive.","Inspect the archive listing (`python -m zipfile -l fleet.zip`) to confirm 'AGENTS.md' appears at top level, not nested."],"exampleFix":"// before (nested)\nzip -r fleet.zip myfleet/          # contains myfleet/AGENTS.md\n// after (root-level)\ncd myfleet && zip -r ../fleet.zip . # contains AGENTS.md at root","handlingStrategy":"validation","validationCode":"import zipfile\ndef zip_has_root_prompt(path) -> bool:\n    with zipfile.ZipFile(path) as z:\n        names = {n.split(\"/\")[0] if \"/\" in n else n for n in z.namelist()}\n        return \"AGENTS.md\" in z.namelist()","typeGuard":null,"tryCatchPattern":"from deepagents_talon.fleet_import import import_fleet_zip, FleetImportError\ntry:\n    result = import_fleet_zip(source, target)\nexcept FleetImportError as exc:\n    if \"missing required root prompt\" in str(exc):\n        raise SystemExit(\"archive must contain AGENTS.md at its root\") from exc\n    raise","preventionTips":["Zip the contents of the assistant home, not the parent folder, so AGENTS.md sits at the archive root.","Verify with `python -m zipfile -l fleet.zip` that 'AGENTS.md' is a top-level entry.","Include the root prompt in your fleet export tooling."],"tags":["import","zip","validation","fleet"],"backgroundTag":"missing-required-file","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}