Building an AI Screenwriting Agent

Get ready to build your own AI Screenplay Agent. This custom-designed AI partner can help you craft compelling stories, develop unforgettable characters, and polish your script until it shines.

Before you picture robots taking over Hollywood, let’s be clear: this isn’t about replacing human creativity. It’s about collaboration and harnessing the power of AI to enhance and streamline your screenwriting process. And Google Gemini? It’s not just another chatbot; it’s like having a seasoned Hollywood screenwriter in your corner, ready to brainstorm, analyze, and refine your script to perfection.

Why Gemini, you ask? Well, it’s particularly good at understanding complex instructions (like those we’ll use to build our agent) and readily accessible. Think of it as your friendly, super-smart writing buddy who is always up for a brainstorming session.

So, if you’ve got experience with Gemini and are ready to take your screenwriting to the next level, grab your laptop, and let’s get this show on the road!

AI Screenwriting Experiment

Okay, so full disclosure: I’m not a screenwriter. However, I am fascinated by how large language models (LLMs) can push the boundaries of creativity. So, I decided to dive headfirst into an experiment: Could I use an AI agent to help me write a screenplay?

An AI agent based on LLMs is an AI-powered program that uses a large language model to understand instructions, perform tasks, and interact with its environment autonomously or with human guidance to achieve specific goals.

Think of it like this: I’m the curious explorer venturing into uncharted territory with an AI companion. It’s less about producing a Hollywood-ready script and more about seeing just how far we can push the capabilities of these LLMs and agents.

Spoiler alert: Based on my experience with various LLMs, I don’t believe they will ever be able to write a great screenplay independently; we likely need a new kind of AI breakthrough for that to happen.

Now, this AI companion isn’t just any chatbot. It’s a specialized agent designed specifically for screenwriting. It’s like having a writing partner who can brainstorm ideas, analyze pacing, suggest dialogue tweaks, and even help me hit that industry-standard page count.

But even the most advanced AI needs good instructions. That’s where the system prompt comes in — it’s the key to unlocking the full potential of this AI screenwriting partner.

The System Prompt Blueprint

Think of the system prompt as an AI agent’s instruction manual. It’s how to define its role, its knowledge base, and the tools it can use. Here’s a look inside:

• Core Instructions: This is where I set the stage. The agent is told, “You are a seasoned Hollywood screenwriter. Your mission is to write a compelling screenplay, using all the tools and strategies a pro would.” It’s all about setting the right expectations from the start.
• Movie Idea: This is where the core of the story takes shape. The archetypes (e.g., “the hero’s journey”), the logline, and the genre are all essential building blocks.
• Fountain Markdown: Fountain is a standard for formatting screenplays, so naturally, the AI agent needed to be fluent in it.
• The Agent’s Toolkit: This is where things get interesting! A whole suite of specialized tools, from expanding scenes and refining dialogue to analyzing pacing and suggesting plot twists. Think of these tools as your director’s toolbox — each helps you polish a specific aspect of your script.
• The Process: The AI agent follows a straightforward process: selecting the best tool for the task, providing context, executing the tool, evaluating the results, and iterating until it hits the mark. It’s a structured approach with room for experimentation.
• Goals and Metrics: For this experiment, the main goal was to see if the AI could help produce a complete screenplay draft, hitting that typical 90–120 page count.
• Strategy: The AI agent isn’t just randomly using tools. It develops its strategy, adapting to feedback and using the tools wisely to achieve the goals I set.

With this detailed system prompt, the AI agent was ready to become a co-writer on this experimental journey.

The Node.js Engine Powering the Process

While the AI agent takes center stage in refining the screenplay, there’s a powerful engine running behind the scenes, orchestrating the entire process. This engine is built using Node.js and the Google Gemini API. It manages the workflow, handles data, and interacts with the language models.

Think of it like this: the AI agent is the screenwriter, but the Node.js code is the producer, director, and film crew all rolled into one. It sets the stage, guides the action, and ensures everything runs smoothly from the initial concept to the final screenplay.

Note: The agent uses various LLM instances to do multiple tasks. Each instance has a prompt with distinct roles, instructions, and contexts.

The Workflow

The screenwriting process is broken down into a series of distinct steps, each building upon the previous one. The initial steps are hand-coded to establish the story’s foundation, while the AI agent manages the later steps, allowing for more dynamic and creative decision-making.

1. Brainstorming the Movie Idea:

This is where the story’s seed is planted. The initial steps focus on generating a comprehensive movie idea, complete with the following:

• Archetype & Logline: Identifying the core story and its essence.
• Genres & Story: Defining the plot, characters, themes, and even citing examples.
• Audience & Impact: Determining the target audience and the desired emotional impact.
• Context: Establishing the setting, subplots, and cultural relevance.
• Analysis: Delving deeper into the unseen forces, unanswered questions, and story logic.

2. From Idea to Treatment:

