Deep-Dive: Agents and Prompts

This module provides a deeper understanding of how agents and prompts work in Airgentic. Read this when you need to create specialist agents, customise agent behaviour, or understand how the AI decides what to say.

Who this is for

• Platform administrators who configure agents
• Technical owners who write or customise prompts
• Anyone who wants to understand how agent behaviour is controlled

What you'll learn

• How the agent routing system works
• When to create specialist agents vs use the Frontline
• How prompts control agent behaviour
• How to use modular prompt components effectively
• Best practices for prompt writing
• How to test and debug agent behaviour

The agent system

How routing works

When a user asks a question:

1. Frontline receives the question — The Frontline agent is always the first to see incoming questions
2. Frontline evaluates specialist agents — It reads the role description of each specialist agent
3. Frontline decides — Either handle the question itself or delegate to the best-fit specialist
4. Selected agent responds — The chosen agent processes the question using its prompt and functions

This routing happens automatically based on the role descriptions you write.

The Frontline agent

The Frontline is a special built-in agent:

• Always active, cannot be deleted
• Handles questions when no specialist is a better fit
• Makes routing decisions for all incoming questions
• Has limited configuration options (some fields are disabled)

Most questions can be handled by the Frontline alone. Only create specialists when you need genuinely different behaviour.

Specialist agents

Specialist agents handle specific question types:

Each specialist has:
- Role description — Tells the Frontline when to delegate to this agent
- Prompt — Instructions for how this agent behaves
- Functions — Actions this agent can perform
- Search scope — Which content this agent can access

When to create a specialist agent

Good reasons to create a specialist

When to stay with the Frontline

Avoiding over-specialisation

• Each agent adds configuration complexity
• Routing errors increase with more agents
• Start simple and add specialists only when clearly needed
• You can always add agents later

Prompt fundamentals

What prompts do

Prompts are the instructions that tell an agent:
- Who it is (identity)
- How it should communicate (tone)
- What it should and shouldn't do (guardrails)
- How to structure responses (output format)
- How to use information (retrieval behaviour)

The agent follows these instructions when generating responses.

Modular prompt architecture

Airgentic uses modular prompts for maintainability:

Agent Prompts — The main prompt file assigned to an agent. Contains agent-specific instructions and references to shared components.

Prompt Components — Reusable building blocks that can be included in multiple agent prompts:

Syntax for inclusion:

{{prompt:Component Name}}

When the agent runs, the component content is substituted inline.

Why modular prompts matter

• Consistency — All agents share the same identity and guardrails
• Efficiency — Change a component once, and all agents using it are updated
• Clarity — Agent-specific prompts focus on what makes that agent unique

Writing effective prompts

Be specific and clear

Too vague:

Be helpful and answer questions well.

Better:

When answering questions about our products, include the product name, key specifications, and a link to the product page. If you don't have enough information to fully answer, say so clearly and suggest the user contact support.

Use structured sections

Organise prompts into clear sections:

## Identity
You are the customer support assistant for Acme Corp...

## Tone
Communicate in a friendly but professional manner...

## Guardrails
Never provide medical advice...
Never share internal processes...

## Response Format
Keep responses under 200 words unless detailed instructions are needed...

Be explicit about boundaries

Tell the agent what not to do:
- Topics to decline or redirect
- Information it shouldn't share
- Actions it shouldn't take

Include examples when helpful

Examples clarify expected behaviour:

When users ask about pricing:
- If asking about a specific product, provide the listed price and link
- If asking for a quote, explain they should contact sales
- Example: "Our Widget Pro is $99. For custom pricing on bulk orders, please contact sales@example.com."

Keep it maintainable

• Use prompt components for shared content
• Avoid duplicating instructions across agents
• Write prompts that other team members can understand

Agent configuration

Status settings

Best practice: Keep new agents in Testing until thoroughly verified, then move to Live.

Role descriptions

The role description is critical for routing. Write it so the Frontline can correctly decide when to delegate:

Too vague:

Handles customer questions.

Better:

Handles technical questions about product installation, troubleshooting error codes, and resolving hardware malfunctions. Does not handle pricing, returns, or account questions.

Search scope

Restrict an agent's search results using URL prefixes:

https://www.example.com/products/
https://www.example.com/support/

This agent will only see content from those URL paths.

Use search scope when:
- An agent should focus on specific content areas
- You want to prevent an agent from accessing certain information
- Different agents need access to different knowledge bases

Testing agents

Using Admin Chat

Admin Chat is essential for testing agents:

1. Set the agent to Testing status
2. Ask questions that should route to your agent
3. Check if routing happens correctly
4. Verify the response quality

Using the Trace Log

The Trace Log shows exactly what happened:

Common issues to look for:
- Wrong agent handling the question → Adjust role descriptions
- Missing search results → Check search scope or content indexing
- Unexpected responses → Review the prompt instructions

Test systematically

Test with varied questions:
- Clear cases that should obviously go to your specialist
- Edge cases that could go either way
- Cases that should stay with Frontline
- Questions with no good answer in the knowledge base

Common pitfalls

Overlapping role descriptions

If two agents have similar role descriptions, routing becomes unpredictable.

Fix: Make role descriptions mutually exclusive or prioritise one over the other.

Prompts that are too restrictive

Over-constraining the agent can make it unhelpful.

Fix: Balance guardrails with flexibility. The agent should be safe but still useful.

Prompts that are too permissive

Under-constrained agents may say things you don't want.

Fix: Add explicit boundaries for sensitive topics.

Not testing edge cases

The happy path works, but unusual questions cause problems.

Fix: Test with adversarial and edge-case questions before going live.

Version control

Prompt history

Every prompt save creates a version:
- Timestamp and author recorded
- Commit message describes the change
- View and restore any previous version

Access: Edit Prompts → Select prompt → View History

Rollback process

If a change causes problems:
1. Open the prompt editor
2. Click View History
3. Select the previous working version
4. Click Restore This Version
5. Review and save

Related documentation

• Agents Overview — Managing the agent list
• Creating an Agent — Step-by-step creation
• Editing an Agent — Configuration options
• Edit Prompts — Prompt management
• Editing a Prompt — The prompt editor
• Admin Chat — Testing and debugging

Back to: Optional Deep-Dives