Forge Best Practices

Practical guidance for getting reliable results from Forge: how to prepare, how to word requests, what to check before you approve a plan, and how to test, debug and move to production. It is written for implementation teams, solution consultants, support engineers and admins who build AI Colleagues.

The examples on this page come from real Forge conversations that completed first time: the plan was approved, every step finished, and nothing was retried.

Forge in 60 seconds

Forge is the conversational builder and investigator inside AI Colleagues Studio: describe the outcome, approve its plan, and it builds, debugs or migrates for you. It acts as you, only on the bot you are in, and every change needs your approval.

Job	What Forge does	Use Forge when…	Do it manually when…
Build	AI Colleagues, AOPs, Code tools (Forge-only), MCP tools	Starting from a process description or SOP; multi-artifact builds ("build the AOP and any tools it needs")	Tiny edits to one field you can see on screen
Workbench	Create, edit, pause schedules and external triggers	Setting cadence in plain language	Bulk changes across many triggers
Debug	Read-only root cause, run search, analytics, tool-selection and KB traces	Any "why did this fail / not pick X?" question	Start here, then confirm in Run Execution Details if needed
Move to prod	Readiness checks, mappings, migration	Moving an AOP or a single tool from UAT/Staging to Prod	–
KM	Find connectors, run and schedule syncs, copy UAT to Prod	Connector operations	Editing articles or FAQs (not supported)
Settings & access	Reads settings, opens the right page; invites dashboard users (System Admin)	Checking a guardrail or flag	Changing a setting (you always make the change on the page)
How-to	Answers from product docs	Product questions in context	–

For a larger request, Forge makes a plan and then builds each item (AI Colleague, AOP, Code tool, MCP tool) as a separate step. Each step works from what your request says about that item, so the clearer your request, the better every step turns out.

Before you open Forge

Most poor builds trace back to missing inputs. Spend 15 minutes on scoping before the first prompt.

Gather these first

The process in writing: an SOP, runbook or a numbered list of steps. Attach it rather than retyping.
Trigger: chat by an employee, a schedule, or an external event (webhook).
Who it is for (audience) and who approves what (roles, not names, where possible).
Systems touched and the action in each (e.g. "ServiceNow: create incident", "Workday: read leave balance").
Connections and credentials already set up on this bot, or who will set them up.
Business rules and edge cases: thresholds, exceptions, what to do when a lookup fails.
Org-level codes and IDs the build needs (e.g. purchasing org, document type, company code).
Expected output: what the user sees, what gets written, who is notified.
3–5 realistic test inputs, including one failure case.

Set up your session

Work in Staging or UAT, then move to Prod with Forge. Forge only acts on the bot you are in.
Open the right page first (the AI Colleague, AOP or run). Forge reads page context, so "this AOP" just works.
Check your role: Forge can only do what your dashboard role allows.
Check what already exists: ask "What tools and AOPs does this bot already have for onboarding?" Reusing is faster than rebuilding.

👍
Real example: a build that needed no rework
A consultant scoped a SAP finance build before opening Forge, then sent one message with two attachments: a PO details document and a sample supplier invoice to use as a template.
"This is an AOP to create test Purchase Orders. Each run should create 2 POs … Each PO totals 17,000.00 EUR net (16,100.00 materials + 500.00 freight + 400.00 insurance); with tax code V1 at 19 % … the gross value is 20,230.00 EUR. Freight and insurance are header-level amounts … but the API accepts pricing elements only at item level, so the script splits each amount across the four items pro rata … Each run … should also provide a comparable invoice in the downloadable format, use the attached template."
Forge planned 2 Code tools and 1 AOP. Its only follow-up question was for three master-data values (purchasing org, purchasing group, document type).
Lesson: list org-level codes and IDs up front and the build needs no clarifying questions.

Prompting Forge well

Tell Forge what must happen and the business rules. Let it decide how (endpoints, code, field names) unless you know the real system's details. Anything you write becomes a requirement, so a guessed endpoint or field name gets built as if it were correct.

Anatomy of a good build request

Outcome: one sentence on what the AI Colleague should achieve.
Trigger and audience: who starts it and how (chat, schedule, webhook).
Steps: the business steps in order, in your own words or as an attached SOP.
Systems and actions: which system, which action; name existing tools if you know them.
Rules, approvals and edge cases: thresholds, approvers, what to do on failure.
Output: what the user sees, what gets updated, who is notified.
Scope of the build: "use existing tools only" or "create any tools it needs".

