> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Agents

Agents [#agents]

An agent belongs to one workspace and combines a model, a prompt, tools, skills, files and connections; each run acts as the caller in that workspace.

* [Create and configure an agent](./create-and-configure)
* [Run an agent and stream its events](./run-and-stream)
* [Hosted agent apps](./apps)
* [Agents API reference](./api/get_api_v1_agents_v2_agents)

Building blocks [#building-blocks]

| Part                  | Field                                                     |
| --------------------- | --------------------------------------------------------- |
| Model                 | `model_config_id`                                         |
| Prompt                | `system_prompt` (required); optional `prompt_template_id` |
| Runtime tools         | `tool_names`                                              |
| Reusable instructions | `enabled_skill_slugs`, `enabled_skill_set_slugs`          |
| Files knowledge       | `enabled_file_scope`                                      |
| Data and SaaS access  | `enabled_connection_ids`                                  |
| Remote tools          | `enabled_mcp_connection_ids`                              |

Agents in a workspace [#agents-in-a-workspace]

`GET /api/v1/agents-v2/agents/` returns the workspace's own agents and the platform agents installed in it. Add `?show_platform=true` to include every other platform agent, with `installed: false`.

| Field                   | Meaning                                                                                                                       |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | Identifies the agent in run and edit calls. Names can repeat; ids cannot                                                      |
| `scope_visibility`      | `space`: the workspace's own agent, and `space_slug` names the workspace. `global`: a platform agent from the Alomana catalog |
| `installed`             | For a platform agent, whether it is installed in this workspace                                                               |
| `is_default`            | The workspace's default agent, which `POST /api/v1/agents-v2/agents/run-stream/` runs                                         |
| `is_workspace_required` | Alo, App Builder and Agent Builder: installed in every workspace and cannot be removed                                        |
| `catalog_kind`          | Catalog metadata, not ownership. Use `scope_visibility` to tell the workspace's agents from platform agents                   |

Authentication [#authentication]

Every request sends `X-Space-Slug` and one credential; see [Authentication and API keys](../api-basics/authentication).

| Task                                                                                                                                   | Auth          |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| Create, edit, delete and fork agents, from JSON or a ZIP bundle; export one                                                            | Key or bearer |
| Skills, skill sets, prompt templates and marketplace skills                                                                            | Key or bearer |
| Run an agent; follow, read and cancel background runs                                                                                  | Key or bearer |
| [Apps](./apps): edit, open, secrets, copy and sync                                                                                     | Key or bearer |
| [Scheduled tasks](./scheduled-tasks); [Slack](./slack) installations: list, rename, remove                                             | Key or bearer |
| [Chats](./chats): list, read, rename, delete and share; list or delete a chat's sandbox files; run a scheduled task now; install Slack | Bearer only   |

An API key on a bearer-only route gets `401 {"detail": "Not authenticated"}`.