> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognite.com/llms.txt > Use this file to discover all available pages before exploring further. # Agent definition (`.agent.yaml`) > Complete field reference for .agent.yaml, the Atlas AI agent definition used by the Cognite CLI and compatible with the Cognite Toolkit. `.agent.yaml` is the agent definition for the Cognite CLI (`cognite agents create`, `push`, `publish`, and related commands). `create` and `pull` name the file after the project folder, for example, `my-agent/my-agent.agent.yaml`. The YAML shape matches agent resources in the Cognite Toolkit. The Cognite Toolkit treats the resource type as case-insensitive, so the same file works with `cognite agents` and `cdf build` / `cdf deploy`. | Workflow | File / location | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Cognite CLI | `.agent.yaml` in the agent project root (one agent per directory) | | The Cognite Toolkit | `agents/*.Agent.yaml` in a module (resource type is case-insensitive; see [YAML reference library](/cdf/deploy/cdf_toolkit/references/resource_library#agents)) | The CLI also resolves a lone `*.agent.yaml` in the folder (any prefix, including PascalCase `.Agent.yaml` from the Cognite Toolkit). Several matching files with none named after the folder is an error. ## Example ```yaml title="my-agent.agent.yaml" theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} externalId: my_agent name: My Agent description: This is my agent instructions: Follow these instructions when helping the user. model: azure/gpt-4o-mini tools: - type: askDocument name: Document Search description: Search for information in documents. skills: - my_skill ``` The `externalId` inside the file is the Cognite Data Fusion (CDF) identity. It does not have to match the folder or filename. ## Fields | Field | Required | Description | | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `externalId` | Yes | Unique agent identifier in the project. | | `name` | Yes | Display name. | | `description` | No | Short description shown in CDF. | | `instructions` | No | Agent instructions (editable custom behavior). The platform may also apply built-in guidance that is not set in this file. | | `model` | No | Language model id (for example `azure/gpt-4o-mini`). | | `runtimeVersion` | No | Agent runtime version when you need a specific runtime. | | `labels` | No | String labels (for example `published` after `agents publish`). | | `exampleQuestions` | No | Array of `{ question: string }` starters for the UI. | | `skills` | No | Skill `externalId` values to attach. Deploy skills before the agent that references them. | | `subagents` | No | Array of `{ agentExternalId: string }` for subagent routing. | | `tools` | No | Tool definitions. Defaults to an empty list when omitted. | ## Tools Atlas AI tools evolve quickly. The Cognite Toolkit warns on unknown tool types at `cdf build` but still deploys tools the CDF API accepts. The CLI passes tool configuration through to the Agents API. Common tool types (illustrative; see the [Agent builder](/cdf/atlas_ai/guides/atlas_ai_agent_building) or [agents reference in the Cognite Toolkit](/cdf/deploy/cdf_toolkit/references/resource_library#available-tools) for the latest list): | `type` | Purpose | | ------------------------------------------ | ------------------------------------------------ | | `askDocument` | Ask questions about documents | | `summarizeDocument` | Summarize documents | | `queryKnowledgeGraph` | Natural-language queries against CDF data models | | `queryTimeSeriesDatapoints` | Fetch time series data points | | `query` | Structured queries against data models | | `callFunction` | Call a Cognite Function | | `callRestApi` | Call an external REST API | | `runPythonCode` | Run Python in a sandbox | | `analyzeTimeSeries` / `timeSeriesAnalysis` | Time series analysis | Each tool entry needs at least: ```yaml theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} - type: askDocument name: Document Search description: Search for information in documents. ``` Tools may also include `instructions` and a `configuration` object. Example knowledge-graph tool: ```yaml theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} tools: - name: find_assets type: queryKnowledgeGraph description: Find assets and related instances in the knowledge graph. configuration: version: v2 dataModels: - space: cdf_cdm externalId: CogniteCore version: v1 viewExternalIds: - CogniteAsset instanceSpaces: type: all ``` For additional tool fragments (`summarizeDocument`, `queryTimeSeriesDatapoints`, and more), see the [agents section in the Cognite Toolkit](/cdf/deploy/cdf_toolkit/references/resource_library#available-tools). ## Skills List skill `externalId` values under `skills`. With the Cognite Toolkit, define skills as `*.Skill.yaml` resources under `agents/` (requires the Cognite Toolkit `agent-skills` alpha flag). See [Agent skills in the YAML reference library](/cdf/deploy/cdf_toolkit/references/resource_library#agent-skills). ## Cognite Toolkit compatibility The same YAML works in the Cognite CLI and the Cognite Toolkit. Differences are location and how many agent files you can keep together. | Aspect | Cognite CLI | The Cognite Toolkit | | ------------ | -------------------------------------------------------------- | -------------------------------------------------------------------- | | Location | `.agent.yaml` in the agent project root | `agents/` in a module | | Filename | Named after the folder; a lone `*.agent.yaml` is also accepted | Resource type is case-insensitive (`*.agent.yaml` or `*.Agent.yaml`) | | How many | One agent per directory | Several agent files under `modules//agents/` | | Feature flag | Not required | `agents` alpha flag, if required for your version | `eval/eval.yaml` is CLI-only. It is not a Cognite Toolkit agent resource. To add the file to a module and deploy it, see [Configure, build, and deploy modules](/cdf/deploy/cdf_toolkit/guides/usage) and [YAML reference library: Agents](/cdf/deploy/cdf_toolkit/references/resource_library#agents). ## Related information * [Building Atlas AI agents with the Cognite CLI](./agents): step-by-step guide to scaffold, push, evaluate, and publish an Atlas AI agent. * [Agent evaluation cases](./agents-eval): `eval/eval.yaml` schema (CLI-only; not part of the Cognite Toolkit agent resources). * [Command reference](./reference#agents): `agents` subcommands.