Agents

Agents are packaged AI workers with their own persona, preloaded skills, model selection, and tool restrictions. Create one to build a specialized assistant you can deploy to a thread, trigger on a schedule, or invoke by @mention in any conversation.

What an agent carries

Every agent definition stores four things that the worker applies on every run:

Field	Role
`system_prompt`	The agent's persona. Injected as the system message on every run — before any user content, skills, or context.
`default_skill_slugs`	Preloaded skills. Each slug is resolved and merged into the run context on every execution, the same way a user-selected skill would be.
`config.model`	Model override. When present, the agent runs on this model family slug (e.g. `"claude-opus"`) instead of the organization default.
`config.tools`	Tool allowlist. Omit to allow all tools the run context makes available. A non-empty array restricts the agent to exactly those tools. An empty array allows no tools.

The config field

The config field is a JSON object stored alongside the agent. Two keys are recognized by the worker at runtime:

{
  "model": "claude-opus",
  "tools": ["web_search", "calculator"]
}

Both keys are optional. Omitting model falls back to the organization's default model selection. tools controls which tools the agent may call: omit the key entirely to allow all tools the run context provides, pass a non-empty array to restrict the agent to exactly those tools, or pass an empty array to allow no tools at all.

Additional keys in config are stored as-is and ignored by the runtime; you can use them for application-level metadata.

@mentioning an agent

Prefixing a user message with @agent-name routes that conversation turn through the named agent instead of the default assistant. The worker:

Looks up the agent by display name within the organization.
Applies the agent's system_prompt, default_skill_slugs, config.model, and config.tools for that turn.
Attributes the reply to the agent, not to the default assistant, so the thread clearly shows which agent responded.

@mention routing applies to a single turn. The next message in the thread returns to the default assistant unless it also carries an @mention.

Creating an agent

Use POST /v1/agents with at minimum a name and a system_prompt. Supply config and default_skill_slugs to control the model and skills the agent preloads.

curl https://api.cortex.cognit-dx.com/v1/agents \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Research assistant",
    "system_prompt": "You are a rigorous research assistant. Cite sources.",
    "default_skill_slugs": ["web-search"],
    "config": {
      "model": "claude-opus",
      "tools": ["web_search"]
    }
  }'

The full endpoint reference — including update, archive, and run endpoints — is in the Automation section.