> ## Documentation Index
> Fetch the complete documentation index at: https://ade-ac1c6011-ade-im-seeing-error-messag-eright-58df792e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run your first agent

> Choose between a direct chat and a structured worker run for your first ADE task — with step-by-step instructions for each approach and guidance on what to try first.

You have a lane ready. Now it is time to run an agent in it. ADE offers two paths depending on the scope of the task.

***

## Two good first paths

<Tabs>
  <Tab title="Agent Chat (recommended for first run)">
    Use Agent Chat when the task is small and you want the fastest iteration loop. Chat is conversational — you describe what you want, the agent makes changes, you review and iterate.

    <Steps>
      <Step title="Open the lane chat">
        Select your lane in the Lanes panel. Click the **Chat** button in the lane toolbar, or press `Cmd+K`. A new chat session opens with automatic context injection from the lane's pack.
      </Step>

      <Step title="Choose a model (optional)">
        The model selector in the chat header defaults to your configured preferred model. Click it to switch models for this session. If you set up Anthropic, Claude Sonnet is a good default for a first task.
      </Step>

      <Step title="Send one narrow task">
        Start with something small and easy to review. Type your task description and press Enter. The agent receives your message along with the injected context and begins working immediately.

        See [suggested first prompt](#first-prompt-to-try) below.
      </Step>

      <Step title="Watch the agent work">
        As the agent processes your request, you will see:

        * **Text responses** explaining what it plans to do
        * **Tool call blocks** showing file reads, writes, and terminal commands in expandable cards
        * **A progress indicator** in the chat header showing token usage

        Tool calls that take more than a few seconds show a spinner with elapsed time. Click to expand and see partial output as it streams.
      </Step>

      <Step title="Review the diff">
        After the agent finishes, switch to the **Files** view (or stay in the lane's center pane) to inspect what changed. ADE shows a side-by-side diff of every modified file.

        If the changes look good, you can commit directly from the Files view or ask the agent to commit for you.
      </Step>
    </Steps>

    <Tip>
      If the agent asks a question, a question modal appears in the chat. Read the options, select your answer, and the agent continues. This is ADE's **AskUserQuestion** flow — the agent pauses cleanly instead of guessing when it needs your input.
    </Tip>
  </Tab>

  <Tab title="Worker run (for structured work)">
    Use a Worker run when the task needs a formal plan, parallel workers, validation, or a stronger audit trail. Workers are overkill for a first test — but if you want to see ADE's full orchestration, here is how.

    <Steps>
      <Step title="Open Workers">
        Click **Workers** in the left sidebar. Click **+ New Worker run**.
      </Step>

      <Step title="Set a goal">
        Write a clear, specific goal. The planner agent uses this to generate a structured execution plan.

        Example: *"Add a REST endpoint `GET /api/health` that returns `{ status: 'ok' }` with a corresponding test."*
      </Step>

      <Step title="Choose launch mode">
        Select **Supervised** for your first worker run. This pauses for your approval before the agent starts executing — so you can review the plan before any code is written.
      </Step>

      <Step title="Review the plan">
        The planner generates a step-by-step execution plan. Review the steps, lane assignments, and estimated cost. Click **Approve** to proceed or **Edit** to adjust.
      </Step>

      <Step title="Monitor execution">
        Workers execute the plan. The worker detail panel shows:

        * Live status of each step (queued, running, completed, failed)
        * Terminal output from each worker
        * File changes and tool call logs

        When all steps complete, the worker run enters validation.
      </Step>

      <Step title="Review results">
        Check the Artifacts tab for test reports, code changes, and summaries. Create a PR from the worker run's result lane if the work looks good.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## First prompt to try

For your first agent task, use something narrow enough to verify the full loop but broad enough to exercise the core workflow:

```text theme={null}
Add a GET /health endpoint that returns { "status": "ok" } and add one test for it.
```

Other good first prompts:

* `"Add a TypeScript type for UserPreferences with name (string), theme (light | dark), and notifications (boolean)."`
* `"Write a utility function that validates email addresses and add 3 unit tests for it."`
* `"Update the README with a Getting Started section that explains how to install dependencies and run the dev server."`

***

## What to expect during your first session

**Context injection**: ADE prepends the Lane Pack before the agent sees your message — so the agent already knows the project structure, lane intent, and recent file state.

**Tool calls**: The agent reads files, writes code, and runs commands via ADE CLI tools. Each call appears as an expandable block in chat. No per-call permissions required in the default config.

**Session recording**: Every message and tool call is captured in the session transcript, viewable in the History tab.

**Interrupting**: Press **Escape** or click **Stop** at any time. The agent reports partial results and the conversation continues.

***

## After your first task

Once you have verified the result:

<Steps>
  <Step title="Review the diff">
    Open the Files view scoped to your lane. Check every changed file. The side-by-side diff makes it easy to spot issues.
  </Step>

  <Step title="Commit the changes">
    If the changes look correct, commit them. You can:

    * Ask the agent: *"Commit these changes with a descriptive message"*
    * Use the git operations bar at the bottom of the Files view
    * Use the terminal in the lane to run `git commit` manually
  </Step>

  <Step title="Create a PR (optional)">
    Ask the agent: *"Create a PR for this work"* — or use the lane's PR action in the right inspector. ADE pre-fills the PR title and description from the Lane Pack.
  </Step>
</Steps>

***

## Troubleshooting your first run

<AccordionGroup>
  <Accordion title="The agent is not responding" icon="circle-question">
    Check that at least one AI provider is configured and verified in **Settings > AI Providers**. A green indicator means the provider is ready. If the provider shows a red indicator, verify your API key.
  </Accordion>

  <Accordion title="The agent made changes to the wrong files" icon="file-circle-exclamation">
    Verify you are in the correct lane — check the lane selector in the chat header. If the agent is in the Primary Lane, it writes to your main working directory. Create a Worktree Lane for agent-driven tasks.
  </Accordion>

  <Accordion title="The agent's changes do not compile or tests fail" icon="circle-xmark">
    This is normal for a first run, especially on complex codebases. The Lane Pack may not have captured all relevant context. Try:

    1. Tell the agent what failed: *"The tests are failing with this error: \[paste error]"*
    2. The agent will read the error and attempt a fix
    3. If it still fails, provide more context about your project's testing setup
  </Accordion>

  <Accordion title="The session is taking very long" icon="clock">
    Check the token usage indicator in the chat header. If the agent is consuming tokens but not producing visible output, it may be reading large files. Press **Escape** to interrupt, then try a more focused prompt.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Key Concepts" icon="book" href="/key-concepts">
    Understand every core concept in ADE: Lanes, Packs, Workers, the CTO, Automations, and more.
  </Card>

  <Card title="Chat Capabilities" icon="toolbox" href="/chat/capabilities">
    See the full list of what the chat agent can do — file operations, git, PRs, worker runs, and more.
  </Card>

  <Card title="Workers" icon="bullseye" href="/cto/workers">
    Learn how to configure multi-step worker runs with planning, validation, and cost tracking.
  </Card>

  <Card title="Multi-Agent Setup" icon="users" href="/guides/multi-agent-setup">
    Run parallel agents across multiple lanes and monitor them from the Workspace Graph.
  </Card>
</CardGroup>