Good vs poor

Poor	Better	Why
"Make an onboarding AOP"	"Create an onboarding AOP for the HR colleague. Triggered by a webhook from Workday when a hire is confirmed. Create the laptop request in ServiceNow, add the user to Slack, email the manager a summary. If ServiceNow fails, escalate to IT Admin. Create any tools it needs."	Trigger, systems, failure path and build scope are explicit
"Fix this tool"	"On this tool, the ticket number in the output is empty when priority is P1. Here is run ID_015028. Find the cause and propose a fix."	Symptom, condition and evidence; diagnose first, then change
"Use POST /api/now/table/incident with header X and return {ok:false}"	"Build a tool that creates a ServiceNow incident from a description and urgency, and returns the incident number."	Lets Forge choose and test the implementation
"How many runs failed?"	"How many runs of the Payroll AOP failed in the last 7 days, grouped by failure reason?"	A narrow question avoids trimmed results

Chat hygiene

One problem per chat. Use New chat for each build or investigation; context does not carry between chats.
Diagnose, then change. Ask "why" first, confirm the cause, then ask for the fix.
Attach, don't paste. SOPs, sample payloads and test files (up to 10 files, 25 MB each). Messages are limited to 5,000 characters.
One turn at a time. Stop the current turn before changing direction.
Reference real IDs (run IDs, AOP names) when you are not on that page.

Real prompts that worked first time

Prompt (as sent)	What Forge built	Why it worked
"I want to make changes to the AOP Manage My Emergency Contacts: When a user deletes their preferred contact, or changes an existing contact so it's no longer preferred, prompt them to pick one of their remaining contacts as the new preferred contact. They can't skip this step or choose none, because at least one contact must always be marked as preferred."	AOP edit, published	Names the AOP, the trigger condition, the required behaviour and the rule behind it
"I want to make changes to the AOP Workday Goals Management. When sending the results back to Workday it is referencing '…set the goal year to 2026'. The issue is that the field is called Status and not year. I think this is why it's not processing correctly."	Field-reference fix, published	Quotes the exact wrong text and says what it should be
"While presenting the job search results to the user, please also share the Job Requisition Number … Same … at the end when the application is submitted … show the Job Requisition the user has applied for."	Output change in two places, published	Says exactly where in the flow the new field must appear
"Set up the prebuilt catalog template servicenow.approvals … Lets an employee see the ServiceNow approvals waiting for them and approve or reject one, with a comment (a reason is required to reject), after they confirm. … Walk me through connecting the apps, confirming the process, and creating the AOPs, then run a test."	AI Colleague, 2 Code tools and an AOP	Starts from a template, states the rule and asks for a test run
"can you create an AOP for me based on attached" plus a build spec (.docx)	5 Code tools and an AOP, published	The attached spec already held the steps, tools and rules
"I want to know why 'What's the leave of absence policy?' question was not routed through the Leave of absence AOP", then "so I want to improve the AOP so it picks the AOP for these kind of questions"	Diagnosis, then a description fix	Diagnoses first with a request ID, then asks for the change

Reviewing the plan and answering questions

The plan card is the cheapest point to catch a wrong build. A minute here saves rebuilding an AOP later.

When Forge asks clarifying questions (up to five, with tappable options)

Answer all of them; if you skip one, Forge has to guess.
Use Something else for detail the options miss, rather than picking the closest wrong option.

Before you approve a plan, check:

Order: tools and connections come before the AOP that uses them; the AI Colleague exists before its AOPs.
Reuse: it reuses existing tools and AOPs instead of creating near-duplicates.
Names: tool and AOP names follow the naming rules below (action verb + object).
Scope: nothing extra you didn't ask for, and nothing missing (approvals, notifications, failure path).
Target: right AI Colleague, right bot and environment.

During and after the build

Watch the status bar above the composer: in progress, needs your input, or a step failed.
If a step fails, say how to continue ("retry", "skip and continue", or what to change) instead of starting over.
To change the plan, reply with the change. Say "start over" only when you want a fresh plan.
Use View full plan to open everything Forge created, then review each item on its own screen.

Building AOPs with Forge

Ask for AOPs that follow the AOP format principles, and check Forge's output against them before you publish.

