Agent definition (`<name>.agent.yaml`)

<name>.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	`<folderName>.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)

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

my-agent.agent.yaml

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 or agents reference in the Cognite Toolkit 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:

- type: askDocument
  name: Document Search
  description: Search for information in documents.

Tools may also include instructions and a configuration object. Example knowledge-graph tool:

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.

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.

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	`<folderName>.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/<module>/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 and YAML reference library: Agents.

Building Atlas AI agents with the Cognite CLI: step-by-step guide to scaffold, push, evaluate, and publish an Atlas AI agent.
Agent evaluation cases: eval/eval.yaml schema (CLI-only; not part of the Cognite Toolkit agent resources).
Command reference: agents subcommands.

Develop

SDKs and toolkits

Agent definition (`<name>.agent.yaml`)

Example

Fields

Tools

Skills

Cognite Toolkit compatibility

​Example

​Fields

​Tools

​Skills

​Cognite Toolkit compatibility

​Related information

Example

Fields

Tools

Skills

Cognite Toolkit compatibility

Related information