# Tips for Working with the Agent

## Overview

The Bluebricks agent works from live infrastructure data and IaC state. Specific, well-structured prompts yield faster and more precise answers.

## Use resource identifiers

When you have a resource ID, ARN, environment slug, or collection name, use it. The agent pulls live infrastructure data, so an exact identifier means an instant, precise lookup. Descriptions lead to broader searches and sometimes ambiguous results.

> **Good:**
>
> "What manages `sg-0a1b2c3d4e5f`? Does anything else share it?"
>
> "Show me the current state of the `prod-payments` environment."

> **Instead of:**
>
> "What manages our main security group?"
>
> "What's going on with payments?"

{% hint style="success" %}
If you have raw IaC output or console logs, share the resource ID and let the agent pull live state directly. Live data is always more accurate than pasted text.
{% endhint %}

## Specify live state or IaC

The agent can answer from two angles: what is actually running in your cloud account, and what your IaC says should be running. These can differ, and that difference is drift. One word of context ("Terraform", "Helm", or "live") removes all ambiguity.

> **Good:**
>
> "What does Terraform think the instance type is for `i-0abc123`? What is it actually running as in AWS?"
>
> "Is our RDS cluster in `us-east-1` managed by IaC, or is it unmanaged?"

> **Instead of:**
>
> "What's the instance type of that RDS cluster?"

## Scope to a collection or environment

Infrastructure data in Bluebricks is organized by collection. When you include the collection or environment name, the agent skips the org-wide search and goes straight to the right scope.

> **Good:**
>
> "In the production collection, are there any EC2 instances not managed by Terraform?"
>
> "Show me all environments in the `platform-team` collection that are currently drifted."

> **Instead of:**
>
> "Are there any unmanaged EC2 instances?"

{% hint style="info" %}
Omitting the scope is fine when you want org-wide results. If you only care about one collection or environment, say so.
{% endhint %}

## Share what you expected

When something looks wrong, give the agent your baseline. The agent can show you what changed, but it pinpoints the relevant change faster when it knows what you think should be true.

> **Good:**
>
> "Our `prod-api` EKS cluster should be running version 1.29, but something looks off. Can you check what version is live and whether Terraform agrees?"
>
> "Security group `sg-0a1b2c3d` should only allow port 443 inbound. Has anything changed?"

> **Instead of:**
>
> "Something seems wrong with our EKS cluster."

## Ask for topology and blast radius

The agent can show relationships: what is in a VPC, what shares a security group, what sits in a subnet. A hint like "topology", "blast radius", or "what's connected" triggers the right query.

> **Good:**
>
> "Show me everything inside `vpc-0abc123`: subnets, instances, load balancers."
>
> "What's the blast radius if I change security group `sg-0a1b2c3d`? What resources reference it?"

> **Instead of:**
>
> "List EC2 instances."

## Read the deployment plan before approving

When you trigger a deployment, the agent generates a plan and presents it before applying anything. That plan is the right moment to ask questions: what does this resource do, is this change destructive, why is it being replaced? The agent never auto-approves.

> **Good:**
>
> After seeing the plan: "Why is the RDS instance being replaced rather than updated in-place? That's a stateful resource."
>
> "The plan modifies a security group. Show me the before and after for the inbound rules."

> **Instead of:**
>
> Approving a plan without reading it because it looked short.

{% hint style="warning" %}
A short plan can still contain a destructive change. One line like `aws_db_instance.main: must be replaced` can mean data loss. For production environments, review every resource change before approving.
{% endhint %}

## Separate reads from writes

The agent treats read operations (listing resources, showing configs, explaining topology) differently from write operations (deploying, planning, updating infrastructure). For writes, it always pauses for your explicit confirmation. Stating your intent upfront avoids unnecessary back-and-forth.

> **Good:**
>
> "Plan a deployment of `aws-rds-postgres` to the staging collection. Don't apply yet; I just want to see what it would do."
>
> "How many Lambda functions do we have in `eu-west-1`?"

> **Instead of:**
>
> "Deploy the RDS blueprint." (Which collection? Which version? Plan first or apply directly?)

## Quick reference

<table><thead><tr><th width="208.9453125">Practice</th><th>One-liner</th></tr></thead><tbody><tr><td>Use identifiers</td><td>A resource ID or slug beats a description every time</td></tr><tr><td>Specify state or IaC</td><td>Say which layer you care about: live cloud or Terraform</td></tr><tr><td>Scope to collection</td><td>Name the collection or environment to skip the broad search</td></tr><tr><td>Share your baseline</td><td>Tell the agent what you expected when something looks wrong</td></tr><tr><td>Ask for topology</td><td>"What's connected" and "blast radius" unlock relationship views</td></tr><tr><td>Read the plan</td><td>Read it, ask questions, then decide; never skip this step</td></tr><tr><td>Separate reads from writes</td><td>Make your intent clear; the agent pauses for confirmation on all writes</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/agent/prompting-best-practices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.