Create and configure an agent

Create the prompt templates, skills, connections and Files folders an agent uses, then publish the agent as a bundle or create it as JSON.

Write paths

Platform agents are read-only: PATCH or DELETE on one returns 403 Default platform resources are read-only.; fork it instead.

Agent fields

Fields of the JSON body; agent.yaml differs as listed under agent.yaml keys.

Building blocks

Prompt templates and skills

• Created prompt templates and skills belong to the workspace.
• Platform (global) ones are read-only: PATCH returns 403 Default platform resources are read-only. Copy one into the workspace instead.
• PATCH takes only the fields you change. Sending slug renames the row (suffixed -2 when taken); agents and skill sets keep the old skill slug, and a bundle upload finds its prompt template by slug, so a rename breaks those references.

Skill sets

A skill set groups workspace skills so an agent can enable them together with enabled_skill_set_slugs.

skill_slugs must name skills in the workspace. A platform skill's slug returns 422 Unknown skills for selected space: <slug>; fork it first and use the fork's slug.

Skills from the marketplace

curl -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/skills/marketplace/install/" \
  -H "X-API-Key: $ALO_API_KEY" \
  -H "X-Space-Slug: $WORKSPACE_SLUG" \
  -H "Content-Type: application/json" \
  -d '{"slug": "pdf", "github_repo": "anthropics/skills", "github_path": "pdf"}'

Bundle format

contract-analyst.zip
├── agent.yaml
├── PROMPT.md
└── skills/
    └── contract-review/
        └── SKILL.md

• Exactly one agent.yaml; PROMPT.md and skills/ sit next to it.
• Each skills/<slug>/SKILL.md becomes a workspace skill with that slug and is added to the agent's skills.
• Limits: 30 MB compressed and 30 MB uncompressed per archive (400); 500 KB for agent.yaml, PROMPT.md and each SKILL.md (422).
• Every other file in a skill folder is kept, binary files included. Only .DS_Store, Thumbs.db and anything under .git/ are dropped, without an error.

agent.yaml keys

• Any other key is ignored with a warning, such as agent.yaml has unrecognized field 'tool_names' — ignored. kind is accepted and has no effect.
• On update, name, tools, enabled_skill_slugs and the prompt are always replaced; an omitted tools clears the agent's tools. Other omitted keys keep their current values.
• A slug that matches a platform agent, prompt template or skill adds a warning: the workspace copy shadows it.

Minimal agent.yaml:

slug: contract-analyst
name: Contract analyst
description: Answers questions about contracts
model_slug: claude-sonnet-5
tools:
  - web-search

Publish an agent bundle

1. Build the ZIP in the bundle format.

2. Dry-run it with ?check=true; nothing is written:

   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"

   {
     "check": true,
     "agent": null,
     "results": [
       {"kind": "skill", "slug": "contract-review", "id": null, "action": "would_create"},
       {"kind": "prompt_template", "slug": "contract-analyst", "id": null, "action": "would_create"},
       {"kind": "agent", "slug": "contract-analyst", "id": null, "action": "would_create"}
     ],
     "warnings": []
   }

3. Send the same request without ?check=true. The response is 200 with check: false, the saved agent in agent, and each row's id with action created or updated.

Create an agent as JSON

1. Find the IDs and names to reference, for example the tools:

   curl "$CENTRAL_HUB_URL/api/v1/agents-v2/tools/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG"

2. Create the agent:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Contract analyst",
       "description": "Answers questions about contracts",
       "system_prompt": "You are a careful contract analyst. Cite the source file for every conclusion.",
       "model_config_id": 12,
       "tool_names": ["web-search", "semantic_search_tool"],
       "enabled_skill_slugs": ["contract-review"],
       "enabled_connection_ids": [42],
       "enabled_mcp_connection_ids": [7],
       "enabled_file_scope": {"file_ids": [], "folder_ids": ["<alo-files-folder-id>"]}
     }'

3. The response is 201 with the agent: id, a slug made from name (contract-analyst), space_slug and owner_ref, the key owner's email.

4. To change it later, send PATCH /api/v1/agents-v2/agents/{agent_id}/ with only the changed fields; DELETE the same URL removes it.

Upload a skill ZIP

Use a ZIP for a skill that ships scripts or reference files.

1. Put each skill in its own folder: <slug>/SKILL.md plus its files. The folder name becomes the skill's slug; name and description come from the SKILL.md frontmatter.

2. Upload it. Add ?upsert=true to update a workspace skill with the same slug:

   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"

3. The response is 201 with a list of the skills written.

File size and type limits are the same as in a bundle.

Copy a platform skill or prompt template

1. Find its id: platform rows have scope_visibility: "global" in GET /api/v1/agents-v2/skills/?show_platform=true or GET /api/v1/agents-v2/prompt-templates/?show_platform=true.
2. Send POST /api/v1/agents-v2/skills/{skill_id}/fork/ or POST /api/v1/agents-v2/prompt-templates/{template_id}/fork/, with no body.
3. The response is 201 with the workspace copy: scope_visibility: "space" and the slug with a suffix, such as skill-pharma-regulatory-c3d7e21d.

Export an agent bundle

1. Download the ZIP:

   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

2. The export leaves out connection IDs, MCP connection IDs and the file scope; add them to agent.yaml before uploading to another workspace. Only workspace skills are embedded; platform skills stay as slugs.

Troubleshooting