Run An Example In VS Code

Use this page when you want to try design-research-agents in VS Code. Choose the installed-package path for a first user workflow, or the source checkout path when you want to run the repository’s checked-in examples and development checks.

The checked-in examples/ directory lives in the repository source. Do not assume those files are present inside the PyPI wheel.

Requirements

• Python 3.12 or newer.

• VS Code with the Python extension.

• A VS Code integrated terminal.

For the editor setup itself, follow the official Getting Started with Python in VS Code tutorial. It covers installing the Python and Pylance extensions, opening a folder, selecting an interpreter, and running a Python file in VS Code.

Installed Package From PyPI

Open an empty folder in VS Code, then create and activate a virtual environment from Terminal > New Terminal.

On macOS or Linux:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install design-research-agents

On Windows PowerShell:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install design-research-agents

Run Python: Select Interpreter from the command palette and choose the interpreter inside .venv. If VS Code does not list it, enter the interpreter path manually:

• macOS/Linux: .venv/bin/python

• Windows: .venv\Scripts\python.exe

Create hello_agents.py in the workspace folder:

import json

import design_research_agents as drag


class HelloWorldLLMClient:
    def generate(self, request: drag.LLMRequest) -> drag.LLMResponse:
        del request
        return drag.LLMResponse(
            text="Hello from design-research-agents.",
            model="local-demo",
            provider="local-demo",
        )

    def default_model(self) -> str:
        return "local-demo"


agent = drag.DirectLLMCall(llm_client=HelloWorldLLMClient())
result = agent.run(
    prompt="Say hello to a new design research teammate.",
    request_id="example-vscode-hello-world-001",
)
print(json.dumps(result.summary(), ensure_ascii=True, indent=2, sort_keys=True))

This example uses only the published package API and does not require an API key or model server.

Run the file with VS Code’s Run Python File action, or run:

python hello_agents.py

A successful run prints a JSON summary in the integrated terminal:

{
  "error": null,
  "final_output": "Hello from design-research-agents.",
  "success": true,
  "terminated_reason": null,
  "trace": {
    "request_id": "example-vscode-hello-world-001"
  }
}

Source Checkout For Repository Examples

Use this path when you want the checked-in examples, docs, tests, and optional development tooling.

git clone https://github.com/cmudrc/design-research-agents.git
cd design-research-agents
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e ".[dev]"

Equivalent maintainer shortcut:

make dev

Run the deterministic VS Code onboarding example from the integrated terminal:

python examples/agents/vscode_hello_world.py
make examples-smoke

First Development Checks

Run the checks from VS Code’s integrated terminal:

make test
make qa
make docs-check

make qa runs linting, formatting checks, type checks, and tests. Run make coverage before merge when changing tested behavior.

Optional Model Backends

The base install supports deterministic local examples. Install model-client extras only when a workflow needs them. For example:

python -m pip install "design-research-agents[openai]"

Use Dependencies and Extras for the full extras list.

Troubleshooting

• If VS Code imports fail but the terminal works, reselect the .venv interpreter and reload the window.

• If make uses the wrong Python, activate .venv in the terminal or run PYTHON=.venv/bin/python make test.

• If Windows activation is blocked, switch the terminal profile to Command Prompt and run .\.venv\Scripts\activate.bat.

• If a model backend import is missing, install the matching backend extra rather than broad optional dependencies.

• Avoid committing generated runtime output under artifacts/, docs/_build/, or local virtual environment directories.