Simple AI Workflow with Reflection using OpenRouter

Authored by Dr. Tiziana Ligorio for AI Agents - CSCI 395.32 taught at Hunter College of The City University of New York¶

In this demo, we build a simple AI workflow that demonstrates a single round of reflection. One model call produces a draft, a second critiques it, and a third revises it.

Our workflow consists of three steps, each handled by an LLM with a distinct role:

1. Report Writer (think journalist): Generates an initial report based on a user-provided topic

2. Critic (think editor): Provides detailed critique and improvement suggestions

3. Reviser (think senior reporter): Takes the original report and critique to produce a final version

The purpose is to see how outputs from multiple LLM calls can be connected. A reflection workflow is more elaborate than a single call, but it is not automatically better. We will inspect the draft, critique, and revision to decide what changed and whether the change helped.

We use the OpenAI SDK directly, with OpenRouter as our provider, to keep the implementation transparent: no orchestration framework, just API calls that can be followed step by step.

Installs and Imports¶

%%capture hides installation output to keep the notebook readable. %pip installs packages into the Python environment used by the current notebook kernel.

OpenRouter provides access to models from multiple providers through one API. Model availability, pricing, and free-model options can change, so check the current OpenRouter model list before choosing a model.

This notebook follows OpenRouter’s documented integration with the OpenAI SDK. Other services may also describe themselves as OpenAI-compatible, but their supported endpoints and parameters can differ.

Setup your API Key¶

Step 1: Get an OpenRouter API key¶

For this demo we will use an LLM via OpenRouter, which requires an API key.

1. Go to https://openrouter.ai

2. Sign in (or create an account if you don’t have one)

3. Once logged in, navigate to https://openrouter.ai/settings/keys

4. Click Create Key

5. Give the key a name, e.g. colab-reflection-workflow

6. Copy the key immediately (you won’t be able to see it again)

Important: Treat this key like a password. Do not share it, paste it into notebooks, or commit it to GitHub.

Step 2: Store the API key¶

If running in Google Colab:¶

1. On the left sidebar, click 🔑 Secrets

2. Add a new secret:

   • Name: OPENROUTER_API_KEY

   • Value: your actual API key

3. Toggle the switch to give notebook access (you should see a checkmark)

If running locally:¶

1. Create a .env file in the project root:

   touch .env

2. Add the following (replace with your own key):

   OPENROUTER_API_KEY=your_openrouter_key_here

Important: Never paste API keys directly into code cells.

Load the API Key¶

In Colab:¶

Uncomment and run the cell below if you’re using Google Colab.

Locally:¶

Run the cell below if you’re running locally with a .env file.

Initialize the LLM Client¶

We use the OpenAI SDK to communicate with OpenRouter. OpenRouter documents this SDK integration and provides an OpenAI-compatible Chat Completions endpoint.

This demo uses gpt-5.6-luna, a current OpenAI model that is cost-sensitive. It is not a source of verified facts: generated factual claims should still be checked, especially for changing topics.

Models do not all support the same request settings. OpenRouter’s current model information lists reasoning_effort for this model but does not list temperature, so this notebook does not send a temperature setting. If you choose another model, check its supported parameters in the OpenRouter model list.

Step 1: The Report Writer¶

Our workflow begins with the Report Writer, an LLM instructed to act as a journalist who writes an initial report on a given topic.

Giving the model a role¶

The system message supplies instructions that should guide the model when it responds to the user message. It is part of the list of messages sent in the API request.

The OpenAI SDK uses a message format like this:

messages = [
    {"role": "system", "content": "You are a..."},  # Instructions for the model
    {"role": "user", "content": "..."},             # The request and its context
]

For our Report Writer:

• System message: Instructs the LLM to behave as a journalist writing informative reports

• User message: Supplies the topic and asks for a concise, well-structured report

The user message does not have to be the raw topic by itself. We can add context or instructions around it, for example, Write a concise, well-structured report on the following topic: {topic}.

The function above:

1. Takes a topic string

2. Wraps it with a more specific request

3. Sends the user message together with the writer’s system message

