create_agent

Create a stored Agent definition by its caller-relative name. A standalone personal credential uses a bare name. In organization scope, use me/name for the represented member's private space or <team>/name for a bound team. An unprefixed organization-scoped name denotes the shared organization catalogue, which is currently read-only over MCP. This defines reusable identity and behavior—it does not start, assign, or execute an agent.

Parameters

Parameter	Type	Required	Description
name	string	Yes	Caller-relative address: bare with a standalone personal credential, me/name in private organization space, or <team>/name for a bound team.
description	string	No	Human-readable description. Defaults to empty.
definition	object	Yes	Complete identity and behavior definition stored as version 1.
version_limit_policy	string	No	reject (default) or prune_oldest when a later update reaches the retained-version limit.

The definition contains:

Field	Type	Required	Description
identity	string	Yes	Core role and identity instructions.
categories	object[]	No	Ordered categories; each has required key and name, plus optional description.
components	object[]	No	Ordered behavior components.
components[].key	string	Yes	Stable lowercase key beginning with a letter.
components[].category_key	string	Yes	Key of a category in the same definition.
components[].name	string	Yes	Human-readable component name.
components[].description	string	No	Optional explanation.
components[].applicability	string	Yes	always or conditional.
components[].load_when	string	Conditional	Required for conditional; omit for always.
components[].instructions	string	Yes	Instructions contributed when the component is active.

Response

Field	Type	Description
id	string	Stable internal definition identifier, returned as metadata.
name	string	Canonical caller-relative address of the created Agent definition.
active_version	integer	The initial active version (1).

Example

{
	"name": "engineering/reviewer",
	"description": "Reviews risky changes",
	"definition": {
		"identity": "You are a careful code reviewer.",
		"categories": [{ "key": "quality", "name": "Quality" }],
		"components": [
			{
				"key": "evidence",
				"category_key": "quality",
				"name": "Evidence",
				"applicability": "always",
				"instructions": "Cite concrete code before reporting a defect."
			}
		]
	}
}

Result:

{
	"id": "018f...c2a1",
	"name": "engineering/reviewer",
	"active_version": 1
}

Errors

Domain and authorization failures are tool results with isError: true; malformed arguments and server faults are JSON-RPC protocol errors.

Code	Cause
agent_name_taken	That name already exists in the target ownership space.
invalid_agent_name	The bare Agent name is invalid.
empty_name	The name is empty after removing the team prefix.
agent_required_field	A required definition field is empty.
agent_field_too_long	A definition or metadata field exceeds its limit.
too_many_agent_items	The definition contains too many categories or components.
agent_definition_too_large	The complete definition exceeds its total-size limit.
invalid_agent_key / duplicate_agent_key	A category or component key is invalid or repeated.
agent_missing_category	A component references a category that is absent.
agent_always_has_load_when	An always-on component supplied load_when.
agent_conditional_missing_load_when	A conditional component omitted load_when.
invalid_version_policy	The version policy is not reject or prune_oldest.
agent_limit_reached	The target space has reached its plan's Agent limit.
forbidden	The credential lacks create authority, uses me/ outside organization scope, or targets the read-only organization catalogue.
team_not_found	No team with that prefix is bound to this credential.
personal_cannot_address_team	A standalone personal credential used a Team prefix.
no_personal_space	A userless organization credential used me/name.
invalid_arguments	Input is missing or does not match the schema.
internal_error	An unexpected server error occurred.

Notes

• The tool is governed: it requires Tools and tool-policy admission. A standalone personal target additionally requires its Agent-create permission; a Team target requires a binding and the matching Team permission; me/name requires an acting user with active organization membership. It does not require Agents merely to write the definition.
• Creating a definition does not assign it to the current credential. Assignment remains a deliberate dashboard action.
• Organization-catalog definitions cannot be created over MCP. In organization scope, create privately with me/name or use a bound team; publish through the dashboard.