Principle	What to ask for / check
Clear sequential steps	Numbered, named steps (`Step "Fetch Data": …`), one action each, in logical order
Explicit tool references	Every system action uses an `@Tool` mention; no "configure access somehow"
Data flow	Each step says what it passes on (e.g. "list of employees missing access")
Loops	What to loop over, the action per item, the tool, and what happens on a per-item error
Approvals	Approver role, what is shown (e.g. a table with named columns), and what happens on reject or no response
Error handling	For each tool step: what can fail, retry / skip / escalate / halt, who is notified
Branching	Simple if/else rules written as bullets in the step
Helper AOPs	Reusable or complex blocks extracted with defined inputs and outputs
Attachments	The file's structure, which step uses it, and the fallback when a case is missing

Working practices

Tools before the AOP. If a tool the AOP needs doesn't exist, Forge stops and tells you. Say "create any tools it needs" up front so the plan includes them.
Save as draft before Improve. Improve AOP runs through Forge and needs a saved draft.
Validate before you publish. Ask Forge to validate the draft and fix any warnings first.
Keep AOPs focused. One business process per AOP; move shared logic into helper AOPs.
Re-read the final instructions. Forge writes them; you own them. Check that every rule from your SOP made it in.

👍
Real example: spec in, AOP out
A consultant attached a written build spec for "Update Bank Account (SuccessFactors)" and typed one line: "can you create an AOP for me based on attached". Forge proposed a 6-step plan (5 Code tools, then the AOP under the SAP SuccessFactors colleague), asked only for the test tenant and a test user, saved the AOP as a draft, and published it on a second request.
Lesson: when the spec is complete, the prompt can be one line, and Forge orders the tools before the AOP without being asked.

Building tools

The AI Colleague chooses tools by their name and description, so these matter as much as the code.

Code tools (can only be created through Forge)

Describe the inputs, the action and the output; Forge writes the code, tests it in a sandbox and publishes it.
Attach a sample input or response as a test file so tests use realistic data.
One tool, one action. "Fetch incident" and "Update incident" are two tools.
Make sure the connection exists, or let Forge open the connection form beside the chat.
Editing an existing Code tool through Forge is coming soon.

MCP tools

Start from an existing MCP connection and name the specific actions to expose, not the whole server.

Naming and descriptions (check what Forge proposes; see Writing Effective Tool Names & Descriptions)

Rule	Good	Poor
Name = action verb + object (+ system)	Fetch Employee Leave Balance	Workday Integration
Description says what, when and required inputs	"Retrieves remaining leave from Workday. Use for PTO, vacation, sick leave. Requires employee ID."	"Handles leave requests"
Distinct from neighbouring tools	Fetch Leave Balance vs Submit Leave Request	Leave Tool 1 / Leave Tool 2
Include user synonyms, under 50 words	"PTO, vacation, time-off"	Internal jargon

👍
Real example: a Code tool and AOP in one plan
On a ServiceNow colleague, a consultant asked for one read-only Code tool ("Fetch My Assets ServiceNow") and one draft AOP ("View My Equipment (ServiceNow)"). The request included:

The tool description in the routing format: system, read-only, what it returns, when to use it.

Config values to look up rather than hard-code (the "In use" status value).

Named error cases returned as data (for example CALLER_NOT_FOUND, NO_ACCESS), never raw exception text.

A test list: one asset, none, 60 assets, filter hit and miss, 401, 500, HTML response, missing config.

"Don't change existing tools or AOPs" and "leave the AOP as an unpublished draft".

What to report back: anything that couldn't be built as specified, and the test results.

Forge asked one safety question before running tests against the connected ServiceNow instance (allow it only if it is a test system), then completed both steps. Both were published on a follow-up request.
Lesson: detailed specs work well when they come from you and match the real system. Always include the test cases and the "don't touch" boundaries.

AI Colleagues and Workbench triggers

AI Colleagues

Give a job title and a job description that state the department and scope ("Handles IT access and hardware requests for employees in India"). It frames how the colleague behaves.
Name owners and an escalation contact explicitly; otherwise you are the default owner.

Workbench (schedules and external triggers)

State the cadence with a time zone: "every Monday at 9am IST", not "weekly".
Include the start time and the end condition (an end date or number of runs) in the same message.
Make sure the AOP's execution permissions allow Workbench runs before you schedule it.
For external triggers, Forge opens a pre-filled form; review the payload mapping before saving.
Use Forge to audit: "Which workbenches run this week?", "Pause the payroll workbench".