4. Asks the model not to spend extra tokens on additional reasoning for this simple task

5. Returns the generated report text

Some models accept a temperature setting that adjusts how varied their output is. This model’s current OpenRouter parameter list does not include temperature, so we do not send one. Model outputs can still vary between runs.

For this demonstration, we will make one writer call, inspect its response object, and reuse that same response as the initial report.

Pedagogical note¶

The SDK returns more than the generated text. We will keep the complete response object so we can inspect its fields before extracting the report.

Now extract the report text from the same response. This avoids paying for a second writer call and ensures that the response object above corresponds to the report used in the rest of the workflow.

The generate_initial_report function packages the same request pattern for reuse with other topics.

Step 2: The Critic¶

Now that we have an initial report, we pass it to the Critic, an LLM prompted to act as an editor who reviews the work and provides constructive feedback.

The Critic doesn’t rewrite the report. Instead, it identifies:

• Areas that need clarification or more detail

• Structural or logical issues

• Missing perspectives or context

• Ways to improve clarity and impact

This separation of concerns (writing vs. critiquing) is key to the reflection pattern. By having a dedicated critic, we get focused, actionable feedback rather than a muddled attempt to both evaluate and fix at once.

The output of Step 1 becomes the input to Step 2. This is the basic idea behind chaining LLM calls: each stage receives information produced by an earlier stage.

We use the same low-cost reasoning setting for the critic. Its focused behavior comes primarily from the critic’s instructions. The critique may still be incomplete or incorrect, so we will inspect what it says rather than assume it found every problem.

Step 3: The Reviser¶

The Reviser receives both the original report and the critique, then produces another version.

The Reviser has:

• The initial draft

• The critic’s comments

This gives it an opportunity to make targeted changes while preserving useful parts of the draft. However, the critic may miss a problem or suggest an unhelpful change, and the reviser may not follow good advice. We therefore need to inspect the final version rather than assume it improved.

This function takes two inputs: the original report and the critique. The labeled sections help the model distinguish the draft from the comments about it.

Let’s generate the revised version and then compare it with the original. Exact requirements, such as a word limit, should be checked with Python rather than estimated by the model.

Comparing the Results¶

Compare the initial report, critique, and revised report. Which comments were useful? Which changes helped? Did the revision introduce a new problem or leave an important issue unresolved?

Experiments¶

The workflow above ran once, with one model and deliberately simple prompts. In the experiments below, change one thing at a time and use the comparison to decide whether it actually helped. Treat the Python word counts (and your own reading of the draft, critique, and revision) as the evidence, not the impression that a longer or more confident answer must be a better one.

Experiment 1: Give the critic an explicit rubric¶

The critic’s current instructions ask for “constructive, specific” feedback in general terms. A more useful rubric might tell the critic which criteria to check, to point to specific wording in the draft as evidence, and to prioritize the few changes that matter most.

Run the critic with the rubric-style prompt below and compare it with the original critique. Is the feedback more actionable? Does the revision improve more as a result, and did it introduce any new problem?

Experiment 2: Use a different model for the critic¶

Nothing requires all three roles to share a model; each is an independent API call. A model asked to critique its own output tends to miss the same things it missed while writing, so a common design choice is to give the critic a different (or stronger) model.

Before switching models, check the model’s supported parameters in the OpenRouter model list. This tutorial’s model, gpt-5.6-luna, accepts reasoning_effort but not temperature; another model may be the reverse. Because every call here sends reasoning_effort, a model that does not support it will raise an error; that error is itself a lesson that request parameters are model-specific. To keep this experiment simple, choose a second model that also supports reasoning_effort.

Reflect¶

When a revision comes out better, notice what this workflow can and cannot tell you. It cannot cleanly separate the critic’s contribution from the reviser’s: a better result might mean the critic gave sharp feedback, or that the reviser executed well despite mediocre feedback, or both. What additional information would you need to tell the two apart?

Now look back at all three prompts. Are there general requirements for these reports that should guide the Writer and the Critic from the start? What are the trade-offs between generality and specificity: are good criteria universal, or domain-specific? Modify the prompts and re-run the notebook to observe the effects.