Agents

An agent is a named specialist: a prompt, a description and, optionally, its own model. Agents run as workflow steps, and each step or later turn receives its own agent’s settings.

Layout

• Directoryagents/

  • Directorydata-analyst/

    • AGENT.md
    • tools.json
    • test_cases.json

tools.json and test_cases.json are optional. If present they must be valid JSON and are kept as read-only companion files. They do not enable custom tool implementations and Cengrid does not execute evaluations from them.

AGENT.md

agents/data-analyst/AGENT.md

---
name: data-analyst
description: Generate SQL and analyze datasets.
model:
  provider: anthropic
  name: claude-sonnet-5
---

# Role and identity

You are an expert data analyst.

# Rules

Never run destructive SQL commands.

Field	Required	Meaning
name	No	Defaults to the directory name. Lowercase letters, digits, hyphen or underscore, starting with a letter or digit, up to 64 characters. Cengrid lower-cases it before validating.
description	Yes	Up to 400 characters.
Body	Yes	The agent’s instructions, up to 8,000 characters.
model.provider and model.name	Yes in a root plugin.json plugin	The model, which must resolve to a model your deployment supports and match the provider.
model.temperature, model.max_tokens	No	Generation settings, checked against what the provider’s metadata says the model supports. Temperature is rejected for reasoning models and where support cannot be verified, which includes Claude Opus 5 and GPT-5.6 Sol, so most agents omit it. A max_tokens too small for a reasoning model’s thinking budget is rejected.
model: inherit	Console and deployment-layer agents	Run on the conversation’s own model, whatever it is when the agent runs. Takes no other settings. Plugin agents in a legacy .codex-plugin or .claude-plugin manifest may also use it, or omit the model.

A plain string model name still works for existing agents. How model settings are validated, and why a short alias such as sonnet rejects the whole plugin, is covered in agent models.

Settings such as tools, disallowedTools, permissionMode, hooks, mcpServers and isolation are not supported and mark the agent unavailable.

Built-in agents

Two agents are built in: __planner__ and __default__. They have no model, so they run on the conversation’s model, and they are always on.

• __default__ is a general assistant with every work tool, so a workflow step always has an agent to run on.
• __planner__ plans work and is not offered as a step agent.

Customise on a built-in opens the editor prefilled with model: inherit and saves a stored agent of that name in the selected scope, which replaces the built-in there. The organisation and a team can each customise one, and the team’s definition adds to the organisation’s. A plugin cannot ship either name; a deployment layer can, with agents/__planner__/AGENT.md or agents/__default__/AGENT.md.

Deployment-layer agents

A deployment directory can seed agents at the organisation from its agents/ directory: one AGENT.md per folder, with the model and description in frontmatter and the instructions in the body. They are reseeded on every boot and edited per scope through the admin API afterwards.

Who can create agents

Organisation administrators create, edit and delete organisation and team agents in the console. Imported agents are read-only. Inspect a plugin agent to see its instructions, model configuration, companion files and GitHub source link.