AgentDefinition
The full definition of an agent. The same type is used whether the agent is declared in code or stored in the database; AgentDefinitionOrigin AgentDefinition.Origin tells the two apart.
Shape: object
| Property | Required | Type | Description | Rules |
|---|---|---|---|---|
name |
yes | string |
Gets the unique name of the agent, used as the key in the catalog and in API routes. | — |
displayName |
no | string |
Gets the name shown in the user interface. Name is used when it is empty. |
— |
description |
no | string |
Gets a short description of what the agent does. | — |
instructions |
no | string |
Gets the system instructions passed to the model. | — |
instructionsByCulture |
no | object |
Gets culture-keyed instructions. The key is a BCP-47 tag ("en", "tr"); a region subtag ("tr-TR") falls back to its parent ("tr"). A run’s requested culture that matches neither falls back to Instructions - resolution never fails. |
— |
model |
yes | ModelBinding |
Gets the provider and model binding to use. | — |
toolNames |
no | array of string |
Gets the names of the tools this agent may use. Every name must match a tool registered in code; otherwise building the agent fails. | — |
skillNames |
no | array of string |
Gets the names of the skills this agent may load at run time. Every name must match an enabled skill found in code or in the skill store. | — |
callableAgentNames |
no | array of string |
Gets the names of the other agents this agent may call. | — |
mcpResourceUris |
no | array of string |
Gets the MCP resources added to the run context (mode A). Each item has the form "{server}:{uri}". They are read at the start of the run and are predictable; every run receives the same resources. |
— |
harness |
no | null oneOf HarnessSettings |
— | — |
compaction |
no | null oneOf CompactionSettings |
— | — |
memory |
no | null oneOf MemorySettings |
— | — |
origin |
no | AgentDefinitionOrigin |
Gets the origin of the definition: code or database. | — |
version |
no | integer (int32) |
Gets the definition version. Every save increments this value and so naturally invalidates the compiled agent cache. | pattern `^-?(?:0\ |
tenantId |
no | string |
Gets the tenant this definition belongs to. A single-tenant setup uses the default value. | — |
updatedAt |
no | string (date-time) |
Gets the time the definition last changed (UTC). | — |
metadata |
no | object |
Gets free-form, application-specific metadata. | — |