Write specialists that know their job

The specialist contract

Description gets the right work. Instructions do the work right.

A specialist needs two different kinds of clarity. Its Description tells the router which visitor needs belong here. Its Instructions tell the selected specialist how to respond, what evidence to use, what information to collect, which actions are permitted, and where its responsibility ends.

The difference that prevents most routing mistakes

Routing signal

Description

Short, distinctive, written around visitor intent. Other workflow actors use it to decide whether this agent should own the turn.

Test: Could a colleague use only this sentence to send a customer to the right person?

Behavior playbook

Instructions

Detailed operating rules for the agent after selection: goals, steps, facts, boundaries, tools, confirmation, handoffs, and response behavior.

Test: Could a new team member follow this playbook without inventing company policy?

Do not paste the full playbook into Description. It makes route comparison noisy. Do not leave Instructions as a one-line department description. The agent may be routed correctly but then have no usable rules.

Every Agent field, explained

Open AI Website Chat → Agent Flows → a workflow → Add Agent. You can select an existing node and choose Edit later.

Identity and scope
Field	Meaning	Recommended use	Example
Name	The friendly role name administrators see on the canvas and in logs.	Name the job in ordinary language. Avoid internal acronyms and numbered agents.	Appointments Specialist
Key	A stable internal identifier used in workflow records.	Use lowercase words separated by underscores. Keep it stable when the friendly Name changes.	appointments_specialist
Description	The short scope summary used as a routing signal.	List the specific visitor intentions it owns and, where ambiguity is likely, one or two nearby intentions it does not own.	Handles visitors who want to schedule, reschedule, cancel, or check an existing appointment. Does not answer general service or billing questions.
Instructions	The detailed playbook used while the specialist is active.	Write role, goals, source rules, steps, missing-information behavior, tool rules, boundaries, handoff rules, and completion behavior.	See the full appointment pattern below.

Runtime settings
Field	Meaning	Recommended use	What to watch
Model	The OpenAI model used by this specialist.	Keep the tested default unless this particular job needs a deliberate speed, cost, or reasoning tradeoff. Confirm the model is available to your project before publishing.	A model name is operational configuration, not a quality guarantee. Model availability and pricing can change.
Temperature	Controls answer variation on a scale from 0 to 2.	Use low values for support, policy, booking, account, and action-oriented work. The form starts at 0.10. Raise it only for intentionally creative work.	High variation can make wording and decisions less repeatable. Temperature does not make unknown facts accurate.
Max Tokens	Caps the length of one specialist response.	Leave empty for normal use. Add a limit only when you have tested that complete useful answers fit inside it.	A value that is too low can cut off disclaimers, next steps, or a confirmation summary. Zero or empty means no specialist-specific cap from this field.
Knowledge Base	Allows this specialist to search synchronized website content when needed.	Enable it when the role must answer from policies, services, product pages, help articles, or uploaded files. Keep it off if the role should operate only from its narrow instructions and tools.	Knowledge access is broad to the site’s synchronized knowledge; it is not a per-agent private collection. Exclude sensitive material at the knowledge-source level.
Output Style	A concise note about tone, structure, length, and language behavior.	Describe presentation, not company facts or routing rules. Keep a shared brand voice, then add only role-specific differences.	Conflicting style rules across specialists make the conversation feel disjointed.
Sort Order	Controls the order of agents in admin screens and workflow data; lower numbers appear earlier.	Use 10, 20, 30 if your team benefits from a predictable order with room to insert another role. Use 0 when it does not matter.	Sort order is organization, not routing priority. Handoff Priority is a separate field.

A specialist instruction pattern that non-developers can maintain

Use headings and direct sentences. The AI does not need legalistic prose; it needs unambiguous operational rules.

Role and outcome

State who the specialist helps and what a successful conversation produces.

What you own

List included visitor intentions in the language customers use.

Trusted information

Say when to search the Knowledge Base or use a lookup tool. Say never to invent availability, price, policy, status, or action results.

Conversation steps

Define what to ask first, what information is required, and how to handle missing, conflicting, or corrected details.

Actions and confirmation

Name the permitted action tools and the condition for using each. Require a review of exact details before consequential action.

Boundaries and exits

Name what the specialist must not answer or do, when to hand off, when to return to Base, and when to offer human help.

How to finish

Say how to communicate success, failure, cancellation, and next steps without making unsupported claims.

Complete example: Appointments Specialist

Role and outcome
Help visitors request, reschedule, or cancel appointments. A successful
conversation gives the visitor an accurate next step and submits an action
only after the required details are complete and confirmed.

What you own
- New appointment requests
- Rescheduling or cancelling an existing appointment
- Questions about availability when the visitor is trying to book

Trusted information
- Search the Knowledge Base for published preparation and cancellation policy.
- Use the appointment lookup tool for an existing booking.
- Never invent availability, prices, deposits, appointment status, or policy.

