> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Create an AI agent that owns a job end to end: give it instructions, tools and triggers, let it run on its own, and approve what it does.

An **Agent** is a named AI worker that owns one job, such as "triage inbound support email and escalate anything about billing". You give it **Instructions**, the **Tools** it may use, **Rules** for when to stop and when to ask you, and **Triggers** that wake it up. It keeps its own run **History**, a **Memory** of what it has learned, and a list of things waiting for you under **Action required**.

Use an Agent when the work needs judgement and the steps change from case to case. If you can draw the steps as a fixed sequence, a [workflow](/automations/workflows/build) is usually cheaper and more predictable.

**Where:** there is no Agents item in the left sidebar. Open `https://connie.ai/<workspace-id>/agents` (see [Navigating Connie](/navigating-connie) for your workspace ID).

## How to find your Agents

Agents don't have a sidebar entry and aren't listed on the **Automations** page. Use any of these:

* **Type the address.** Go to `https://connie.ai/<workspace-id>/agents`. Bookmark it.
* **Search.** Click **Search anything** at the top of the sidebar (or press ⌘K / Ctrl+K) and type the agent's name.
* **Notifications.** Approval notifications such as "\[agent name] needs approval" open the agent.
* **Chat.** Ask Connie about the agent (for example "send my Support triage agent this email"). The result card links to the agent's run.

<Note>
  While you're on an Agent page, the sidebar highlights **Automations** and the breadcrumb reads **Automations › \[agent name]**. Clicking **Automations** in the breadcrumb takes you to the Automations page, which doesn't list Agents. To get back to the list of Agents, go to `https://connie.ai/<workspace-id>/agents` again.
</Note>

## Agent, 'Run AI agent' step, or scheduled task?

Three different things in Connie involve AI working on its own. They are not interchangeable.

| | **Agent** (this page) | **Run AI agent** step in a workflow | **Scheduled task** |
| - | - | - | - |
| What it is | A standalone AI worker with its own instructions, tools, rules, memory and history | One step on a workflow canvas that does an AI task and passes its answer to the next steps | A saved instruction that Connie re-runs inside one chat on a timetable |
| Where it lives | `https://connie.ai/<workspace-id>/agents` | Inside a workflow, under **Automations** | In a chat, and on **Automations → Scheduled tasks** |
| How it starts | Its triggers (event, schedule, manual), or when you chat with it | When the workflow runs (once per run, or once per row) | On its schedule, or **Run now** |
| Where results go | The agent's **History** and **Artifacts** | Into variables and columns for later workflow steps | A new message in that chat |
| Choose the AI model | No, Connie picks it | Yes, the **Model** field | No |
| Learn more | This page | [The Run AI agent step](#the-run-ai-agent-workflow-step) below | [Scheduled tasks](/automations/scheduled-tasks) |

<Warning>
  On the Automations page, **New → New workflow → AI Agent** (and **Templates → Blank project → AI Agent**) does **not** create an Agent. It creates a workflow with a **Schedule** trigger and a **Run AI agent** step. To create a standalone Agent, go to the Agents page and click **New agent**.
</Warning>

## The Agents page

The page header reads **Agents** with a count, and has a **New agent** button. Three tabs sit underneath:

* **Your agents**: your agents and folders. Columns: **Agent**, **Actions** (actions the agent has completed), **To review** (approvals and questions waiting for someone), and **Status**.
* **Templates**: ready-made agents you can start from, such as **AI Appointment Setter**, **Support triage agent**, **Customer onboarding manager**, **Recruiting sourcer**, **Content repurposing agent** and **Invoice processing agent**. Templates people in your workspace shared with **Share as template** can also appear here.
* **Archived**: agents you deleted or archived. Click **Restore** to bring one back.

Use **Search agent...** to find an agent or folder by name, and **Filters** to filter by status, tools, triggers, approval owner, creator, dates and more. Starred agents and folders are listed first.

**Status** tells you whether the agent wakes up on its own:

| Status | Meaning |
| - | - |
| **Live** | Its triggers are on. It runs by itself when a trigger fires. |
| **Draft** | Its triggers are off. It runs only when someone chats with it or clicks **Run now**. |
| **Error** | Something is wrong with the agent. Open it and check its triggers and tools. |
| **Archived** | Deleted. Triggers are off. It can be restored. |

## Create an agent

<Steps>
  <Step title="Open the create dialog">
    On the Agents page, click **New agent**. (In an empty workspace, click **Add agent**, or type what you need in **What do you want to build?** on the **Templates** tab and click **Create agent**.)
  </Step>

  <Step title="Describe the job, or set it up by hand">
    The dialog **What job should this agent own?** asks for one sentence, for example "Triage inbound support email, draft a reply, and escalate anything about billing." Click **Continue** and Connie drafts a name, instructions, rules, and suggested triggers and tools for you. Click **Configure manually** to skip the draft and start from a blank form.
  </Step>

  <Step title="Review the form">
    The **Create new agent** form opens. Check every section (they're explained below): **Name**, **Instructions**, **Triggers**, **Tools**, **Rules**, **Who answers this agent's requests**, and **Advanced settings**. Nothing is created until you click **Create agent**.
  </Step>

  <Step title="Click Create agent">
    If every trigger is fully set up, the agent is created and set **Live** straight away, and you see "\[agent name] is ready". If a trigger still needs an account or a field, the agent is saved as a **Draft** and opens on its configuration so you can finish it. An agent with no triggers stays a **Draft**: it only runs when you chat with it.
  </Step>
</Steps>

<Tip>
  To start from a template, open the **Templates** tab and click a template card. The form opens already filled in. Review the instructions, connect the accounts its tools need, and add triggers before you click **Create agent**. Many templates don't preselect triggers.
</Tip>

### Name and Instructions

* **Name**: up to 160 characters, and unique in the workspace. You can rename the agent later from its menu.
* **Instructions**: the agent's mission, in plain language. Describe the goal, who or what it works on, how to judge a good result, and what it must avoid. Up to 50,000 characters.
* **Improve with AI** rewrites your instructions as a suggestion. Click **Accept** to use it, **Discard** to ignore it, or **Undo** after accepting. It works on instructions between 3 and 2,000 characters.

### Rules and approval owners

Every agent has two fixed rules you fill in:

* **When should the agent stop?** For example, "Stop once the reply is drafted and the ticket is tagged."
* **When should the agent ask for approval?** For example, "Ask before sending any email to a customer."

Click **Add rule** to add your own rule with a **Title** and **Description**. In rules you can type **@** to mention records, lists, workflows and other workspace content.

**Who answers this agent's requests** decides who may approve the agent's actions and answer its questions. Choose **Everyone in workspace** (the default) or pick members. This setting also limits who can run, pause, rename, duplicate and archive the agent: see [Good to know](#good-to-know).

### Advanced settings

* **Model credit limit**: an optional cap on the AI credits the agent may spend, **across all of its runs combined** (not per run). Tool credits are charged separately and don't count. Leave it empty for no limit. Allowed values are 10 to 10,000,000 credits.
* **Memory → Manage**: appears after the agent is created. See [Memory, reference files and artifacts](#memory-reference-files-and-artifacts).

## Add triggers

A **trigger** is the event that wakes the agent up, for example "an email arrives" or "every weekday at 9:00". Each time a trigger fires, the agent starts a new, separate run.

<Steps>
  <Step title="Click Add trigger">
    In the agent's configuration (on the create form, or **Edit** on the agent page), click **Add trigger** and pick a type: **Run every row of a list**, **Event**, **Manually** or **Schedule**.
  </Step>

  <Step title="Configure it">
    In **Configure trigger**, choose the **Event**, give it a **Display name**, pick the **Connected account** if the event needs one, and fill in any extra fields (for example the list to watch, or filters such as "Only run for records that match these conditions").
  </Step>

  <Step title="Save">
    Click **Save trigger**. Trigger changes are only stored when you click **Create agent** or **Save changes**.
  </Step>
</Steps>

What the trigger types do for an Agent:

* **Run every row of a list**: offers record events such as **Record Created** and **Record Updated** on a list you choose. (For an Agent this reacts to changes; it does not loop through every row like a workflow does.)
* **Event**: anything from the event catalog, such as **Email Received**, **Email Sent**, **LinkedIn Message Received**, calendar events, Slack, HubSpot, Calendly or **Custom Webhook**. See [Triggers](/automations/workflows/triggers) for what the events mean.
* **Manually**: adds a **Run now** button on the trigger row so you can start the agent's routine yourself.
* **Schedule**: runs on a timetable. Choose a **Frequency**: **At a set interval** (Repeat every N minutes, hours or days, counted from when the trigger is turned on), **Once a day** (**Run at**), **Once a week** (**Day of week** and **Run at**) or **Custom schedule** (a five-part **Cron expression** such as `0 9 * * 1-5`). Set the **Timezone**; it defaults to your browser's.

For **Email Received**, **Email Sent** and **LinkedIn Message Received**, you can pick **All connected \[provider] accounts**. That option also covers accounts connected later. If you pick specific accounts instead, accounts connected later are **not** included.

<Warning>
  A **Custom Webhook** trigger shows a **Copy webhook URL** button. The URL itself is the only password: anyone who has it can wake the agent. Don't share it publicly. If it leaks, remove the trigger and add a new one to get a new URL.
</Warning>

Each trigger row shows its health when you hover it: "Never fired", "Last run succeeded…", or "Last run failed… " with the error. A trigger that still needs setup shows **Finish setup** in red.

## Choose tools

**Tools** are the actions the agent may take, such as sending an email, searching the web or updating a record.

<Steps>
  <Step title="Click Add tools">
    The **Select Tools** window opens. Browse by category, or use **Suggestions** and **Selected**. Switch on the tools you want, then click **Continue**. **Enable all** turns on every tool in the workspace.
  </Step>

  <Step title="Connect accounts">
    If a tool's app isn't connected yet, click **Connect** next to it. See [Connect accounts](/tools/connect-accounts).
  </Step>

  <Step title="Pick which account the agent uses">
    Tools from a connected app show a chip such as "1 of 2 accounts connected". Click it to choose which accounts the agent may act as, then click **Save**.
  </Step>
</Steps>

The **All available tools** switch gives the agent every tool available now. Give the agent only what it needs: an agent with fewer tools is safer and usually works better.

There's no per-tool approval switch inside the agent. What needs approval comes from your workspace's tool permissions (see [Tool permissions](/tools/permissions)) and from the agent's **When should the agent ask for approval?** rule. A tool set to **Disabled** in Tools can't be used by any agent.

## Set the agent live or pause it

The main button on the agent page is **Set live** (or **Pause** when the agent is live).

* **Set live** turns its triggers on. If the agent has no triggers, Connie opens the configuration and shows "Add a trigger before setting this agent live. It only runs when someone starts it until then."
* Before going live, Connie checks the agent. If something looks wrong you see **Check \[agent name] before it runs**, listing problems such as "This Agent has no usable tools", "This Agent can only observe", "N enabled tools need a connected account" or "\[app] is not connected". Click **Open Tools** to fix them, or **Set live anyway**. The check advises; it never blocks you.
* **Pause** turns the triggers off. You see "Automatic triggers paused".

Live or Draft only affects **automatic** triggers. You can chat with a Draft agent and use **Run now** at any time.

## Run and chat with an agent

Open an agent to see its home page:

* **Left:** a chat box (**Ask anything...**) and the agent's **History**.
* **Right:** **Action required**, **Instructions**, **Artifacts**, **Trigger** and **Memory**.

To run the agent yourself, type a request and send it. Each message you send from the home page starts a new run in **History**. Open a run to see what the agent did; follow-up messages in that run stay in the same History entry. In the chat box you can attach files, type **/** to use a [skill](/skills/overview), and type **@** to mention workspace content.

To run the agent's full routine without typing, add a **Manually** trigger and click **Run now** on it (save your changes first). The run appears in **History** marked **Manual**. Runs from triggers are marked **Automatic**.

**Run statuses in History:**

| Status | What it means |
| - | - |
| **Queued** | Accepted, not started yet |
| **Running** | Working now |
| **Action required** | Waiting for someone to approve or reject an action |
| **Needs input** | The agent asked a question and is waiting for an answer |
| **Completed** | Finished |
| **Completed with issues** | Stopped early; some work may be missing |
| **Needs review** | Finished, but flagged for a person to check |
| **Failed** | Hit an error |
| **Cancelled** | Stopped |
| **Not started** | Never ran |
| **Credit limit reached** | The workspace ran out of credits during the run |
| **Cost limit reached** | The agent hit its own **Model credit limit** |

The **Analytics** button in the header opens a side panel with the agent's charts. Agents created from a template show **Runs**, **Completed actions** and **Failures**. Agents you created from scratch show "No Analytics widgets yet".

## Approve what an agent does

When an agent wants to do something that needs a person's OK, the run pauses.

* If you started the run by chatting, the approval card appears right in the conversation with **Reject** and **Allow** (or **Approve**).
* If a trigger or **Run now** started it, the item appears under **Action required** on the agent's home page (✓ to approve, ✗ to reject), and members get a bell notification "\[agent name] needs approval".

Unattended approvals don't wait forever. See [Approvals](/automations/approvals) for deadlines, who can approve, and where to find pending items.

## Memory, reference files and artifacts

* **Memory** is one short summary the agent keeps about what it has learned from its runs. Click the **Memory** card to open **Memory summary**. Edit the text directly with the pencil, or type an instruction in **Add or update** ("Always CC sales@ on replies") and send it. The summary must stay below 2,000 tokens.
* **Reference files** are documents the agent can read when it needs them, such as a pricing sheet or a playbook. Click **+** on the **Artifacts** card. Accepted: PDF, DOCX, TXT or MD, up to 3 MB. Use each file's menu to **Replace file** or **Remove reference**.
* **Artifacts** lists what the agent produced in its runs (records, workflows, analytics, files) alongside your reference files.

## Organise, duplicate and delete agents

Use the **⋮** menu on a row of the Agents page, or the **▾** next to the agent's name in its breadcrumb:

* **Star** / **Unstar**: pins it to the top of the list.
* **Rename**.
* **Duplicate**: makes a copy with the same instructions, rules, tools and triggers. The copy is a **Draft** with its triggers off, and it opens on its configuration: "Duplicated from … review and activate when ready. Triggers are copied but inactive." Memory, artifacts and history are not copied. You become the copy's owner.
* **Move to** a folder (or create one there). Folders are shared with Automations.
* **Delete** (or **Archive** on the agent page): turns off all its triggers and moves it to the **Archived** tab. Its history is kept. Nothing is permanently deleted.

To bring an agent back, open **Archived** and click **Restore**. It comes back as a **Draft**: click **Set live** to turn its triggers on again.

To share an agent with teammates or publish it as a template, click **Share** on the agent page. See [Templates and sharing](/automations/templates-and-sharing).

## Manage agents from Chat

In any [chat](/chat/overview), you can ask Connie to list, create, change, pause or resume your agents, add or remove triggers, or send an agent a message and wait for its answer. Connie shows an approval card before it changes anything, and a result card that links to the agent's run.

## The 'Run AI agent' workflow step

**Run AI agent** is a step inside a [workflow](/automations/workflows/build), not a standalone Agent. It does one AI task each time the workflow reaches it (once per run, or once per row) and passes its answer to later steps as [variables](/automations/workflows/variables).

**How to add it:**

* **Automations → New → New workflow → AI Agent** creates a workflow with a **Schedule** trigger and a **Run AI agent** step.
* Or, in any workflow, add a step and choose **Run AI agent** (category **AI**, or search "agent").

**Fields:**

* **Task** (required): what to do, in plain language. Be specific about inputs and the result you want. You can insert variables from earlier steps.
* **Model**: which AI model runs the step. Its help text tells you which models need at least one tool switched on.
* **Enabled Tools**: the tools the step may use. On a new step, an empty selection means **All tools**. Choose **No tools** if you want none.
* **Output**: one text column, or separate fields that each become a column.

**Using the answer:** refer to `{{<step name>.response}}` for the answer, `{{<step name>.response.<field>}}` for one field of a structured answer, and `{{<step name>.summary}}` for a one-sentence recap.

**Credits:** 1 credit for the step, plus AI usage, plus the price of any paid tools it calls. It's charged every time the step runs, so once per row on list workflows. The badge "From N" is a minimum estimate, not the final charge.

**Limits:** one step must finish within about 20 minutes and 999 tool steps. For big jobs, give it fewer items per run or loop with **For each** (see [Logic](/automations/workflows/logic)).

## Good to know

* **Who can create agents:** workspace owners, admins and members. Guests can only view agents shared with them.
* **Who can run, pause, approve, rename, duplicate or archive:** members with edit access, as long as **Who answers this agent's requests** is **Everyone in workspace** or they are listed there. Workspace owners and admins can always do these. Restricting approval owners therefore also restricts who can control the agent.
* **An agent acts as its creator.** Its tools use the creator's access and connected accounts. If the creator leaves the workspace, the agent can't run.
* **Credits:** an agent is charged for AI usage (at least 1 credit per AI step, more for longer work) plus the price of each paid tool it calls. Chatting with an agent costs the same as a triggered run. There is no fixed fee per run. See [Credits](/billing/credits).
* **Model:** Connie chooses the model for standalone agents. There's no model setting.
* **Runs at the same time:** each trigger event starts its own run, so several runs can happen at once. One conversation can only have one turn running at a time.
* **Limits:** name 160 characters; instructions 50,000 characters; **Model credit limit** 10 to 10,000,000; reference files 3 MB each.
* **How many agents:** there's no set limit on the number of agents in a workspace.

## Troubleshooting

<AccordionGroup>
  <Accordion title="I can't find my Agents anywhere">
    **Why:** Agents have no sidebar entry and aren't listed on the Automations page. **Fix:** go to `https://connie.ai/<workspace-id>/agents`, or search the agent's name with ⌘K.
  </Accordion>

  <Accordion title="Clicking 'Automations' in the breadcrumb lost my list of agents">
    **Why:** the breadcrumb always goes to the Automations page, which doesn't show Agents. **Fix:** go back to `https://connie.ai/<workspace-id>/agents`.
  </Accordion>

  <Accordion title="I chose AI Agent under New workflow and got a workflow">
    **Why:** that option creates a workflow with a **Run AI agent** step. **Fix:** that's expected. For a standalone Agent, use **New agent** on the Agents page.
  </Accordion>

  <Accordion title="Set live just opened the settings">
    **Why:** the agent has no triggers. **Fix:** click **Add trigger**, set it up, click **Save changes**, then **Set live**.
  </Accordion>

  <Accordion title="The agent is Live but never runs, or the trigger says 'Never fired'">
    **Why:** the trigger's account isn't connected or was disconnected, the wrong account is selected, or the account was connected after you picked specific accounts. **Fix:** reconnect the account in [Tools](/tools/connect-accounts), edit the trigger and choose the account again (or **All connected … accounts**), click **Save changes**, then **Set live**.
  </Accordion>

  <Accordion title="Trigger … needs a connected account before this agent can resume / A trigger account is disconnected">
    **Why:** a trigger has no working account. **Fix:** connect or reconnect the account, edit the trigger, save, then click **Set live**.
  </Accordion>

  <Accordion title="After Create agent it stayed a Draft with '… needs an account. Finish that trigger in Configuration'">
    **Why:** a suggested trigger had no account yet. **Fix:** open the configuration, finish that trigger, click **Save changes**, then **Set live**.
  </Accordion>

  <Accordion title="A duplicated or restored agent doesn't run">
    **Why:** copies and restored agents are Drafts with their triggers off. **Fix:** review it, then click **Set live**.
  </Accordion>

  <Accordion title="Check [agent] before it runs: 'This Agent can only observe' or 'has no usable tools'">
    **Why:** the agent has no tools that can change anything, or its tools need accounts. **Fix:** click **Open Tools**, switch on the tools it needs and connect their accounts. If the agent is meant only to read and report, click **Set live anyway**.
  </Accordion>

  <Accordion title="… tools are pinned to an account that no longer exists">
    **Why:** the account a tool was set to use was disconnected or replaced. **Fix:** reconnect it, or click the tool's account chip and choose another account.
  </Accordion>

  <Accordion title="I can't approve: the approve button is greyed out">
    **Why:** you aren't listed in **Who answers this agent's requests**, you're a guest or have view-only access, or the agent is archived. **Fix:** ask a listed approver or a workspace owner or admin, or ask them to add you.
  </Accordion>

  <Accordion title="I can't rename, run or pause the agent">
    **Why:** you have view-only access, or approval owners are restricted and you aren't one of them. **Fix:** ask the creator or an admin to give you edit access and add you as an approval owner.
  </Accordion>

  <Accordion title="This request has expired. Please try again.">
    **Why:** an approval from an unattended run passed its deadline, so the run ended without doing that action. **Fix:** start the run again.
  </Accordion>

  <Accordion title="This thread already has a turn in progress. Try again when it finishes.">
    **Why:** that conversation is still working. **Fix:** wait, or start a new run from the agent's home page.
  </Accordion>

  <Accordion title="This chat is waiting for your input. Answer or dismiss the pending question, then try again.">
    **Why:** the agent asked you something (**Needs input**). **Fix:** answer or dismiss the question in the run, or under **Action required**.
  </Accordion>

  <Accordion title="Agent '…' cannot run because its creator no longer has workspace access.">
    **Why:** agents act as the person who created them. **Fix:** restore that person's access, or have an active member **Duplicate** the agent. The copy runs as them; set it live after checking its accounts.
  </Accordion>

  <Accordion title="Agent '…' is archived and cannot accept new messages.">
    **Why:** the agent was deleted (archived). **Fix:** open **Archived** on the Agents page and click **Restore**.
  </Accordion>

  <Accordion title="Run status 'Credit limit reached' or notification '… needs AI credits'">
    **Why:** the workspace ran out of credits mid-run. Work already done is kept and spend so far is billed. **Fix:** [add credits](/billing/top-ups), then start a new run. Adding credits doesn't restart the old run.
  </Accordion>

  <Accordion title="Run status 'Cost limit reached'">
    **Why:** the agent has used up its **Model credit limit**, which counts all runs together. **Fix:** raise or clear it in **Edit → Advanced settings**.
  </Accordion>

  <Accordion title="Run now is greyed out, or missing">
    **Why:** greyed out means you have unsaved changes; missing means the agent has no **Manually** trigger. **Fix:** click **Save changes**, or add a **Manually** trigger.
  </Accordion>

  <Accordion title="The toast says 'follow it in Activity' but there's no Activity tab">
    **Why:** the wording is out of date. **Fix:** the run is in **History** on the agent's home page, marked **Manual**.
  </Accordion>

  <Accordion title="Could not draft this agent / AI drafting is temporarily unavailable">
    **Why:** the AI draft failed. **Fix:** click **Try again**, or **Configure manually** and fill in the form yourself.
  </Accordion>

  <Accordion title="Keep the memory summary below 2,000 tokens. Shorten the text and try again.">
    **Why:** the memory summary is too long. **Fix:** shorten it, or move detail into a reference file.
  </Accordion>

  <Accordion title="Run AI agent step: 'Agent hit its step limit…' or 'Agent ran out of time…'">
    **Why:** the step used its 999 tool steps or about 20 minutes without an answer. **Fix:** narrow the **Task**, switch on fewer tools, give it fewer items per run, or loop with **For each**.
  </Accordion>

  <Accordion title="Run AI agent step: 'Agent finished without producing the JSON its output column requires…'">
    **Why:** you defined output fields but the AI answered in prose. **Fix:** make the **Task** and field descriptions more specific, or switch **Output** to one text column.
  </Accordion>

  <Accordion title="My Run AI agent step used tools I didn't pick">
    **Why:** on a new step, an empty **Enabled Tools** list means all tools. **Fix:** select specific tools, or choose **No tools**.
  </Accordion>
</AccordionGroup>

## Related

* [Approvals](/automations/approvals): deadlines, who can approve, where pending items show up
* [Scheduled tasks](/automations/scheduled-tasks): recurring instructions in a chat
* [Templates and sharing](/automations/templates-and-sharing): share an agent or publish it as a template
* [Automations overview](/automations/overview): workflows vs agents vs scheduled tasks
* [Tool permissions](/tools/permissions): which actions need approval
* [Credits](/billing/credits): how AI usage and tools are charged


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.