> For the index of every page in Orbital's docs, read https://docs.beta.runorbital.dev/llms.txt.

# Research report

> Research a question on the web and write a short report with sources

In this example you turn a question into a short written report with sources. One step of the `research-report` workflow researches the question on the web and lists what it found. A second step writes the report from those findings alone.

About five minutes to set up.

```dot title="research-report.dot"
digraph research_report {
  graph [version="1", entry="research", description="Research a question on the web and write a short report with sources"]

  research [role="Researcher", tool_access="Research", prompt_file="prompts/research-report/research.md", outputs="findings:text"]
  write [role="Researcher", tool_access="Research", prompt_file="prompts/research-report/write.md"]
  done [shape="Msquare", outcome="success"]

  research -> write
  write -> done
}
```

![research passes its findings to write, then done ends the run.](/research-report.svg?v=f9f6c28b0d)

## Before you start

You need a signed-in harness and the workflow: [download the archive](/research-report.zip).

The workflow touches no code. Neither step can change a file or run a command: both have the Research [tool access](/roles/#tool-access), which allows reading files and browsing the web and nothing else.

## 1. Add the workflow

1. Unpack the archive into your workflow library, `~/.orbital/workflows/`. Keep every relative path.

2. Check it:

   ```sh
   orbital validate ~/.orbital/workflows/research-report.dot
   ```

Every project now offers `research-report`. The archive holds the workflow above and its two prompts:

```md title="prompts/research-report/research.md"
Research this question: {{ inputs.goal }}

Search the web and read at least three independent sources. Prefer primary sources, such as official documentation, standards, papers or the organisation's own pages, over summaries of them.

Do not change, create or delete any file.

Return `findings`: a list of facts. Give each fact its source's title and address. Mark each fact as agreed by several sources, stated by one source, or disputed. Note what you could not find out.
```

```md title="prompts/research-report/write.md"
Write a short report that answers this question: {{ inputs.goal }}

Use only these findings: {{ context.findings }}

Write in plain language, in short sentences. Put the answer first, in two or three sentences. Then give the details under short headings. Say where the sources disagree and what nobody could confirm. End with a numbered list of sources, each with its title and address.

Do not change, create or delete any file. The report is the run's final answer, so end with it and nothing else.
```

## 2. Make a place for it to work

Every run belongs to a [project](/projects/), and a step starts in the project's primary folder. Any project works, because the workflow reads no project files. The project does not need to be a Git repository, unless you run it with Codex, which needs one. See [plain folders and Git](/projects/#plain-folders-and-git).

If you have no project yet, make one:

1. Make a folder such as `~/research`.

2. In Orbital, open **Projects**, choose **New project** and name it `Research`.

3. Choose **Add folder** and pick `~/research`. It shows as a Plain folder.

## 3. Start the run

1. Choose **New task**, pick any project and choose the `research-report` workflow.

2. Write the question as the goal. For example:

   ```text
   What are the main differences between the EU AI Act's obligations for
   providers and for deployers of high-risk AI systems?
   ```

3. Choose a harness in the harness picker, and choose **Start run**.

![The Start page asking what to do in a project, with a goal box, a harness picker, a workflow picker and a Chat or Workflow switch.](/screenshots/start-page.webp?v=0428f5d705)

*The harness picker sits beside the workflow picker.*

## 4. Read the report

The **research** step's findings appear in the **Context** tab as `findings`. Each fact comes with its source and whether sources agree.

![A run's Context tab with a table of context keys, their values and the step that set each one.](/screenshots/run-context.webp?v=3e79bd8607)

*Each value shows the step that set it.*

The report is the **write** step's reply: the last message in the **Session** tab, above "Run ended: success". It gives the answer first, then the details, then a numbered list of sources.

:::caution
Check the sources yourself before you rely on the report. The agent can misread a page, and the web changes.
:::

## Make it yours

- Ask for a different shape of report by editing `write.md`, for example a one-page brief for a manager.
- Add a review step with the Reviewer role that checks each fact in the report against its source. [Add branches](/workflows/add-branches/) shows how to send a rejected report back.
- Start it every Monday with a Schedule [trigger](/triggers/).

## Related

- [Pass context between steps](/workflows/pass-context/): how `findings` reaches the write step
- [Add branches](/workflows/add-branches/): send a rejected report back for another try
- [Triage issues](/examples/triage-issues/): another workflow that changes no files