Build your first agent
Before you build — what is an agent?
The simplest way to think about it: a Riff agent is like a new hire.
You define the job. You give the agent a name, describe what triggers it to start, what it should do, and what "done" looks like. Then it runs — handling the routine, escalating the exceptions, and reporting back.
If you can write a handover note for the role, you can build the agent.
What makes a good agent job?
Not every task is a good fit for an agent. Use this quick check before you build:
Judgement
Does someone have to think each time?
"It depends" — each case is a real judgement call
Same input, same output every time — a script does it
Value
Is it worth the time it takes today?
Hours every week, or work that's being skipped
A few minutes a month — not worth a build
Handover
Could a new hire actually do this?
You can write the handover note and name the systems
It's all tribal knowledge — write it down first
Stakes
If it gets one wrong, can you undo it?
Worst case is a draft you discard
High stakes — keep a human approval step for now
If most of those are a green light, you're ready to build.
Agent vs App — a quick distinction
Riff gives you two things to build. Knowing which is which saves you time.
Build an Agent when the job has a clear trigger and a clear "done" state, runs repeatedly, and humans only need to review exceptions — not every step.
Build an App when humans drive the flow, the output is a screen someone opens, or AI is a feature inside a larger workflow rather than the whole job.
Many projects combine both — an agent does the routine work, an app surfaces the output for your team to review.
Configuring your agent
An agent in Riff is configured through four things: instructions (what it does and how it behaves), tools (how it takes action in external systems), skills (step-by-step processes it follows), and knowledge (background context it can look up). You build all of these through a conversation with the Riff agent — no forms to fill in, no configuration files.
Here's how to get started.
Step 1 — Click New Agent
From your workspace home, click New Agent in the side navigation. You'll see a panel asking you to describe your agent.
Don't worry about getting this perfect — it's just a starting point. Describe the job you want the agent to do in plain English, the same way you'd explain it to a new hire.
You can refine everything as you go. The description is a starting point, not a contract.
Step 2 — Start chatting with your agent
Once you've named and described your agent, you'll be dropped straight into a chat with it. This is where building happens — through conversation.
The agent will ask you a series of questions to understand the job: what triggers it, what systems it touches, what a good outcome looks like, and when it should escalate to a human.
Answer as naturally as you'd explain the role to someone new. The agent uses your answers to write its own instructions, and to figure out what tools, skills, and knowledge it needs.
Step 3 — Understand Build vs Live
In the left sidebar you'll see a Build / Live toggle. This is one of the most important things to understand as you work.
Build Your development environment. Use this to shape the agent — test how it responds, add tools and skills, adjust its instructions. Think of it as working behind the scenes before the agent goes on shift. Changes you make here don't affect anything your team is relying on.
Live The deployed version of your agent — the one doing real work. Switch to Live to test how the agent behaves once it's been deployed, before you point live work at it.
Step 4 — Explore the tabs
At the top of the agent builder you'll find five tabs.
Chat Your main building surface. Have a conversation with the agent to configure it, test it, and iterate. This tab stays active in the background even when you're looking at other tabs — so a running response won't be interrupted.
Profile The full description of your agent: its purpose, its instructions, and all the tools, skills, and knowledge it has. This is a great anchor point for understanding what your agent can and can't do. Anything shown here can be adjusted by going back to the Chat tab and telling the agent what you want to change.
Pipeline Where you can see the tasks your agent is working on. (More coming soon.)
Triggers How your agent gets started — on a schedule, by email, or by an incoming event. (More coming soon.)
Activity A log of every run: what the agent did, which tools it called, and how long each step took.
Three concepts to know
As you build, you'll hear three terms often. Here's what they mean:
Tools
The hands of your agent. Tools connect it to external systems — your ERP, a Slack channel, an email inbox, a database. If your agent needs to do something in the world (read data, send a message, update a record), it needs a tool for that.
Skills
Step-by-step procedural guidance. If your agent needs to follow a specific process — a particular way of checking invoices, a house style for writing emails, a decision tree for approvals — write it as a skill. Think of it as the training manual for this one job.
Knowledge
Background context your agent can search when it needs it. Product catalogues, supplier lists, policy documents, glossaries — anything too large or too fluid to put directly in the agent's instructions. The agent looks it up when it's relevant, rather than holding it all in memory.
You're ready to build
That's the shape of a Riff agent: a job description, a set of tools to act on the world, skills to follow the right process, and knowledge to draw on when it needs context.
The agent you just configured isn't finished — it's a starting point. The best agents are built iteratively: start with a narrow job, get it working, then expand. Talk to your agent in the Build environment, watch how it reasons, and adjust. The Profile tab is always there to show you exactly what it knows and how it's been instructed to behave.
When you're happy with how it performs in Build, switch to Live and run it for real.
A note for beta testers: We're actively developing Riff based on your feedback. If something doesn't work the way you'd expect, or a concept isn't clear, we want to know. Reach out directly — your input shapes what we build next.
Last updated
Was this helpful?