> ## 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.

# Building Atlas AI agents with the Cognite CLI

> Step-by-step guide to scaffold, push, evaluate, and publish an Atlas AI agent with @cognite/cli.

This guide is for **developers** and **AI engineers** who build [Atlas AI agents](/cdf/atlas_ai) 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.

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

## Prerequisites

* [Node.js](https://nodejs.org) v18 or later
* A CDF project where you can create Atlas AI agents
* Basic familiarity with the terminal

## Build your first agent

<Steps>
  <Step title="Verify the CLI">
    Confirm `@cognite/cli@latest` includes the `agents` command:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npx @cognite/cli@latest --version
    npx @cognite/cli@latest agents --help
    ```

    <Check>
      You see a version of **1.10.0** or later, and `agents` lists subcommands such as `create`, `push`, and `eval`.
    </Check>
  </Step>

  <Step title="Authenticate">
    Sign in so the CLI can call your CDF project. Prefer a persisted session when available:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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](./reference#agents).
  </Step>

  <Step title="Create a new agent project">
    Run the interactive scaffolder:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npx @cognite/cli@latest agents create my-agent \
      --external-id my-agent \
      --display-name "My Agent" \
      --description "Helps with industrial data questions" \
      --no-prompt
    ```

    <Check>
      A new `my-agent` directory exists with `my-agent.agent.yaml`, `eval/eval.yaml`, `README.md`, and `AGENTS.md`.
    </Check>
  </Step>

  <Step title="Push a draft agent">
    From the agent directory, upsert the local `<name>.agent.yaml` to CDF as a draft:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cd my-agent
    npx @cognite/cli@latest agents push
    ```

    <Check>
      The command completes without errors and reports that the agent was pushed.
    </Check>
  </Step>

  <Step title="Open the agent in CDF">
    Open the agent in the Atlas AI Agent builder for interactive testing:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npx @cognite/cli@latest agents open
    ```

    Use `--upsert` to push local changes before opening.
  </Step>

  <Step title="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`):

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npx @cognite/cli@latest agents eval --upsert
    ```

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

    Edit `eval/eval.yaml` to match your agent's behavior. See [Agent evaluation cases](./agents-eval) for scorers and schema details.
  </Step>

  <Step title="Publish the agent">
    When you are ready for users to see the agent:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npx @cognite/cli@latest agents publish
    ```

    Use `agents unpublish` to remove production visibility while keeping the draft.
  </Step>
</Steps>

## 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`)](./agent-yaml): fields and tools (compatible with the Cognite Toolkit).
* [Agent evaluation cases](./agents-eval): scorers, `eval.yaml` schema, and CLI flags.
* [Command reference](./reference#agents): every `agents` subcommand and option.
* [Building agents](/cdf/atlas_ai/guides/atlas_ai_agent_building): UI workflow in CDF.
* [YAML reference library: Agents](/cdf/deploy/cdf_toolkit/references/resource_library#agents): deploy the same agent YAML with the Cognite Toolkit.