Create and configure an agent
Create reusable resources first—prompt templates, skills, connections, and Files folders—then reference their IDs or slugs from the agent.
curl -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Space-Slug: acme" \
-H "Content-Type: application/json" \
-d '{
"name": "Contract analyst",
"description": "Answers questions about the contracts workspace",
"system_prompt": "You are a careful contract analyst. Cite the source file for every conclusion.",
"model_config_id": 12,
"tool_names": ["files-search", "code-execution"],
"enabled_skill_slugs": ["contract-review"],
"enabled_connection_ids": [42],
"enabled_mcp_connection_ids": [7],
"enabled_file_scope": {"file_ids": [], "folder_ids": ["legal-folder-id"]}
}'tool_names enables runtime abilities. Skills and skill sets add reusable operating instructions. enabled_file_scope limits which Alo Files files or folders the agent can search. Standard and MCP connection IDs are resolved at run time and remain subject to ownership and space permissions.
Update with PATCH /api/v1/agents-v2/agents/{agent_id}/. All of the endpoints below accept an API key (X-API-Key) with X-Space-Slug.
Browse the building blocks
Discover the IDs, slugs, and names to reference from an agent:
| Method | URL | Purpose |
|---|---|---|
GET | /api/v1/agents-v2/models/ | List model configs (?enabled_only) — model_config_id values |
GET | /api/v1/agents-v2/tools/ | List built-in tools — each name, display_name, description for tool_names |
GET | /api/v1/agents-v2/tool-sets/ | List tool sets — each name, label, tool_names |
GET | /api/v1/agents-v2/skills/ | List skills (?source); GET /skills/{skill_id}/ reads one (resolves global skills too) |
GET | /api/v1/agents-v2/skill-sets/ | List skill sets |
GET | /api/v1/agents-v2/prompt-templates/ | List prompt templates; GET /prompt-templates/{prompt_id}/ reads one |
curl "$CENTRAL_HUB_URL/api/v1/agents-v2/tools/" \
-H "X-API-Key: $ALO_API_KEY" -H "X-Space-Slug: $WORKSPACE_SLUG"Author prompts and skills
Prompt templates and skills you create through the API are workspace-scoped. Platform (global) resources are read-only over the API — editing one returns 403; clone it into the workspace instead. On update, send only the fields you are changing and never send slug (identity is fixed).
| Method | URL | Purpose |
|---|---|---|
POST | /api/v1/agents-v2/prompt-templates/ | Create a workspace prompt template |
PATCH | /api/v1/agents-v2/prompt-templates/{prompt_id}/ | Update a workspace prompt template in place |
POST | /api/v1/agents-v2/skills/ | Create a workspace skill (from a SKILL.md body; no aux files) |
PATCH | /api/v1/agents-v2/skills/{skill_id}/ | Update a workspace skill in place |
POST | /api/v1/agents-v2/skills/upload/ | Upload a skill as a ZIP archive (scripts + resources) |
For a skill that ships scripts or reference files, upload a ZIP instead of a single body. upsert=false (the default) always creates — a re-upload of the same slug lands as slug-2; upsert=true updates the existing workspace skill with that slug in place:
curl -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/skills/upload/?upsert=true" \
-H "X-API-Key: $ALO_API_KEY" -H "X-Space-Slug: $WORKSPACE_SLUG" \
-F "file=@contract-review.zip;type=application/zip"Publish and export agent bundles
Move a whole agent between environments as a ZIP bundle (agent.yaml + PROMPT.md at the root, plus optional skills/<slug>/SKILL.md). The bundle upserts by the slug in agent.yaml.
| Method | URL | Purpose |
|---|---|---|
POST | /api/v1/agents-v2/agents/upload/ | Publish (create/update) an agent from a bundle ZIP |
GET | /api/v1/agents-v2/agents/{agent_id}/export/ | Download an agent as a bundle ZIP |
Pass ?check=true for a dry run — the response's results list each planned change as {kind, slug, action: "would_create" | "would_update"} without writing anything:
# Dry-run first
curl -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/upload/?check=true" \
-H "X-API-Key: $ALO_API_KEY" -H "X-Space-Slug: $WORKSPACE_SLUG" \
-F "file=@contract-analyst.zip;type=application/zip"
# Then publish for real
curl -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/upload/" \
-H "X-API-Key: $ALO_API_KEY" -H "X-Space-Slug: $WORKSPACE_SLUG" \
-F "file=@contract-analyst.zip;type=application/zip"
# Export an existing agent
curl "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/42/export/" \
-H "X-API-Key: $ALO_API_KEY" -H "X-Space-Slug: $WORKSPACE_SLUG" \
-o contract-analyst.zip