Building an Agent

Building an Agent is a five-minute exercise. The goal is to take something you do repeatedly — triaging email, writing a Friday recap, watching a folder for new contracts — and hand it off to a persistent worker that runs on its own.

Two ways to build#

Talk to River AI#

Open SpaceChat and describe the Agent you want. The AI will draft the persona, choose tools, suggest triggers, and create the Agent for you. This is by far the fastest path.

"Build me an Agent that reads my unread emails every morning at 7am, picks out the three most important, and saves a one-page briefing to my Notes."

The AI proposes a complete Agent definition. You review it, tweak the persona or tools if needed, and click Create.

Build it manually in AutomationsApp#

Open Automations → Agents → New Agent. You'll fill in:

• Name — what it is (e.g., "Morning Briefer")
• Description — one line for your future self and teammates
• Persona / system prompt — how it should think and write. Be specific.
• Tools — which tools it's allowed to use. The fewer the better.
• Triggers — when it should run

Save, and the Agent is live. Click Run now to test it before letting it run on its own.

Writing a great persona#

The persona is the most important field. It's the system prompt the Agent uses every time it runs.

Good personas are:

• Specific about role — "You are an inbox triage analyst working for [name]."
• Specific about output — "Always produce a numbered list of at most three items."
• Specific about voice — "Match [name]'s direct, low-fluff style."
• Specific about constraints — "Never auto-send replies. Only draft."

Bad personas are vague: "You help with emails."

A good rule: re-read your persona and check that someone reading it could act exactly the way you want without further instruction. If not, tighten it.

Choosing tools wisely#

Every tool is a capability. Give the Agent only what it needs:

• A Morning Briefer needs read mail, read calendar, write doc.
• An Inbox Triager needs read mail, draft reply, label.
• A Deal Researcher needs read mail, search contacts, web search, write doc.

Adding more tools makes the Agent more capable but also more expensive and more prone to drift. Start narrow; expand only when needed.

Choosing a trigger#

Most Agents end up with one schedule trigger and one or two event triggers. See Triggers.

Testing before going live#

Before you turn on triggers, click Run now to do a dry run with the current state of your Dataspace. Inspect the Job:

• Did it call the right tools?
• Did it produce the output you expected, in the right place?
• Did it write any noise — wrong entities, junk drafts, accidental mutations?

Iterate on the persona and tools until the dry run is consistently good. Then turn on triggers.

Sharing an Agent#

Agents in a team Dataspace are shared by default — anyone can see, run, or edit them. Keep your personal Agents in your personal Dataspace. Move an Agent between Dataspaces with right-click → Move to.

Tips#

• Name Agents like coworkers. "Maya the Inbox Triager" reads better than "agent_inbox_v3."
• Keep one Agent doing one thing. If it's doing three things, make three Agents.
• Add a "draft only, never send" line to the persona of any Agent that can write outbound messages until you trust it.
• Review Job history weekly for the first month. Look for hallucinations or wasted runs.