👍
Real example: a Workbench end to end
One chat created, monitored and switched off a schedule:

"create a workbench with AOP → employee hiring process sync", then "activate it first" (the AOP was inactive).

Forge asked for the details over five turns: every 15 minutes, UTC, 9:00 am start, end after 4 runs, confirm.

"Show upcoming runs for this workbench", then "does this schedule have any cancelled run?", then "Explain run Occurrence #3".

"deactivate this workbench now", then an approved plan.

Lesson: put everything in the first message, for example "Activate the employee hiring process sync AOP and schedule it every 15 minutes from 9:00 UTC, ending after 4 runs", and you skip five clarifying turns.

Testing and debugging with Forge

Debugging in Forge is read-only, so it is always safe to ask. Start every failure investigation here.

Test before you roll out widely

Run each test input from your scoping list through the Virtual Assistant, including the failure case.
Set up Evals for AOPs that will run at volume, and rerun them after every Forge edit.

Debug loop

Open the failed run and ask "Why did this run fail?"
Ask for the evidence: "Show the timeline" or "Why wasn't the leave-balance tool picked?"
Confirm the cause in Run Execution Details if it is not obvious.
In the same chat, ask for the fix, review the plan and approve.
Retest with the same input.

Getting complete answers

Add filters: AOP, AI Colleague, status, channel, date range. Large results are trimmed (tables show up to 25 rows).
Forge reports only what the data contains. If it can't find something, widen the time window rather than rephrasing.

Moving to production

Build in Staging or UAT, then let Forge move it. Ask "Is <AOP> ready to move to prod?" before "Migrate <AOP> to prod".

Readiness first. Fix every blocker the readiness check reports before migrating.
Map connections and environment variables carefully. Prod should point at prod systems and credentials, never UAT ones.
One AOP at a time. Forge migrates several AOPs in sequence and saves progress; review each mapping.
Build where you are. Forge only builds on the bot you are in. Build there, then migrate.
KM too. Copy KM connectors or KM settings from UAT to prod through Forge, after you approve.
After migration, run one smoke test in prod and check the run in Forge.

Safeguards and limits

Forge acts as you, on one bot, with your approval, and every change is recorded in Audit Logs as Initiated Via: Studio Assist.

Limit	Workaround
One bot per chat; no cross-bot reads or builds	Build on this bot, then move with migration
One turn at a time	Stop the current turn before redirecting
One build request per chat works best	Start a new chat for each AOP
No deletion of AOPs, AI Colleagues or tools through chat	Disable a tool through Forge; delete AOPs from the dashboard if permitted
Forge doesn't change settings	Forge opens the page; you make the change
KM articles, FAQs, business reports and eval suites can't be edited here	Use the Knowledge Management, Performance insights and Evals screens
5,000 characters per message; 10 files of up to 25 MB	Attach the SOP instead of pasting it
Large results are trimmed	Add filters and date ranges
Editing existing Code tools through Forge is coming soon	Rebuild through Forge or edit manually

Governance tips

Agree who in your team may approve Forge plans in environments close to production.
Review Audit Logs for Forge changes during UAT sign-off.

Templates and checklist

Build template (copy, fill in, attach the SOP)

Create an AOP called <name> for the <AI Colleague> colleague.
Goal: <one sentence>.
Triggered by: <chat from employees | schedule | webhook from system>.
Steps (see attached SOP):
1. <step>
2. <step>
Systems: <system: action>, <system: action>.
Approvals: <role> approves when <condition>; on reject <what happens>.
If something fails: <retry | skip | escalate to role>.
Output: <what the user sees, who is notified>.
Tools: <use existing tools only | create any tools it needs>.

Debug template

Run <ID> for <AOP> <failed | answered wrongly | escalated>.
Expected: <behaviour>. Actual: <behaviour>.
Find the root cause and show the evidence. Don't change anything yet.

Pre-publish checklist

Plan reviewed: order, reuse, scope, target bot
Every system action uses an @tool; no vague steps
Approvals and failure paths defined
Tool names and descriptions follow the naming rules
Draft validated with no open warnings
All test inputs pass, including the failure case
Execution permissions and audience set
Readiness check passed before moving to prod

Updated about 13 hours ago

Did this page help you?