Building Agents

This guide shows you how to build agents that are useful, easy to trust, and simple to improve. Start with one clear job, test it manually, review the logs and documents, then add automation when the result is reliable.

The Short Version

Build agents in small steps:

  1. Create the smallest agent that proves the idea.
  2. Run it manually from the agent page.
  3. Open the log and check what happened.
  4. Open the documents it created and check the output.
  5. Ask the chat to improve one thing.
  6. Repeat until the agent is dependable.
  7. Only then set a schedule or webhook.

Start With One Job

An agent should have one clear responsibility. It can use many tools and steps, but the outcome should be easy to describe.

Good first agents sound like:

Avoid starting with a large, vague request like "automate support reporting". Turn it into the first visible result you want to review.

Write a Strong First Prompt

Click New Agent and answer "What should this agent do?" with enough detail for a first draft. Mention the source, the output, and any limits.

Use this structure:

Example:

"Use the Intercom connector to find the 20 newest conversations from the last 24 hours. Create a document that lists each conversation, the customer, the topic, and whether it looks urgent. Do not reply to customers or update Intercom yet."

Use the Agent Page

After the first version is created, you land on the agent page. This is where you build and test.

Read the Description First

The left side starts in description view. Treat this as the agent's standard operating procedure. It should explain what the agent does, where it gets data, what it creates, and what it avoids doing.

If the description is unclear, ask the chat:

Check the Code When Needed

Use the code toggle when you want implementation detail. You do not need to read code to use agents, but it can help when you want to verify which connector, database table, or API endpoint is being used.

Good questions are:

Chat on the Right

Use the chat panel to make changes. Ask for one improvement at a time so each change is easy to test.

Good follow-up requests:

Iterate in Small Steps

Small changes make agents easier to debug. After each change, run the agent and review the result before asking for the next change.

For example, build a customer feedback agent like this:

  1. List the 10 newest feedback messages.
  2. Add sentiment for each message.
  3. Group messages by sentiment.
  4. Add themes and examples.
  5. Add a weekly summary chart.
  6. Add a schedule after the document format is right.

This keeps every version understandable. If something breaks, you know which change caused it.

Test Before Automating

Use manual runs until you trust the output.

Run Manually

Click the Run button on the agent page. You will be taken to a live log for that run. Watch the steps, then open any documents the agent created.

Check:

Review the Log

Logs show each run as a timeline. Steps expand to show detail, created documents appear in the timeline, and errors appear in red.

If a run fails, click Fix This from the log. That opens the agent chat with the error so you can ask for a fix in context.

Review the Documents

Documents are the easiest way to judge the agent's work. Open them from the log or from the Documents button on the agent page.

Ask yourself:

Be Careful With Changes to Other Systems

If an agent will update a CRM, send messages, create tickets, change a database, or call any external API that has side effects, test it in review mode first.

Start with:

  1. Create a document showing the exact changes it would make.
  2. Review that document.
  3. Test one real update.
  4. Test a small batch, such as 5 or 10 records.
  5. Run at full scale only after the results are correct.

Useful chat requests:

Add Connectors Explicitly

If the agent needs an external service, set up the connector first and mention it by name in chat.

For example:

Being specific helps the agent use the right credentials and avoid guessing which system you meant.

Use Groups to Stay Organized

Groups keep the sidebar readable as your workspace grows. Think of groups as work areas.

Common group ideas:

You can drag agents into groups, reorder them, collapse groups, and create a new group by dragging an agent to New Group in the sidebar.

Choose a Trigger

Keep new agents on manual runs while you are building. Switch the trigger only when the manual output is reliable.

Runs Manually

Use this while testing, for one-off reports, or for work that needs a person to decide when it should happen.

Runs on a Schedule

Use schedules for recurring work. The trigger menu supports options like every minute, every hour, every day, weekdays, specific weekdays, the first day of the month, and the last day of the month. For schedules with a time, choose the time in the trigger menu.

Good scheduled agents are:

Runs With Webhook

Use webhooks when another system should trigger the agent. After choosing Runs with Webhook, copy the webhook URL from the agent page and use it in the other tool.

Good webhook agents are:

Keep Improving Existing Agents

You do not need to get an agent perfect on the first try. Open the agent page and keep chatting.

Useful maintenance requests:

Use Chat History from the agent menu when you want to return to an earlier conversation. Use New Chat when you want to start a fresh thread for the same agent.

A Practical Checklist

Before you schedule or webhook an agent, confirm: