---
title: "Agents"
space: "Raven"
url: "https://docs.frappe.io/raven/agents-and-webhooks/agents"
updated: "2026-10-19"
---
An agent is a Raven user that posts messages for another system. Messages from an agent show the agent's name.
Agents post the messages from [incoming webhooks](wiki:40bd4f13d16c), [recurring agent messages](wiki:ee12bcc84a4b) and [document notifications](wiki:14f564810d8c). Your own code can post as an agent too. An agent can post in any channel. It does not need to be a member.
Manage agents in **Settings > Agents**.
:::note
Only Raven admins and System Managers can create, change or delete agents.
:::
## Create an agent
1. Open **Settings > Agents**.
2. Click **Create**.
3. Enter a **Name**. This is the name people see on the agent's messages.
4. If you like, enter a **Description**.
5. Leave **Is AI Agent** off.
6. Click **Create**.
The name must be unique. It can't be changed after you create the agent.
AI features in Raven are being retired. Keep **Is AI Agent** off. An agent without AI does not reply to messages.
## Change or delete an agent
Click an agent in the list to open it.
- To change the description, edit it and click **Save**.
- **Open Chat** opens a direct message with the agent.
- The **API Docs** tab shows code to post as this agent.
- To delete the agent, click **⋮** next to **Open Chat**, click **Delete** and confirm.
## Post as an agent from code
A server script or a custom Frappe app can post as an agent. In code, an agent is a record of the DocType `Raven Bot`. Load the agent by its name, then call one of its methods. Each method returns the ID of the new message.
### Post in a channel
```python
agent = frappe.get_doc("Raven Bot", "Releases")
agent.send_message(
channel_id="lumen-cycles-engineering",
text="**Version 2.4** is live.",
markdown=True,
)
```
The channel ID is the last part of the channel's address in your browser. For example, in `/raven/Lumen%20Cycles/lumen-cycles-engineering` it is `lumen-cycles-engineering`.
### Send a direct message
```python
agent.send_direct_message(
user_id="maya@lumencycles.com",
text="Your export is ready.",
)
```
`user_id` is the person's email address, their user ID on the site. Raven opens a direct message between the agent and the person if there isn't one yet. Nothing is sent if the person is disabled. If the person is not on Raven, Raven raises an error.
### Attach a document
Any document from any Frappe app on your site can be attached. The message shows a preview of it. In a document event server script, `doc` is the document that changed:
```python
agent.send_message(
channel_id="lumen-cycles-finance",
text="This needs a review.",
link_doctype=doc.doctype,
link_document=doc.name,
)
```
### Reply in a thread
Pass the thread's ID as `channel_id`. The thread ID is the ID of the message the thread was started on.
```python
agent.send_message(
channel_id="q8x2k4m1pz",
text="The build for this branch passed.",
)
```
The thread must already exist. There is no method to start a new thread as an agent.
To find a thread's ID, open the thread. Its ID is the last part of the address, after `/thread/`.
### Arguments
`send_message` and `send_direct_message` take the same arguments, except for the first one.
| Argument | What it does |
| :--- | :--- |
| `channel_id` | The channel or thread to post in. `send_message` only. |
| `user_id` | The person to send a direct message to. `send_direct_message` only. |
| `text` | The message. It is HTML unless `markdown=True`. |
| `markdown` | Set to `True` to write `text` in Markdown. |
| `link_doctype` | The DocType of the document to attach. |
| `link_document` | The name of the document to attach. |
| `file` | The URL of a file on your site to send, such as `"/files/report.pdf"`. JPG, PNG, GIF and WEBP files show as images. |