The fleshed-out movie idea is then transformed into a detailed movie treatment, including:

• Core Info: Title and logline for easy identification.
• Detailed Synopsis: A plot breakdown into key stages like setup, inciting incident, rising action, climax, and resolution.
• Character Profiles: In-depth profiles for each main character, including their role, motivation, relationships, and character arc.

3. Expanding the Narrative:

The treatment is further expanded into 15 standard movie beats, providing a skeletal structure for the story. These beats are then expanded to 40 beats, adding more detail and complexity.

4. The First Draft:

The 40 movie beats are then transformed into the screenplay’s first draft. The first draft is usually around 20 pages.

5. The Agent Takes Over:

Now, the AI agent steps in, armed with a clear set of goals:

• Reach the desired page count of 120 pages (although a minimum of 90 would do).
• Achieve the best possible qualitative evaluation. This evaluation skips strict structure rules, focusing on the core theme and how the protagonist embodies it. Does the theme resonate? Does the hero’s journey drive meaningful change? Do dialogue, visuals, and pacing serve that thematic purpose, creating emotional impact?
• Achieve the best possible qualitative analysis. This analysis starts by checking if the screenplay emotionally connects and sparks thought. Then, it analyzes dialogue, visuals, and structure, pinpointing weaknesses with targeted questions. Finally, it’ll assess the screenplay’s lasting impact and originality.

The agent is provided with the current page count, a qualitative evaluation, and a qualitative analysis for each step in the process, allowing it to make informed decisions.

6. The Toolkit:

The agent has a powerful toolkit at its disposal, including tools to (listed with their internal names):

• Expand and develop the story (“Screenplay Expand”).
• Increase the screenplay’s page count by enriching narrative depth, sensory detail, and cinematic structure (“Screenplay Increase”).
• Avoid clichés and stereotypes (“Screenplay Stereotypical”).
• Ensure continuity and resolve inconsistencies (“Screenplay Continuity”).
• Improve overall quality using a checklist (“Screenplay Checklist”).
• Refine scenes with critic feedback (“Screenplay Critic Feedback”).
• Polish dialogue (“Screenplay Dialog”).
• Sharpen descriptions (“Screenplay Descriptions”).
• Get an actor’s perspective on dialogue by having the LLM act out a character (“Screenplay Dialog Actor”).
• Strengthen character arcs (“Screenplay Character Arc”).
• Analyze and enhance themes (“Screenplay Theme Explorer”).
• Track and improve the use of motifs (“Screenplay Motif Tracker”).
• Ensure audience empathy with characters (“Screenplay Empathy Check”).
• Refine pacing (“Screenplay Pacing Analysis”).
• Transform telling into showing (“Screenplay Show Don’t Tell”).
• Systematically analyze and improve the script (“Screenplay Hacking”).
• Craft surprising but logical plot twists (“Screenplay Plot Twists”).
• Improve the overall movie arc (“Screenplay Future Perspective”).
• Enhance dramatic irony (“Screenplay Dramatic Irony”).
• Use reversals to subvert expectations (“Screenplay Reversals”).
• Create tension through conflicting scene goals (“Screenplay Conflicting Scene Goals”).

Once the agent selects a tool, it provides clear and concise instructions. This context is crucial for guiding the tool’s actions and ensuring it focuses on the areas that need improvement.

The agent meticulously records observations, decisions, and lessons learned throughout this process. This digital memory helps it refine its strategies, adapt to new challenges, and make more informed choices as it progresses.

Note: The agent can also undo the effects of the last tool, which effectively reverts to the previous screenplay draft.

7. The Final Report:

Once the agent is satisfied with the screenplay, it generates a comprehensive report detailing its process, insights, and recommendations.

8. Formatting and PDF Generation:

The last step in the workflow is to verify that the screenplay is formatted correctly and generate a PDF of the final draft.

Decoding the Agent’s Report

Our AI agent has been at work, diligently applying its tools and refining the screenplay. It’s time for the grand reveal: the agent’s report! This report isn’t just a dry summary of what happened; it’s a treasure trove of insights, a screenwriting masterclass curated by your AI partner.

Consider it a debriefing session with a seasoned screenwriter who helped you craft a story. The agent shares its observations lessons learned, and even offers advice for future projects. Let’s dive in and see what wisdom it has to offer.

Targeted Tool Selection and Creative Flow

The agent emphasizes the importance of selecting the right tool for the right job. It’s about being strategic, not just randomly applying tools. Identify the screenplay’s weaknesses and choose the best tools to address those areas. But it’s not just about the tools; it’s also about maintaining a balance between AI-driven enhancements and your organic creative flow. Don’t let the tools dictate the story; use them to enhance your vision.

Tool-Specific Tips and Tricks

The agent provides a detailed breakdown of each tool’s strengths and best use cases. For example:

