> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/agent-builder/build/instructions.md). # Instructions **Instructions** is where you write what the agent does and how it does it — the agent's operating brief, in your words. The platform feeds this content to the underlying model on every turn, so the rules, tone, examples, and step-by-step procedures you put here shape every response the agent produces. It is the single most consequential page in the builder: a good set of instructions makes everything else work better; a vague or contradictory set makes the agent unreliable in ways that are difficult to debug later. Manage Agent → Instructions Reach this page from **Manage Agent → Instructions** in the left navigation. ### The three action buttons Three buttons sit above the editor body: * **Upload from file** (green) — bulk-import instructions from a file rather than typing them in the editor. Useful when the instructions exist elsewhere as a document and you want them in the agent verbatim. * **Improve with AI** (sparkles icon) — runs an AI pass over the current instructions. The platform automatically reviews the instructions you've written and suggests or applies improvements, replacing the manual work of self-editing for clarity, structure, and consistency. Use it as a second opinion after you draft, not as a substitute for thinking through what the agent should do. * **Best Practices to give instructions** — opens a side panel with the recommended template (see below). Useful as a structural scaffold the first time you author instructions, or when you're not sure your current set covers everything it should. #### The Best Practices side panel Instructions with the Best Practices side panel open Clicking **Best Practices to give instructions** opens a side panel titled `Best Practices for General Purpose Agents`. The panel narrows the editor to the left and renders the platform's recommended structure on the right. The general advice at the top: 1. Include a clear and concise objective or goal for the agent. 2. Include examples where possible. 3. Include details like format, data types, and any other relevant information. The recommended template — use the sections that apply, skip the optional ones:
SectionWhat Goes Here
Objective / GoalThe main purpose of the agent in one or two sentences.
Inputs RequiredWhat information the agent needs to do its job.
Process / StepsThe procedure the agent follows.
Outputs / DeliverablesWhat the agent produces.
Constraints / RulesLimitations, compliance requirements, things the agent must never do.
Tone / Interaction Style (optional)How the agent communicates with users.
Additional Instructions (optional)Anything else that didn't fit above.
Close the side panel with its own `×` when you're done; the editor returns to full width. ### What to put in instructions, and what not to The instructions field is the agent's operating brief, not its credentials store. Put the agent's **behavior** in instructions — what it does, the steps it follows, the rules it observes, the tone it uses, the examples that anchor good outputs. Do **not** put **secrets** in instructions. > **Important** Never paste API keys, passwords, tokens, or other credentials directly into the Instructions field. Credentials belong in Secrets & Variables. Reference them in skill configurations and instructions as `$secret.{name}`. Instructions content is included in every model call and may appear in execution traces, logs, and downstream systems — anywhere a secret pasted here would also appear. The same rule applies to other sensitive data: personally identifying information, customer records, and internal documents that shouldn't accompany every model call all belong outside the instructions field, behind references the agent can resolve at runtime. ### Saving The **Save** button sits in the top-right and activates when you've made changes. Saved changes go to the agent's draft; create a recoverable snapshot from the Draft Version popover. After saving, send a test message in the Agent Preview pane to verify the agent follows the new instructions before relying on the change in production. ### Why this matters Of every setting in the builder, the instructions field has the most direct effect on what the agent actually does. Two agents with the same model, same skills, and same attached knowledge will behave very differently if their instructions diverge. The Best Practices template exists because clean, well-structured instructions tend to produce predictable agents, and a few minutes spent putting the brief in the right shape prevents hours of debugging surprising behavior later. Treat this page as authoring, not as form-filling. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.uptiq.ai/agent-builder/build/instructions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.