Quickstart - build your first agent

The fastest path from a fresh bot to a real agent you can talk to - about 15 minutes. You'll build one slice of a larger assistant for Yellow Bikes (a sample e-bike brand): a Bike Finder agent that recommends the right bike from your catalogue - and you'll test it in the Playground.

Build the smallest end-to-end version first - one agent, one tool, one test - then expand. Once Bike Finder works, the same moves grow into a full multi-agent assistant that also books test rides and tracks orders (see Where to go next).

Prerequisites. You're on nexus.yellow.ai. You also need a bot to build in: if you don't have one yet, create it in Create your AI agent. For Step 4 you'll seed a small bikes database with dummy data we provide - nothing to prepare. (Prefer your own catalogue API, database, or documents? Have those handy instead.)

Nexus Tip

In a hurry? The Nexus AI Layer can scaffold this conversational agent - its trigger, instructions, and a starter tool - from a one-line description, so you start from something working. This quickstart walks the manual path so you understand each piece.

Ask the AI layerCreate a conversational agent called Bike Finder for Yellow Bikes that recommends an e-bike by commute distance, terrain, budget, height, and experience, grounded in our bike catalogue

What you'll build

A single conversational agent - Bike Finder - that asks a shopper about their needs (commute distance, terrain, budget, rider height, experience) and recommends the best-fit e-bike, grounding every claim in your bike data and never inventing specs. You'll set your bot's tone and welcome, create the agent, give it knowledge, test it, and lock the behaviour in as a test case.

That's the smallest end-to-end slice of the full Yellow Bikes assistant. No extra agents, no routing rules yet - those come later, and only when you have a real reason (start small).

Configuration vs agents. Bot-wide behaviour - tone, identity, conversation rules, welcome, fallback - lives in Configuration and applies to every agent. You'll set the two that shape first impressions - tone and welcome - in Step 1; the rest can wait. The remaining steps focus on building one agent: its Trigger (when it runs) and Instructions (what it does).

Step 1: Set up your profile

Before you build an agent, give your bot a voice. Profile settings is bot-wide - it applies to every agent - so setting it once shapes how Yellow Bikes greets and talks to everyone. For the quickstart we'll set just the two things a shopper notices first; the rest can wait.

Go to AI Agent → Configuration → Profile settings.

1. Set the tone. Under Identity & tone, pick a preset - Helpful (warm & clear) or Professional (formal & precise) - or choose Write your own to describe the voice in your own words. This sets how the bot speaks without writing a full prompt.
2. Set the welcome message. Scroll to Choose how to welcome and keep Instruct AI agent (the default - the AI writes the greeting from a short instruction you give it), or switch to Send message for a fixed greeting. Turn on Conversation starters to show quick-reply buttons - e.g. "Find a bike", "Compare models" - that nudge the common journeys.

1/2Under Identity & tone, pick a tone - Helpful or Professional

That's enough to feel branded. The bot's Name, Company, a one-line Identity, plus conversation rules, fallback, and AI safety also live in Configuration - set them whenever you like. Full page: Profile.

Step 2: Create the agent

1. In your bot, go to AI Agent → Agents. The page has two tabs - Conversational and Guided.
2. Click Create and choose Conversational agent. Conversational agents are open-ended and LLM-driven - the right fit for recommendation and Q&A. (Reach for a Guided agent when the steps must run the same way every time, like a booking flow - that's the test-ride agent you'll add later.)
3. Name it Bike Finder and create it - you land on the agent's profile.

1/3On the Agents page, click Create

Full walkthrough: Create an agent and Conversational agents.

Step 3: Write its Trigger and Instructions

The agent's profile has a Trigger at the top and Agent instructions below.

• Trigger - when Nexus should hand a conversation to this agent. Be concrete about what it covers and what it doesn't:

  "When the shopper wants help choosing or comparing an e-bike - recommendations by commute distance, terrain, budget, rider height, or experience. Not for test-ride booking or order tracking."

• Instructions - the agent's job, in plain language:

  You are the Bike Finder agent for Yellow Bikes. You help shoppers
  choose the right e-bike.
  
  - Ask what they need the bike for: commute distance, terrain, budget,
    rider height, and experience.
  - Recommend the single best-fit model and explain why it matches their
    answers.
  - If two models are close, compare them and name the trade-off plainly
    ("X has more range but is heavier").
  - Ground every spec in your bike data - never invent range, price,
    or weight.
  - If you don't have the data, say so instead of guessing.

Click Save.

Writing good instructions - the habits that matter most. The model follows clear and plain far more reliably than emphatic:

• One instruction per line. Chaining actions with "and" / "then" makes the model do the first and drop the second.
• Say what not to do, concretely. "Never invent range, price, or weight" is testable; "be accurate" isn't.
• Keep when separate from how. When the agent runs is the Trigger; how it behaves is the Instructions - Nexus owns routing, so don't restate it inside the prompt.
• Skip the SHOUTING. ALL-CAPS "MANDATORY" lines bury the real instruction instead of enforcing it.

Go deeper: Writing agent instructions · Writing prompts.

Step 4: Give it real bike data - create a tool

Right now Bike Finder can talk but knows nothing about your bikes. Tools let an agent act - an agent automatically picks up every tool in the bot and chooses one by its name and description.

