[feat][cli[: autoswarm should generate Agent() structs and write a ready-to-run Python file to disk

[kyegomez]

Summary

The autoswarm CLI command currently calls generate_swarm_config() which produces a YAML config and runs the swarm internally, but never persists a usable Python file for the user. The user has no artifact they can inspect, modify, or re-run without touching the CLI again.

This issue tracks adding a full pipeline to autoswarm that:

1. Generates the config — LLM produces the agent/swarm YAML (already works via generate_swarm_config / AutoSwarmBuilder)
2. Parses the dict → Agent() structs — map every key in the config dict to the correct Agent(...) constructor parameter
3. Writes a ready-to-run .py file in the current working directory so the user has a reusable, editable script

---

Current behavior (swarms/cli/main.py:55–100, swarms/agents/auto_generate_swarm_config.py)

swarms autoswarm --task "build a research pipeline" --model gpt-4.1

• Calls generate_swarm_config(task=task, model=model)
• Config is generated, agents are created via create_agents_from_yaml(), swarm runs
• Nothing is written to disk; the user has no output file

---

Desired behavior

swarms autoswarm --task "build a research pipeline" --model gpt-4.1

Expected output:

✓ Swarm configuration generated
✓ Parsed 3 agents from config
✓ Written to: ./autoswarm_research_pipeline.py

Generated file (autoswarm_research_pipeline.py):

from swarms import Agent
from swarms.structs.swarm_router import SwarmRouter

# Auto-generated by `swarms autoswarm` — edit freely

researcher = Agent(
    agent_name="Researcher",
    agent_description="Finds and summarises relevant papers",
    system_prompt="You are a research specialist ...",
    model_name="gpt-4.1",
    max_loops=1,
    temperature=0.5,
)

analyst = Agent(
    agent_name="Analyst",
    agent_description="Synthesises findings into actionable insights",
    system_prompt="You are a data analyst ...",
    model_name="gpt-4.1",
    max_loops=2,
    temperature=0.3,
)

writer = Agent(
    agent_name="Writer",
    agent_description="Produces the final report",
    system_prompt="You are a technical writer ...",
    model_name="gpt-4.1",
    max_loops=1,
)

swarm = SwarmRouter(
    name="Research-Pipeline",
    description="End-to-end research pipeline",
    agents=[researcher, analyst, writer],
    swarm_type="SequentialWorkflow",
    max_loops=1,
)

if __name__ == "__main__":
    result = swarm.run("build a research pipeline")
    print(result)

---

Implementation plan

1. Config dict → Agent() parameter mapping (swarms/agents/auto_generate_swarm_config.py)

Add a config_dict_to_agent_code(agent_dict: dict) -> str helper that maps the parsed YAML fields to the Agent(...) constructor signature:

YAML key	Agent() param
agent_name	agent_name
system_prompt	system_prompt
description	agent_description
model_name	model_name
max_loops	max_loops
temperature	temperature
max_tokens	max_tokens
autosave	autosave
verbose	verbose
output_type	output_type
context_length	context_length

Unknown keys should be emitted as **kwargs-style comments so the user knows they may need to map them manually.

2. File writer (swarms/agents/auto_generate_swarm_config.py or new swarms/utils/swarm_file_writer.py)

def write_autoswarm_file(
    config: dict,
    output_path: str = "autoswarm_output.py",
) -> str:
    """
    Given a parsed swarm config dict, render a ready-to-run Python file
    and write it to `output_path`. Returns the resolved file path.
    """

• Slugify the swarm name field to build the default filename (e.g. Research Pipeline → autoswarm_research_pipeline.py)
• Include a header comment noting the file was auto-generated
• Import only what is needed (Agent, the relevant swarm struct)
• Emit a if __name__ == "__main__": block with swarm.run(task)

3. Wire into run_autoswarm (swarms/cli/main.py:55)

result = generate_swarm_config(task=task, model=model)
output_file = write_autoswarm_file(config=result, task=task)
console.print(f"[green]✓ Written to: {output_file}[/green]")

Add an optional --output / -o flag to setup_argument_parser() so users can specify a custom output path.

4. Preserve existing run-immediately behaviour

Keep the existing in-process execution path. Add a --no-run flag that skips execution and only writes the file, for users who just want the generated script.

---

Relevant files

File	Role
swarms/cli/main.py:55	run_autoswarm() — entry point to modify
swarms/agents/auto_generate_swarm_config.py	generate_swarm_config() — produces the config dict
swarms/agents/create_agents_from_yaml.py	create_agents_from_yaml() — existing YAML→Agent pipeline for reference
swarms/structs/auto_swarm_builder.py	AgentSpec, SwarmRouterConfig Pydantic models — use for field validation
swarms/structs/agent.py	Agent.__init__ — canonical parameter list
swarms/cli/utils.py	CLI helpers, console, error formatting

---

Acceptance criteria

• swarms autoswarm --task "..." --model "..." writes a .py file to the current directory
• The generated file is valid Python that runs without modification (assuming env vars are set)
• Every agent in the YAML config maps to a correctly-named Agent(...) variable in the output
• Swarm architecture section maps to the correct swarm struct (SwarmRouter, SequentialWorkflow, etc.)
• An --output / -o flag lets the user override the output path
• A --no-run flag skips in-process execution and only writes the file
• Existing behaviour (running the swarm immediately) is preserved by default
• Unit tests cover: config→code mapping, file writing, CLI flag wiring

---

Labels

enhancement, cli, autoswarm, good first issue