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

> ## Agent Instructions
> The docs are served at https://docs.devias.io. Every path in these docs is relative to that root: /llms.txt is https://docs.devias.io/llms.txt.
> Devias is an open-source platform that works as an operating system for a business: a core (records, views, workflows, agents, permissions) with installable modules.
> Pages are typed by folder. concepts/ explains what things are, guides/ gives procedures, reference/ is exhaustive (SDK, CLI, HTTP API), operate/ covers hosting. Use /start/glossary for exact terms.
> Every id in a module (module, object, field, view, action, workflow, step, connection, variable, event, policy) is a uuid. Generate them with `devias id <count>`. Never invent dotted or readable ids.
> Run `devias plan` and read its output before `devias apply`. Apply only what the plan says.
> The OpenAPI document, including the routes of the modules in the reference setup, is at /reference/api/openapi.json.
> Devias is young and changes quickly. If a page and the source repository (github.com/devias-io/devias) disagree, the repository is right.

# Agents

> What a Devias agent is and how it behaves. An agent is instructions plus a list of tools, acts with the role of the person who asked, and stops at an approval card for any tool set to ask first. Covers where agents come from, skills and the provider key agents need.

An **agent** is an AI assistant that works inside a workspace. It looks things up, creates and updates records, runs workflows and takes tasks, through the same actions the studio uses. It can do what the person who asked can do, and nothing else.

![An approval card titled Add a comment to a deal, showing the comment's title and text, with Approve and Reject buttons](https://mintcdn.com/devias/TzMNPlq81mH0Qrj7/images/studio-approval.webp?fit=max\&auto=format\&n=TzMNPlq81mH0Qrj7\&q=85\&s=4fde5552d96bf8243f76df880384d4ee)

An approval card: the agent says what it wants to do, and waits.

## What happens when you ask an agent

1. A message is sent, and the studio streams the agent's work back as it happens.
2. The agent chooses which **tools** to use: look up records, create one, run a workflow.
3. Reading and everyday edits, such as creating or updating a record, run immediately. A tool set to **Ask first**, such as one that deletes records or sends a notification, stops and shows an **approval card**.
4. The person approves or rejects. The agent continues with the result and answers.

The whole conversation is saved, including each tool call and each decision.

## Parts of an agent

An agent is a set of instructions plus a **list of tools**. A tool is one thing the agent may do, such as "list records" or "create a task". Each tool is set to one of two modes.

| Mode | Behaviour |
| - | - |
| Runs freely | The tool runs without asking. |
| Ask first | The tool stops and shows an approval card. The person accepts or rejects it. |

The tool list is the agent's boundary: an agent can only do what its tools allow. See [Tools and approvals](https://docs.devias.io/guides/agents/tools-and-approvals.md).

## Who an agent acts as

An agent acts for the person who asked, with that person's role. It can never do more than they could. History records both, so the changes an agent made and the person it acted for are visible.

## Questions and secrets

When an agent needs something it cannot guess, it asks a question and waits for the answer. When a step needs a secret, such as an API key, the approval card shows a form. The value goes from the person straight to the run, is never stored, and is never shown to the model.

## Where agents come from

* Every workspace has a default assistant. `⌘J` opens it.
* A workspace can create its own agents in the studio. See [Define an agent](https://docs.devias.io/guides/agents/define-an-agent.md).
* A module can ship agents. The CRM ships a Sales agent that works the pipeline.
* Tasks: a task can be given to an agent that takes tasks. It works through the task for the person who assigned it.

## Skills

A **skill** is a short how-to that an agent loads only when a request calls for it, such as "how we qualify a lead". A workspace or a module can write skills. See [Skills](https://docs.devias.io/guides/agents/skills.md).

## Requirement: a provider key

Agents need a key from an AI provider: Anthropic, Google or OpenAI. See [Turn on agents in the quickstart](https://docs.devias.io/quickstart.md#turn-on-agents) and [Environment variables](https://docs.devias.io/operate/environment.md).

## Related

* [Use the assistant](https://docs.devias.io/guides/studio/agents.md): use agents in the studio.
* [Define an agent](https://docs.devias.io/guides/agents/define-an-agent.md): create one in the studio or in a module.
* [Access and permissions](https://docs.devias.io/concepts/access.md): what each role can do.


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