Conversation steps
1. Identify whether this is new, reschedule, or cancel.
2. Collect only the details required by the relevant tool.
3. Ask one focused question at a time when information is missing.
4. If the visitor corrects a detail, use the corrected value and re-summarize.

Actions and confirmation
- Use the booking request tool only when all required details are present.
- Before any submission, show the exact action and details for confirmation.
- Never say a booking changed until the tool reports success.

Boundaries and exits
- Send invoice, receipt, charge, or deposit disputes to Billing.
- Return general service and website questions to Base Assistant.
- Do not give medical advice or request medical history in chat.
- Offer staff contact when a record cannot be verified.

How to finish
State what was submitted, what still requires staff confirmation, and the
expected next step. If an action fails, say it failed and offer a safe route.

This example names decisions the agent must make but does not duplicate technical parameter schemas already defined on the underlying SmartSite Tool.

Good and weak descriptions

Routing descriptions compared
Weak description	Why it fails	Stronger description
Helps customers with appointments and questions.	“Questions” overlaps almost every other agent and does not distinguish booking intent from general service information.	Handles scheduling, rescheduling, cancelling, and checking an existing appointment. General service and billing questions belong elsewhere.
Customer support specialist.	It names a department, not the visitor situations this role owns.	Handles existing-order status, delivery delays, damaged parcels, and changes requested after purchase. Product recommendations remain with Product Advisor.
Calms users down.	It is vague and can route any mildly negative wording away from the responsible task owner.	Handles clearly agitated or repeatedly frustrated visitors who need acknowledgement, clarification, and a calm human-support path. It does not claim to resolve unverified account or safety issues.
Sales agent for everything we sell.	It is too broad and competes with Base knowledge and post-purchase support.	Helps visitors compare product categories and choose a suitable option before purchase. Existing orders, returns, and account issues are excluded.

Descriptions work best when neighboring specialists use mutually understandable boundaries. Write the full set together, not one agent at a time months apart.

Knowledge Base: enable with purpose

When enabled, the specialist can search the same synchronized website knowledge used by SmartSite. This is valuable for changing facts and published policies. It also means the role may receive retrieved content unrelated to its exact task, so its instructions still need boundaries.

Enable knowledge for a Product Advisor that must compare published specifications, a Billing specialist that explains current deposit policy, or an Appointments specialist that shares preparation instructions. Disable it for a tightly bounded escalation role that should only acknowledge emotion and provide a verified human-support route.

Retrieved content and tool output are treated as untrusted data by the runtime. The agent should use them as evidence, not obey instructions hidden inside them. Admins should still control which pages and files are synchronized, because prompt protections do not turn private documents into appropriate public answers.

Output Style: make several agents feel like one brand

A useful style note is short:

Use plain language and the visitor’s language. Be calm and warm, not overly familiar. Keep replies under four short paragraphs. Use bullets only for options or required details. Do not mention internal agents, routing, tools, or implementation details.

Do not use Output Style to store policies, opening hours, prices, or legal disclaimers that change. Those belong in maintained knowledge or the role’s essential instructions. Do not ask one agent to be “formal and exhaustive” while another is “playful and one sentence” unless that contrast is an intentional user-experience decision.

Temperature and response length are not repair tools

When an agent routes poorly, rewrite Description or handoff conditions. When it takes the wrong action, fix Instructions, Tool usage guidance, parameters, or confirmation. Lowering Temperature may make the behavior more repeatable, but it does not repair an ambiguous scope or missing rule.

Likewise, Max Tokens controls length, not relevance. Use style guidance such as “answer in two short paragraphs, then ask one question” before imposing a hard cap. A cap is useful only after realistic tests prove it does not truncate important content.

The quality review before saving

Distinct

Could this Description be confused with another specialist or Base?

Grounded

Does every changing fact come from knowledge or a lookup, rather than memory?

Bounded

Does the playbook say what the role must not do and when it exits?

Action-safe

Does it collect only required data and avoid claiming success before a tool result?

Human-readable

Could a marketer or client owner maintain these instructions six months from now?

Visitor-facing

Will replies hide internal agent, route, tool, SDK, and workflow terminology?

Flow Checks warns when an agent has no Description or Instructions, uses only a generated activation route, has neither knowledge nor tools, or lacks a policy escape path. Warnings may not block publishing, but they are design feedback worth resolving or consciously documenting.

Screenshot capture pending /images/screenshots/agentic-flows/agents.webp

Add Agent form with identity, scope, and runtime settings

Capture: Open Add Agent for a synthetic Appointments Specialist and populate every field with safe sample content.
Show: Name, Key, Description, Instructions, Model, Temperature, Max Tokens, Knowledge Base, Output Style, and Sort Order
Viewport: Desktop, 1440 × 1000
Annotate: Call out Description as the routing signal and Instructions as the specialist playbook.
Redact: API keys, private URLs, personal data, real visitor messages, and production action details

Next: capability and movement

A specialist with clear instructions can converse, but it should not receive a capability or exit merely because one exists. Continue to tools and handoffs to attach only what the job needs, then use routing policy to decide how readily ownership may change.