• “Screenplay Expand & Increase”: Great for adding depth and detail, but be mindful of over-expansion. Use it strategically when the core story is solid.
• “Screenplay Critic Feedback & Evaluation”: Invaluable for identifying weaknesses scene-by-scene, especially after a draft.
• “Screenplay Dialog”: Effective for refining dialogue, making it more concise and authentic. It is best used in later stages when characters and plot are well-defined.
• “Screenplay Descriptions”: Useful for crafting visually evocative descriptions throughout the writing process.
• “Screenplay Checklist”: A valuable tool for systematic review, ensuring all key elements are addressed before considering the screenplay complete.
• “Screenplay Pacing Analysis”: Helps identify and refine pacing issues, ensuring a smooth and engaging flow.
• “Screenplay Show Don’t Tell”: Powerful for transforming exposition-heavy scenes into more cinematic sequences.
• “Screenplay Character Arc & Dialog/Actor”: Excellent for deepening character development and ensuring authentic voices.
• “Screenplay Theme Explorer & Motif Tracker & Visual Motif”: Useful for strengthening thematic resonance and consistency throughout the story.
• “Screenplay Dramatic Irony, Reversals, Conflicting Scene Goals, Future Perspective, Plot Twists, Empathy Check”: These tools are more specialized, adding layers of complexity and surprise to enhance specific aspects of storytelling.

Workflow Optimization and Creative Enhancement

The agent also shares insights on how to optimize the workflow and enhance the creativity of a screenwriter:

• Iterative Approach: Embrace the iterative nature of screenwriting, using tools repeatedly and refining the script step by step.
• Targeted Tool Selection: Choose tools strategically based on the screenplay’s needs rather than applying them indiscriminately.
• Balance: Maintain a balance between AI assistance and creative intuition.
• Undo Feature: Don’t hesitate to undo changes if they don’t work as expected. Experimentation is key!
• Early Evaluation: Utilize evaluation tools frequently to monitor progress and identify areas for improvement.

The agent also emphasizes the importance of visual storytelling, emotional depth, thematic consistency, and engaging plot elements. It encourages using tools to enhance these aspects and create a compelling narrative.

Overcoming Challenges

The agent acknowledges common screenwriting challenges and offers strategies for overcoming them:

• Page Count Management: Focus on quality over quantity, using expansion tools strategically to avoid diluting the story.
• Pacing Issues: Use pacing analysis and scene-by-scene evaluation to identify and address pacing problems.
• Dialogue Refinement: Utilize dialogue tools and manual refinement to ensure natural and engaging conversations.
• Avoiding Formulaic Structure: While tools can be helpful, avoid over-reliance and strive for creative exploration and innovation within genre conventions.

By studying the agent’s report, you gain valuable insights into how an agent attempts to write a screenplay. The agent’s report is a helpful context for future instances of the agent to help it learn from past experiences.

Screenwriting by the Numbers

Let’s take a peek behind the curtain and explore some key metrics that reveal the inner workings of this approach.

Here’s a snapshot of the data generated during the creation of a screenplay:

• Final Evaluation Score: 97% — While the evaluation appears very high, I’ll leave it to you to assess how good the screenplay is. You can read the PDF version.
• Page Count: 103 pages — The screenplay is within the typical industry-standard length of 90–120 pages.
• API Calls: 1625 — This number highlights the extensive interaction between the Node.js engine and the language models.
• Max Prompt Tokens: 680,936 — This metric reveals the maximum amount of information the LLMs process during a single session. This is due to some tools having ongoing conversations about every scene in the screenplay.
• Total Output Tokens: 2,155,367 — This number showcases the volume of text generated by the LLMs. The screenplay is rewritten by every tool.
• Duration: 4 hours and 51 minutes — This timeframe demonstrates the efficiency of the AI-powered workflow, potentially reducing the time it would take to write a screenplay from scratch.

So, what conclusions could we make about these numbers? It’s best to look at these regarding the current workflow status. This workflow hasn’t been optimized, the agent design is still evolving, and the best selection of tools is still being explored.

And the most significant question remains: does this approach to writing a screenplay have any merits? While this workflow might never produce a blockbuster screenplay, the tools appear helpful and could be refactored as utilities that complement the manual screenwriting process.

Conclusion

And that’s a wrap! We’ve reached the final scene of our AI screenwriting adventure. Hopefully, by now, you’re buzzing with excitement about the possibilities of collaborating with an AI agent to bring your stories to life.

But remember, AI is your co-writer, not your replacement. Your unique voice, your vision, and your creativity are what will truly make your screenplay shine. Think of the AI as your secret weapon, trusty sidekick, and creative confidant.

So, what are you waiting for? It’s time to put everything you’ve learned into action. Fire up Google Gemini, craft your system prompt, and embark on your AI screenwriting journey. Experiment with the tools embrace the iterative process, and, most importantly, have fun!

Check out my reading list of other Google Gemini articles.

This post was created with the help of AI writing tools, carefully reviewed, and polished by the human author.