> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layest.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure Your Layest Agent: Models, Instructions & Tools
> Learn all agent configuration options in Layest: choose AI models, write system prompts, attach tools and integrations, set memory, and tune behavior.
Every Layest agent is shaped by its configuration — the collection of settings that defines what model it uses, how it behaves, what tools it can call, and how it handles edge cases. Whether you created your agent from a template or built it from scratch, understanding each configuration section lets you tune your agent precisely for its intended role. This page covers every setting available in the agent configuration panel.
To access an agent's configuration, open **Agents** in the sidebar, click the agent you want to edit, and select the **Configuration** tab.
Changes to a live (Active) agent take effect immediately for all future runs. If you are making significant changes, consider switching the agent to **Draft** mode first, testing your changes, and then re-activating it to avoid disrupting ongoing workflows.
***
## Configuration Sections
The **Basic Info** section sets your agent's identity within the Layest workspace. These fields are visible to your teammates and help everyone understand what the agent does at a glance.
| Field | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | A short, descriptive label for the agent (e.g., "Invoice Extraction Agent"). Appears in the agent list, run logs, and notifications. |
| **Description** | A one-to-two sentence summary of the agent's purpose. Shown on the agent card and in the Agent Library if you submit the agent as a template. |
| **Avatar** | An optional image or emoji that represents the agent visually. Useful when your workspace has many agents. |
| **Tags** | Optional labels for organizing agents by team, project, or environment (e.g., `production`, `finance`, `beta`). |
Use a consistent naming convention across your workspace — for example, `[Team] [Function] Agent` — so agents remain easy to find as your list grows.
The **Model** section controls which AI model powers your agent and how that model generates responses. This is one of the most impactful configuration choices you will make.
### Choosing a Model
Layest supports models from multiple providers. Use the dropdown to select from available options:
| Model | Best For |
| ----------------- | -------------------------------------------------------------- |
| GPT-4o | Complex reasoning, instruction-following, multi-step tasks |
| GPT-4o mini | Cost-efficient tasks, high-volume workflows |
| Claude 3.5 Sonnet | Long-context analysis, nuanced writing, safety-sensitive tasks |
| Claude 3 Haiku | Fast, lightweight responses at low cost |
| Gemini 1.5 Pro | Multimodal tasks involving text and images |
Model selection directly affects your credit consumption per run. High-capability models cost significantly more per token than lightweight models. Review your plan's credit limits and estimate run frequency before selecting a model for production workflows.
### Model Parameters
After selecting a model, you can fine-tune its generation behavior:
**Temperature** (`0.0` – `2.0`)
Controls how creative or deterministic the model's responses are. Lower values (e.g., `0.2`) produce consistent, predictable outputs — ideal for data extraction or structured tasks. Higher values (e.g., `0.9`) produce more varied, creative responses — useful for brainstorming or content generation.
**Max Tokens**
Sets the maximum length of the model's response in tokens (roughly 0.75 words per token). Set this high enough to accommodate your expected output length, but not so high that it wastes credits on padding.
**Top P** *(Advanced)*
An alternative to temperature for controlling output diversity. Most users should leave this at the default value (`1.0`) unless they have specific needs.
```json theme={null}
{
"model": "gpt-4o",
"temperature": 0.3,
"max_tokens": 1024,
"top_p": 1.0
}
```
The **Instructions** field contains the system prompt — the foundational message your agent receives before every conversation or task. This is where you define the agent's role, persona, rules, and constraints.
### Writing Effective Instructions
A well-written system prompt is specific, structured, and honest about what the agent can and cannot do. Include:
* **Role definition** — who the agent is and what it is responsible for
* **Task list** — explicit steps or behaviors you expect
* **Tone and style** — how the agent should communicate
* **Constraints** — what the agent should never do
* **Escalation rules** — when and how to hand off to a human
### Example System Prompt
```text theme={null}
You are a Tier-1 customer support agent for Acme Corp, a B2B SaaS company.
Your responsibilities:
1. Answer questions about Acme Corp's product features, pricing, and integrations.
2. Help users troubleshoot common issues by searching the knowledge base.
3. If an issue cannot be resolved within 3 exchanges, create a support ticket
and inform the user of the ticket ID.
Guidelines:
- Always respond in a professional, empathetic tone.
- Never share internal pricing documents, roadmaps, or employee information.
- If a user asks something outside your scope, say: "That's outside what I
can help with directly — let me connect you with the right team."
- Keep responses concise: aim for 3–5 sentences unless a detailed explanation
is explicitly needed.
Current date: {{current_date}}
User name: {{user.name}}
```
You can use **template variables** in your instructions (e.g., `{{user.name}}`, `{{current_date}}`). Layest substitutes these at runtime with live values from the session context. Click the **Variables** button above the instructions field to see all available variables.
### Versioning
Every time you save updated instructions, Layest stores the previous version automatically. Open the **Version History** tab to compare versions or roll back to an earlier instruction set.
The **Tools & Integrations** section lets you attach capabilities to your agent — giving it the ability to search the web, read files, call APIs, query databases, send messages, and more.
### Adding a Tool
1. Click **Add Tool** in the Tools & Integrations panel.
2. Browse the tool catalog or search by name.
3. Select a tool and configure any required settings (e.g., which Slack channel to post to, which database to query).
4. Click **Save** to attach the tool.
Attached tools are listed in the panel with their current status (Connected / Needs Auth / Error). The agent can call any connected tool during a run based on its instructions.
### Tool Categories
| Category | Examples |
| ---------------------- | --------------------------------------------------------- |
| **Knowledge & Search** | Knowledge Base Search, Web Search, Document Reader |
| **Communication** | Slack, Email, Microsoft Teams |
| **Productivity** | Google Calendar, Notion, Confluence |
| **CRM & Sales** | Salesforce, HubSpot, Pipedrive |
| **Data & Analytics** | SQL Query, Google Sheets, BigQuery |
| **Developer** | GitHub, Jira, Linear, PagerDuty |
| **Custom** | HTTP Request (call any REST API with a custom definition) |
Tools that require OAuth authentication will prompt you to connect your account the first time you add them. Credentials are stored securely in your workspace and can be managed from the [Integrations](/capabilities/integrations) page.
### Controlling Tool Use
You can instruct the agent when and how to use each tool through your system prompt. For example:
```text theme={null}
Always search the knowledge base before answering a product question.
Only create a support ticket if the user explicitly requests escalation
or the issue is unresolved after three troubleshooting steps.
```
The **Memory** section controls whether your agent retains information across conversations and how it retrieves relevant context during a run.
### Memory Types
**Conversation Memory**
When enabled, the agent remembers previous messages within an ongoing session. This allows multi-turn conversations where the agent can reference what was said earlier without the user repeating themselves.
* **Session Memory** — retained only for the duration of a single run or conversation session. Cleared when the session ends.
* **Persistent Memory** — facts and preferences the agent learns are stored beyond the session and recalled in future conversations with the same user.
**Knowledge Base Retrieval**
When you attach a knowledge base to your agent, it uses semantic search to retrieve relevant documents before generating a response. Configure:
* **Top K Results** — how many document chunks to retrieve per query (default: `5`)
* **Similarity Threshold** — minimum relevance score for a chunk to be included (default: `0.75`)
* **Retrieval Strategy** — `Semantic` (meaning-based), `Keyword`, or `Hybrid`
Enabling persistent memory means the agent stores data about your users. Review your organization's data retention and privacy policies before turning this on for production agents.
### Disabling Memory
If your agent handles stateless tasks (e.g., single-turn data extraction, document formatting), disable conversation memory entirely to reduce token usage and keep runs fast and predictable.
The **Behavior Settings** section handles edge cases — what the agent does when it is uncertain, when a user asks something out of scope, or when a run needs to be handed off to a human.
### Fallback Response
The fallback response is what your agent says when it cannot answer confidently or when an error occurs. Define a clear, helpful message rather than leaving it to the model's default behavior.
```text theme={null}
I'm sorry, I wasn't able to find a good answer to that. Please reach out to
our support team at support@acmecorp.com, and a human agent will get back
to you within one business day.
```
### Escalation Rules
Define conditions under which the agent should escalate to a human or trigger an external workflow:
| Trigger | Action |
| ------------------------------------------------------ | --------------------------------------------- |
| User expresses frustration or uses escalation keywords | Hand off to live chat queue |
| Agent fails to resolve an issue after N turns | Create a support ticket automatically |
| Confidence score below threshold | Reply with fallback and alert a Slack channel |
Escalation actions can include sending a notification, creating a record in a connected integration (e.g., Zendesk ticket, Jira issue), or triggering a separate Layest workflow.
### Content Moderation
Toggle **Input Moderation** to automatically screen user messages for policy violations before they reach the model. Toggle **Output Moderation** to screen the agent's responses before they are delivered. These settings use Layest's built-in safety filters.
Disabling output moderation is not recommended for customer-facing agents. Even well-instructed models can occasionally produce unexpected responses; moderation provides an important safety net.
### Response Timeout
Set a maximum time (in seconds) the agent is allowed to spend generating a response. If the timeout is exceeded, the agent returns the fallback message and logs a timeout error. The default is `30` seconds.
***
## Saving and Versioning
Every time you click **Save**, Layest creates a new configuration version and records who made the change and when. You can view, compare, and restore any past version from the **Version History** tab on the agent detail page.
Add a short note in the **Change Description** field when saving significant updates. This makes the version history much easier to navigate when you need to track down when a behavior changed.
***
## Next Steps
Learn how to run your configured agent manually, via triggers, or on a schedule.
Monitor every agent run, inspect detailed logs, and track performance metrics.