Guide for Using the Dyad Agent Effectively

Basic Controls

Getting Started

Start the agent via the VS Code command pallette.

Once the agent screen loads, click "Start New Chat" to begin interacting with the agent. The agent is then ready to take your input.

Handling API Errors

The agent handles API errors gracefully. If you encounter an error (rate limits, service overload, etc.), it will display in red:

- ✗ API rate limit exceeded. Please wait a moment before trying again.

or

- ✗ API service is currently experiencing issues. Please try again in a few moments.

Simply type continue and the agent will resume from where it left off - you don't need to restart or repeat your request.

Interrupting the Agent

Press ESC at any time to pause the agent mid-execution. This lets you redirect it with new instructions or corrections.

Exiting the Application

Press Ctrl+C to exit the Dyad Agent at any time.

Understanding Sessions & Capabilities

While powerful, we are only at the beginning of where this technology can go. Although it can feel magical, understanding how the agent works will help you get the best results.

Session Management:

• Each session is fresh - The agent doesn't remember previous conversations. When you start a new session, it has no memory of what you built before

• Use Git for continuity - Since there's no conversation history between sessions, commit your work regularly. This lets you show the agent what exists and build on it in new sessions

• Document as you go - Save important outputs, explanations, and decisions during the session

File and Data Tips:

• Images and text work great - The agent can read screenshots, diagrams, and text files

• Convert PDFs to images - The agent can't parse PDFs directly; convert them to images first

• Stay in your sandbox - The agent works within the Dyad library directory you specified at startup

What the Agent Can Do:

• Read and write code across your Dyad library

• Install Julia packages (via package manager) and system software (via Julia tool as bash)

• Run simulations, create visualizations, and generate plots

• Use Git for version control

• Leverage external tools you've installed (like OpenModelica)

• Debug, refactor, and validate models

Current Constraints:

• No web browsing during sessions (can't look up external docs)

• Single conversation at a time (processes one request at a time)

• No undo feature (use Git commits for rollback capability)

Remember: This technology is evolving rapidly. What you see today is just the beginning. The agent is a powerful assistant that gets better as you learn to work together!

Useful Prompts and Best Practices

Philosophy: Share Your Mental Model

The agent will do what you ask, but the quality of results depends on how well you communicate your intent. For simple, well-understood models, a direct request works fine (as we saw with "Build me an RLC circuit"). For complex systems, it's better to discuss and plan first, then implement. Think of it as: discuss → plan → implement rather than jumping straight to implementation. The agent can't read your mind - share your mental model of what you want to build, and it will build it better.

Always End with Protocols

We started with just "Build me an RLC circuit," but for best results, end your request with "follow your modeling and debugging protocols." This ensures the agent invokes all its protocols. A better starting prompt would be:

"Build me an RLC circuit, follow your modeling and debugging protocols."

For simple conversations, this will usually trigger automatically. However, if you want a more disciplined approach - discussing the model, its physics, what exists in the library, and what components need to be built from scratch - have that exploratory conversation first. Then, right before you want the agent to start implementing, tell it to follow its modeling and debugging protocols. This triggers the disciplined implementation phase.

Be Specific About Requirements

The agent will make assumptions on your behalf if you don't provide details. Always specify:

• The type of model you're building (e.g., "transistor amplifier," "DC motor controller")

• Physics and behavior it should exhibit (e.g., "must handle square wave input," "should show saturation effects")

• Expected outputs (e.g., "plot frequency response," "validate steady-state behavior")

• Timeouts for long operations - If asking the agent to run lengthy simulations or installations, mention it might take time so it plans accordingly

Example: Instead of "Build me a transistor," use "Build me an NPN transistor amplifier that can amplify a 1kHz square wave with gain of 10."

Work Incrementally for Complex Models

For complicated systems, build incrementally:

1. Start with the core functionality

2. Test and validate each piece

3. Add complexity step by step

4. Let the agent validate at each stage

This approach makes debugging easier and ensures each component works before integration.

Use ESC to Course-Correct

Don't let the agent go down the wrong path - interrupt early if you see it heading in the wrong direction. Press ESC and provide new instructions to redirect it.

Leverage the Persistent Julia Session

The agent maintains state throughout the conversation, so you can:

• Ask it to inspect variables or intermediate results

• Run quick tests without recompiling

• Modify parameters and re-run simulations

Deep Debugging

If you want to debug a model thoroughly, tell the agent: "Debug my model using your debugging protocol." This invokes the full debugging workflow with comprehensive validation.

Request Specific Validation

Tell the agent what tests or checks you want:

• "Verify energy conservation"

• "Check frequency response from 1Hz to 10kHz"

• "Validate steady-state behavior"

Control the Output

If you don't want plots or summaries, say so upfront: "Build this model but don't create plots."

Reference Existing Components

If you know a similar component exists, mention it: "Build this like the existing OpAmp component" or "Use the same interface as the Resistor component."