Building Atlas AI agents with the Cognite CLI

This guide is for developers and AI engineers who build Atlas AI agents and want a local, file-based workflow with @cognite/cli. Following the steps below, you will scaffold an agent project, push a draft to Cognite Data Fusion (CDF), run evaluation cases, and publish the agent for users.

Requires @cognite/cli 1.10.0 or later. Use npx @cognite/cli@latest so you pick up the agents command group.

Prerequisites

Node.js v18 or later
A CDF project where you can create Atlas AI agents
Basic familiarity with the terminal

Build your first agent

Verify the CLI

Confirm @cognite/cli@latest includes the agents command:

npx @cognite/cli@latest --version
npx @cognite/cli@latest agents --help

You see a version of 1.10.0 or later, and agents lists subcommands such as create, push, and eval.

Authenticate

npx @cognite/cli@latest auth login

Alternatively, pass browser auth on each command with --interactive, --base-url, --project, and optionally --org. See the command reference.

Create a new agent project

Run the interactive scaffolder:

npx @cognite/cli@latest agents create my-agent

You are prompted for display name, description, model, and related fields.For scripts or CI, pass flags instead of prompts:

npx @cognite/cli@latest agents create my-agent \
  --external-id my-agent \
  --display-name "My Agent" \
  --description "Helps with industrial data questions" \
  --no-prompt

A new my-agent directory exists with my-agent.agent.yaml, eval/eval.yaml, README.md, and AGENTS.md.

Push a draft agent

From the agent directory, upsert the local <name>.agent.yaml to CDF as a draft:

cd my-agent
npx @cognite/cli@latest agents push

The command completes without errors and reports that the agent was pushed.

Open the agent in CDF

Open the agent in the Atlas AI Agent builder for interactive testing:

npx @cognite/cli@latest agents open

Use --upsert to push local changes before opening.

Run evaluation cases

The scaffold includes starter cases in eval/eval.yaml. cognite agents eval runs against the deployed agent, so push first (or use --upsert):

npx @cognite/cli@latest agents eval --upsert

The run prints per-case results and ends with N/N cases met expectations (or reports failures to fix).

Edit eval/eval.yaml to match your agent’s behavior. See Agent evaluation cases for scorers and schema details.

Publish the agent

When you are ready for users to see the agent:

npx @cognite/cli@latest agents publish

Use agents unpublish to remove production visibility while keeping the draft.

Project layout

Path	Purpose
`<name>.agent.yaml`	Agent definition: identity, model, instructions, tools, skills. Named after the project folder, for example, `my-agent.agent.yaml`.
`eval/eval.yaml`	Evaluation suite: cases and scorers for `cognite agents eval`
`README.md`	Project quick start (generated)
`AGENTS.md`	Guidance for coding assistants working in this project

Next steps

Agent definition (<name>.agent.yaml): fields and tools (compatible with the Cognite Toolkit).
Agent evaluation cases: scorers, eval.yaml schema, and CLI flags.
Command reference: every agents subcommand and option.
Building agents: UI workflow in CDF.
YAML reference library: Agents: deploy the same agent YAML with the Cognite Toolkit.

Develop

SDKs and toolkits

Building Atlas AI agents with the Cognite CLI

Prerequisites

Build your first agent

Project layout

Next steps

​Prerequisites

​Build your first agent

​Project layout

​Next steps

Prerequisites

Build your first agent

Project layout

Next steps