For this tutorial we'll back Bike Finder with a small database of bikes: seed a table with the dummy data below, build a workflow that looks a model up in it, and attach that workflow to the agent as a tool.

Following along vs. using your own data. The steps below seed a ready-made bikes table so you have something real to fetch. Already have a catalogue API, database, or another source? Skip the seeding and point the workflow (4b) at it instead. Prefer documents (spec sheets, FAQs)? Use a Knowledge Base tool and skip to Step 5. The tool wiring (4c) is the same either way.

4a - Seed a bikes table

In your bot's Database, create a table called bikes and add these rows (paste them in as-is for the tutorial, or upload as a CSV):

model	range_km	price	weight_kg	terrain
City Lite	45	49999	18	flat city
Commuter Pro	80	74999	22	city, light hills
Trail X	60	99999	27	off-road, steep hills
Cargo One	70	119999	34	city, heavy loads
Folder Mini	40	54999	16	flat city, transit

Those five columns are everything Bike Finder needs to recommend a model and weigh trade-offs.

4b - Build a workflow that reads the table

In Studio → Build → Flows, create a small workflow the agent can call:

1. Start it with a model input variable (what to look up).
2. Add a Database node, set its action to Search, choose the bikes table, and filter where model matches the input. Save the matching row to a variable.
3. End with an Output node that returns that row's fields - range_km, price, weight_kg, terrain.
4. Name the workflow (getBikeDetails) and fill in "When should the AI use this workflow?" - the field the agent reads to decide when to call it.

"When should the AI use this workflow?" is the field that matters most. The agent decides which workflow to run by reading this text - not the name, not the steps inside. Say what it returns and when to call it (and when not):

• ✅ "Returns a Yellow Bikes model's specs - range, price, weight, and recommended terrain. Use it for any spec, price, or comparison question; not for booking or order status."
• ❌ "Call this when bikes data is required." / "Bike workflow."

Vague text gets the workflow skipped or run at the wrong time. More: why the description is the most important field.

Keep it small - one input, one output. (Using your own API or database instead? Swap the Database node for an API node or your DB's connector - the rest is identical.) Details: Workflow tool → Build the workflow.

4c - Attach the workflow as a tool

A workflow attaches directly as a tool - there's nothing to "expose" or wrap, and no schema to re-declare. The workflow's input variable (model) is the tool's input, and its Output node is what the agent reads back.

1. Open the Bike Finder agent. Under Reasoning & Actions → Tools, click + Add tool.
2. Pick the getBikeDetails workflow you built in 4b - it's now a tool the agent can call. The agent decides when to call it from the "When should the AI use this workflow?" text you wrote in 4b, so there's nothing more to configure here.

Wire it into the prompt by name. Back in Bike Finder's Instructions, reference the tool so the model actually calls it: "Call @getBikeDetails for every spec, price, or comparison - never state a number it didn't return." See Referencing tools in prompts.

Deep dives: Workflow tool · Tools overview.

Step 5: Talk to your agent in the Playground

1. On the Bike Finder profile, click the play (▶) icon in the title bar - the Playground opens on the left.
2. Send a recommendation question: "I commute 12 km on hilly roads, my budget is mid-range, I'm 5'6" and a beginner - which bike?"
3. Watch it ask follow-ups, then recommend a model grounded in your bike data. Tap View trace under a reply to see the tool fire (e.g. getBikeDetails) and what it returned. Use 👍 / 👎 to flag anything to fix later.

Playground ≠ Copilot. The left panel is the Playground, where you act as the end-user. The right-hand "How can I help you today?" panel is Copilot - the Nexus AI Layer assistant for you, the builder. More in Testing → Playground.

That's a working agent. 🎉

Step 6 (optional): lock the behaviour in as a test case

When a recommendation looks right, capture it so it can't silently regress: open the AI Trust Centre → Testing Lab, create a New test case with the Trial run flow, drive the same conversation, and approve it as a saved case. Add an assertion such as "recommends the commuter model and cites its range from getBikeDetails." Build up 10-30 cases over time and run them before each release. See Testing → AI Trust Centre and the Testing Lab guide.

Step 7: Publish

A conversational agent carries a Live / Draft status. While you build, it stays Draft. When Bike Finder behaves the way you want, set it Live so it reaches customers on your channels.

Where to go next - grow into the full assistant

You've built one agent end to end. The full Yellow Bikes assistant adds two more agents and some shared setup - add each only when you need it:

• Book test rides - as a guided agent. Booking must collect name, phone, city/showroom, model, and date/time, validate them, confirm, and never double-book - steps that should run the same way every time. Build it as a guided agent (a deterministic flow) with a Workflow tool that writes the booking and returns an ID.
• Track orders - another conversational agent. Authenticate via order ID + phone, then return the current stage and ETA via a Workflow / API tool.
• Route across the three agents. Nexus routes automatically on each agent's Trigger - keep them distinct. Add Routing Logic only when you want a deterministic override.
• Shared identity, rules & memory. Persona, welcome, fallback, safety, and shared memory for all agents live in Configuration.
• Interactive widgets. Quick replies, an order-status card, pickers - design them in the Widget Builder and drop them into a conversation.
• Voice. Test the same agents in voice, not just chat.
• Best practices & what's new. Best practices · What's new.