AI Agent instructions: from generic to specialist

An AI Agent without a custom instruction acts like a new colleague with no briefing: it does something, but rarely the right way for your process. It interprets, assumes and delivers inconsistent results. The problem is not the AI, it is the absence of criteria.

Configuring instructions is not writing a creative prompt. It is encoding the operational policy of your process: what the agent does, how it responds, in what format it delivers and when it escalates to a human. By the end of this article, you will know how to write instructions that make the agent predictable, auditable and truly useful.
 

📖 What you'll understand here:

From the generic agent to the specialist

The difference between a generic agent and a specialist is in the instruction. An agent without a custom instruction uses only the card context to decide what to do. An agent with a well-defined instruction acts within a clear scope, with specific criteria and standardized behavior.

Think of the instruction as a colleague's scope. When you hire someone for ticket triage, you do not just say "resolve the tickets". You explain what is urgent, what language to use with the client, when to escalate to level 2 and how to record the resolution. The agent's instruction is exactly that: the set of criteria that defines its work.

Anatomy of a good instruction

An effective instruction has four components. They do not need to appear in this order, but all of them need to be present when the process requires precision.

Context

What this process is and what the agent's role is within it. Without context, the agent infers. With context, it acts within the correct scope.

Example: "You work in the IT ticket triage process. Your role is to classify the urgency of each ticket received and route it to the correct queue."

Decision criteria

The rules the agent should apply to make decisions. The more specific, the more predictable the result.

Example: "Classify as urgent when the ticket mentions loss of access to critical systems, a production failure or impact on more than 5 users. Classify as normal in the other cases."

Output format

How the agent should fill the card fields. Specify the exact values when the field is a select field.

Example: "Fill the @Urgency field with the values 'High', 'Medium' or 'Low'. Fill the @Summary field with a sentence of up to 20 words describing the problem."

Scope limit

What the agent should not do. Explicit is better than implicit.

Example: "Do not respond to the requester directly. Do not move the card to the resolution phase. Only classify and fill the fields."

Defining what the agent can and cannot do

Each agent behavior can run up to 3 actions per trigger: update fields, create a card, move the card to another phase, create a record or create a connected card. If the process requires more than 3 actions for the same trigger, split it into a second behavior or combine it with a complementary automation.

The scope limit should be explicit in the instruction. Agents without a limit tend to overstep the scope when the context is ambiguous. An instruction that says "analyze the document and fill the fields" may result in the agent also moving the card, if that is not explicitly forbidden.

The instruction is also the right place to define the behavior in cases of ambiguity. If the agent cannot determine the urgency of a ticket with the available information, what should it do? Fill in with "Undefined"? Escalate to a human? Leave the field blank? If the instruction does not say, the agent decides on its own.

Testing and refining

After saving the agent, test it with real cards before activating it at scale. Pipefy records the agent's activity in two places: in the card's Activities tab, to see the result of each run, and in the automation Logs, to investigate failures and unexpected behaviors.

The refinement cycle is: run, check the result, adjust the instruction, run again. The two most common errors are:

• Field filled with an incorrect value: the instruction did not specify the values accepted by the field. Add the exact values the field accepts, especially in select fields.
• Agent ran an action beyond the scope: the instruction had no explicit limit. Add a sentence like "run only these actions and no others".

Instruction examples by use case

IT ticket triage

Resume analysis for recruiting

Purchase request categorization

Before proceeding, confirm that you understand:

☐ The four components of an effective instruction

☐ The difference between an action limit and a decision criterion

☐ How many actions and behaviors an agent can have

☐ How to check the agent's results in the logs

☐ How to refine the instruction when the agent makes mistakes