> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinksheep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Builder

> How the conversational agent builder works, from prompt to deployed agent.

## Overview

The builder is a conversational interface where you describe the automation you want and Pinksheep assembles it into a deployable agent. There's no workflow canvas, no node editor, and no code. You talk, the builder builds.

## The builder conversation

A typical builder session follows this flow:

```mermaid theme={null}
graph TD
    A[Describe your automation] --> B[Builder asks clarifying questions]
    B --> C[Builder discovers tools]
    C --> D[Builder produces agent plan]
    D --> E{Test the agent}
    E -->|Pass| F[Approve & Deploy]
    E -->|Fail| G[Builder adjusts based on failure]
    G --> D
```

### 1. Describe what you want

Start with a natural language description. Be specific about:

* **What** the agent should do
* **Which apps** to use (use @mentions: `@HubSpot`, `@Slack`, `@Gmail`)
* **When** it should run (if scheduled)
* **Who** should be notified

Good prompt examples:

> "Every morning, pull unread emails from @Gmail and post a summary to #daily-digest in @Slack."

> "When a new contact is added to @HubSpot, enrich it with company data and propose CRM field updates for my review."

### 2. Clarification

The builder may ask follow-up questions to fill gaps:

* Which Slack channel to post to
* What data fields to include
* Whether to send automatically or queue for approval
* How frequently to run

Answer conversationally. The builder remembers everything from the current session.

### 3. Tool discovery

Behind the scenes, the builder discovers available tools from your connected apps via Composio. It matches your described task to specific API actions (e.g. `hubspot.list_contacts`, `slack.send_message`).

You don't need to know tool names or APIs. The builder handles mapping.

### 4. Agent plan (manifest)

Once the builder has enough information, it outputs a structured **agent plan** containing:

* **Steps**: Ordered list of actions with descriptions
* **Permissions**: What the agent reads, writes, and whether anything is irreversible
* **Schedule**: CRON expression and description
* **Estimated credits**: Cost range per run
* **Monthly projection**: Based on schedule frequency
* **Auth gaps**: Any apps that still need connecting

### 5. Testing

Click **Test this agent** to run a sandboxed dry-run. The test:

* Executes against your real connections
* Operates in a safe sandbox context
* Reports success/failure per step
* Shows actual credit cost

If the test fails, the failure details are shown inline and you can ask the builder to fix the issue in the same conversation.

You can also **skip the test** and deploy directly, though this is not recommended for agents that write to external systems.

### 6. Deployment

Click **Approve & Deploy** to make the agent live. The builder:

1. Verifies all connections are still active (pre-deploy health check)
2. Creates the agent with an idempotency key (prevents duplicate deploys)
3. Shows a success confirmation with a link to the dashboard

## Builder features

### @mentions

Type `@` followed by an app name to reference it in your prompt. The builder uses mentions to:

* Scope tool discovery to relevant apps
* Pre-fill connection requirements
* Detect which integrations are needed

### Repair mode

If a deployed agent fails, click **"Fix this agent"** from the agent detail page. This opens the builder with:

* The original agent configuration loaded
* The most recent failure details pre-filled
* Step-level error context

You can then iterate on the agent in conversation and redeploy.

### Schedule governance

The builder actively manages scheduling to prevent waste:

* Suggests the least frequent interval that meets your intent
* Pushes back on unnecessarily frequent schedules
* Always shows projected monthly cost before deployment
* Defaults: daily for reports, hourly for monitors, weekly for digests

### Context management

Long conversations are automatically trimmed to stay within model limits. The builder preserves:

* The first 2 turns (your original intent)
* The most recent 14 turns
* A state summary bridging the gap

This means you can have extended conversations without worrying about context loss.