> For the complete documentation index, see [llms.txt](https://docs.riff.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.riff.ai/get-started/quickstart-agent-v2.md).

# 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:

|               | Question                               | Good fit                                             | Not quite                                             |
| ------------- | -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
| **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.

<div data-with-frame="true"><figure><img src="/files/dtneh8ywdCVxGKBvIxVr" alt=""><figcaption></figcaption></figure></div>

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.

{% hint style="info" %}
You can refine everything as you go. The description is a starting point, not a contract.
{% endhint %}

<div data-with-frame="true"><figure><img src="/files/X3xMDuYbAR8hX7UIRjdJ" alt="" width="563"><figcaption></figcaption></figure></div>

***

## 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.

<div data-with-frame="true"><figure><img src="/files/90pXOHF6eKsGkGqndPjd" alt=""><figcaption></figcaption></figure></div>

***

## 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.

<div data-with-frame="true"><figure><img src="/files/Dm0qhBXyxz787W0p3K67" alt=""><figcaption></figcaption></figure></div>

***

## Step 4 — Explore the tabs

At the top of the agent builder you'll find five tabs.

<div data-with-frame="true"><figure><img src="/files/T7iwbKJfeI9KGzj2PR6Q" alt=""><figcaption></figcaption></figure></div>

**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.

<div data-with-frame="true"><figure><img src="/files/Ft3JIcecfAsZNWeFQ3f0" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/tOe6xOhUOeVxjUbNDYRn" alt="" width="563"><figcaption></figcaption></figure></div>

**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.

<div data-with-frame="true"><figure><img src="/files/VSCRU2xT3c5K9r94uROX" alt="" width="563"><figcaption></figcaption></figure></div>

### 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.

<div data-with-frame="true"><figure><img src="/files/QVDBuKVxcYX0KiQVJmo4" alt="" width="563"><figcaption></figcaption></figure></div>

### 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.

<div data-with-frame="true"><figure><img src="/files/KfWZre3pLYoSkz8Vo7hB" alt="" width="563"><figcaption></figcaption></figure></div>

***

## 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.

{% hint style="info" %}
**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.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.riff.ai/get-started/quickstart-agent-v2.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.