# Agents and AI models

Give your module its own AI agent: its name, its instructions, which model it uses and what it may do.

Every module can come with its own AI teammate. An **agent** knows your module's records, uses your module's actions, and follows your module's playbooks. People chat with it in plain words: *"which jobs are behind schedule?"*, *"add these 40 parts from my spreadsheet"*. You describe the agent once; the platform runs it, checks every step against permissions, and records what it did.

## The agent's identity

You give the agent:

| Part | Example |
|---|---|
| **Name** | *Jobs assistant* |
| **Instructions** | Who it is, what it's for, and how it should behave |
| **Tools** | The actions it may take. See [Agent tools](article:8b4baa95-08a0-4e8e-a7e4-890815c6005b) |
| **Skills** | Step-by-step playbooks. See [Skills and scripts](article:26233420-12e1-4c83-8b9a-35004ce84d89) |
| **Memory** | Whether it remembers past conversations: automatic, housekeeping, or none |

Each workspace that installs your module gets **its own copy** of the agent. A Workspace Admin can rename it, adjust its instructions, model and memory under **System settings › Agents**, see its **History**, undo changes, and bring back your version with one click.

## The roles it holds

An agent never does more than the identity it acts for:

- **In chat**, it acts as the person chatting, with exactly their permissions. It isn't even offered tools they don't hold.
- **On a schedule or trigger**, nobody is chatting, so it acts as **its own identity**. That identity holds only the roles a Workspace Admin ticks on the agent's **Permissions** tab. With no role, those runs are refused.

## Choosing a model, and whose key pays

**Leave the model out** (recommended). Your agent then uses the workspace's default model, which a Workspace Admin sets under **System settings › AI providers**. Name a specific model only if your agent truly needs it; every workspace then needs that provider set up.

Who pays depends on the workspace's AI setup:

| Key | What it means |
|---|---|
| **Provided by Data Visions** | Usage appears on the workspace's bill, using its AI credits. |
| **The workspace's own key** | The provider bills the workspace directly. Data Visions switches this option on for a workspace. |

There's no backup key. A workspace with no AI set up gets a clear message: *"AI isn't set up for your organization yet"*. Show it as it is.

Every AI call is logged against your module, so the workspace sees exactly what your agent used under **System settings › Billing**.

## Where people chat with it

- **In your module**: the robot icon in the module's header opens the agent's chat beside the screen. People can attach files, use voice, and stop a run.
- **In Claude or ChatGPT**: with the Data Visions connector, a person's own AI assistant can use your module's read tools and skills, with the same permissions. See [Build modules with Claude](article:f42b51c4-fec0-45db-884b-01acc515da65).
- **From a button**: a long AI job your screen starts (analyze a whole drawing set) runs as your agent too, so it's traced and billed like any other.

## Ask the Module Builder

> *"Give this module an assistant called Jobs Helper. It answers questions about jobs and crews and can update a job's status, but asks first before closing a job."*

## For developers

```json
"ai": {
  "agent": {"agent_code": "JOBS_AGENT", "agent_name": "Jobs Helper",
            "persona": "You help crew leads and the office with jobs...",
            "max_iterations": 20, "temperature": 0.3, "memory_mode": "automatic"},
  "tools": ["find_jobs", "set_job_status"],
  "skills": ["weekly-job-review"]
}
```

Test it from the command line: `platform agents chat JOBS_AGENT "Which jobs are late?"`.

## Good to know

- **Don't build your own AI loop.** Long, many-step AI work belongs to your agent, so it gets permissions, tracing and billing for free.
- **A newer agent in your next version** shows as *Newer version in its module* on the Agents screen; workspace edits are kept until the admin chooses to reset.
- **Model settings in your module** (a "summary model" setting, say) get a proper model picker that only offers current models.


Source: https://datavisions.ai/docs/creators/platform-services/agents-and-ai-models
