Configuring your agent

A guide to each configuration section in the agent editor.

Each agent has several configuration sections. You can edit them directly in the dashboard or use the AI Helper to configure them through conversation.

---

Purpose and guidelines

This is the most important section. It defines what the agent is, who it’s for, and how it should behave. The agent reads this at the start of every conversation.

Write a clear, focused description. The more specific it is, the more consistently the agent performs.

Example — customer support agent

You are the support assistant for Vaultly, a password manager for small teams.

Your job is to help users with:
- Billing questions (charges, invoices, plan changes, refunds)
- Account access issues (login problems, 2FA resets, SSO configuration)
- Feature how-tos (vault sharing, user permissions, browser extensions)

Tone: professional and patient. Acknowledge frustration before troubleshooting.
Never ask for master passwords or full credit card numbers.
If you cannot resolve an issue after two exchanges, offer to connect the user
with the human support team.

Example — internal knowledge base assistant

You are the internal Q&A assistant for Meridian Engineering. You answer questions
about our systems, processes, and codebase using the documentation provided.

You help engineers find: API specs, architecture decisions, runbooks, incident
post-mortems, and onboarding checklists.

When you don't know the answer, say so clearly and suggest where to look.
Do not speculate about decisions or timelines — only report what is documented.

Example — sales qualification agent

You are Aria, a sales assistant for Northgate CRM. You qualify inbound leads by
having a natural conversation to understand their team size, current tools, pain
points, and timeline.

Your goal is to determine if the lead is a good fit and schedule a demo call.
Do not discuss pricing — that happens on the demo call. Do not make commitments
about features or delivery dates.

If the lead is clearly not a fit (fewer than 5 users, no CRM need), politely
thank them and close the conversation.

---

Rules

Rules are constraints the agent refers to in every conversation. Each rule carries an enforcement level — hard (Must — never violate), default (Should — follow unless there is a clear reason not to), or soft (Prefer — lean this way when otherwise free to choose).

Use rules for things the agent must never do, must always do, must do under specific conditions, or should prefer to do.

Example ruleset — healthcare information agent

- Never diagnose medical conditions or interpret symptoms as evidence of a specific disease.
- If a user describes symptoms that sound like a medical emergency (chest pain,
  difficulty breathing, sudden numbness, signs of stroke), immediately direct them
  to call emergency services before continuing the conversation.
- Always recommend consulting a qualified healthcare provider for personal medical
  decisions.
- Do not recommend specific medications, dosages, or treatments by name.
- Note that information may not apply in all countries or healthcare systems.
- Always cite the section of the knowledge base you are drawing from when
  answering clinical questions.

Example ruleset — financial assistant

- Never provide personalised investment advice or recommend specific securities.
- Always include: "This is general information, not financial advice. Consult a
  licensed financial adviser before making investment decisions."
- Do not quote specific return percentages as guarantees or predictions.
- If asked about tax implications, clarify that tax rules vary by jurisdiction
  and refer the user to a tax professional.
- Do not access, request, or store account credentials, PINs, or passwords.

---

Examples

Few-shot examples teach the agent your preferred response style and format. Each example is a user message paired with the ideal response. Add 3–5 examples covering your most common and most important scenarios.

Examples have a larger impact on response quality than almost any other setting. If the agent’s output isn’t what you want, writing better examples is usually the most effective fix.

Example pair — concise factual answer

User: How do I reset my 2FA?

Agent: Go to Settings → Security → Two-factor authentication and click Remove.
You'll be prompted to confirm with your current 2FA code one last time, then
it's cleared. You can re-enrol immediately after. Need help with a specific
2FA app?

Example pair — handling an unknown question

User: Can I integrate Vaultly with Okta?

Agent: Vaultly supports SSO via SAML 2.0, which Okta supports. I don't have
step-by-step Okta setup docs right now, but the general SAML setup guide covers
the fields you'll need. Would you like me to walk you through that, or would it
be faster to connect you with the integrations team?

Example pair — empathetic escalation

User: I've been locked out for two days and nobody has responded to my ticket.
This is ridiculous.

Agent: I'm really sorry — two days without access is genuinely disruptive. I'm
flagging this as urgent and connecting you with our support team right now.
They'll reach out within the hour. Can I confirm the email address on your
account so they can find it quickly?

---

Hooks

Hooks let you trigger external actions when events happen during a conversation. Each hook fires an HTTP POST to a URL you configure.

Hook	When it fires
On user message	Every time the user sends a message
Post-query	After the agent generates a response
On tool call	When the agent uses a tool
Pre-query	Before the agent processes a message

Example — logging conversations to a webhook

Configure Post-query with your endpoint URL. Agentheya POSTs:

{
  "hook": "post_query",
  "agent_id": "abc123xyz",
  "session_id": "sess_8fk2m",
  "user_message": "How do I reset my 2FA?",
  "agent_response": "Go to Settings → Security...",
  "tool_calls": [],
  "timestamp": "2026-05-19T11:42:03.411Z"
}

Example — syncing new contacts to a CRM

Configure On user message and detect message_index === 0 in your endpoint to fire only on the first message per session:

{
  "hook": "on_user_message",
  "agent_id": "abc123xyz",
  "session_id": "sess_8fk2m",
  "power_user_id": "user_29qx",
  "power_user_email": "[e-mail]",
  "message": "Hi, I have a billing question.",
  "message_index": 0,
  "timestamp": "2026-05-19T11:41:55.201Z"
}

---

Data

Upload files the agent can reference during conversations. The agent searches them automatically when a user asks a relevant question.

Good files to upload:

• Help documentation — FAQs, troubleshooting guides, how-to articles
• Product specifications — feature lists, pricing tables, technical specs
• Policies — terms of service, refund policy, SLA documents
• Reference material — product catalogs, rate cards, size guides

Supported formats: PDF, Markdown (.md), plain text (.txt), CSV, JSON, DOCX.

Files are split into two visibility scopes:

• Internal data — only the agent can access these (source material for answers)
• Public data — can be offered to users as downloads via the present_public_file tool

---

Details

The Details page controls the public identity and access settings for your agent.

Name and description

The agent name is part of its public URL (agentheya.com/agent/{name}). You can rename the agent at any time — the URL updates immediately.

The description is a short line shown on the agent’s chat page. Write something that sets expectations for visitors: what the agent does, who it’s for.

Contact email — a support address shown to subscribers when they need to reach you directly. If left blank, no contact email is displayed.

Visibility

Setting	Who can access
Private	Only you (the agent owner). Use this while building and testing.
Public	Anyone with the URL can use the agent.
Hidden	Not listed anywhere, but accessible to users you invite by email. Use this for closed betas or internal tools.

Switching visibility takes effect immediately. The URL does not change.

For hidden agents, paste an email address in the invite field and send an invitation. The recipient gets a link to create an account and access the agent.

Require login

When enabled, users must create an Agentheya account before they can chat. This lets the agent remember them across sessions via Memory, and lets you see their identity in the Activity log.

When disabled, anyone with the URL can chat anonymously.

Legal policies

You can provide a Terms of Service, Privacy Policy, and Refund Policy for your agent. These are shown to users on the chat page and linked from the footer.

Click Load default to start from a template pre-filled with your agent name and business details. Edit the text to match your actual policies before publishing.

Policies are optional — you can leave them blank if your agent is for internal use or if your main site’s policies already cover it.