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
- Run an agent and stream its events
- Hosted agent apps
- Agents API reference
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
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
Every request sends X-Space-Slug and one credential; see Authentication and API keys.
| 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: edit, open, secrets, copy and sync | Key or bearer |
| Scheduled tasks; Slack installations: list, rename, remove | Key or bearer |
| 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"}.