create-agent

Create Agent

Scaffold a new Atlas agent project named $ARGUMENTS using npx @cognite/cli@latest agents create.

What gets created

<agent-name>/
  agent.yaml         # Agent definition — externalId, model, instructions, tools
  README.md          # Quick-start docs and tool reference
  eval/
    cases.yaml       # Starter eval cases (single-turn, multi-turn, correctness + faithfulness scorers)

Step 1 — Gather optional fields

The agent name is $ARGUMENTS. Ask the user for the following (skip any they already provided):

Field	CLI flag	Default
Display name	`--display-name`	same as agent name
Description	`--description`	—
Model	`--model`	`azure/gpt-5.4-mini`
Instructions (system prompt)	`--instructions`	see default below
Tools	(edit after creation)	none

Default instructions when the user doesn't specify:

Help users explore and understand the data in this project.
Use the available tools to retrieve data before answering.
When the data is insufficient, say so rather than guessing.

Step 2 — Run `npx @cognite/cli@latest agents create`

Run the command, including only flags where the user provided a value or a non-empty default applies:

npx @cognite/cli@latest agents create <agent-name> \
  --display-name "<display-name>" \
  --description "<description>" \
  --model <model> \
  --instructions "<instructions>" \
  --no-prompt

Omit --display-name if the user wants the default (same as agent name).
Omit --description if none was given.
Always pass --instructions (use the default if the user didn't specify).
Always pass --no-prompt to skip the CLI's interactive prompts.
For multi-line instructions, pass them as-is in quotes; if the shell quoting is awkward, skip --instructions and edit agent.yaml manually after creation.

Step 3 — Add tools (if any)

If the user wants tools, edit <agent-name>/agent.yaml to add a tools array. Do NOT add tools: [] — omit the key entirely when there are no tools.

Available tool types

Type	Purpose
`analyzeData`	Analyze tabular or structured data
`analyzeImage`	Analyze images and P&ID diagrams
`analyzeTimeSeries`	Analyze time series data
`askDocument`	Ask questions about documents
`callFunction`	Call a Cognite Function
`callRestApi`	Call an external REST API
`callWebhook`	POST a payload to an external webhook
`examineDataSemantically`	Semantic data examination
`query`	Structured queries against CDF data models
`queryKnowledgeGraph`	Query CDF data models with natural language
`queryTimeSeriesDatapoints`	Fetch raw or aggregated time series data
`runPythonCode`	Execute custom Python code
`summarizeDocument`	Summarize documents
`timeSeriesAnalysis`	Advanced time series analysis and anomaly detection

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

Step 4 — Verify and summarize

Confirm agent.yaml, README.md, and eval/cases.yaml were all created
Tell the user the next steps:
- Edit <agent-name>/agent.yaml — add tools and refine instructions
- npx @cognite/cli@latest agents push <externalId> — push to CDF for testing
- npx @cognite/cli@latest agents open — open in Fusion
- Edit <agent-name>/eval/cases.yaml and run npx @cognite/cli@latest agents eval <externalId> — the scaffolded cases are placeholders (a correctness case, a faithfulness case, and a multi-turn case); update the inputs, references, and context to match what the agent actually does

Guard rails

Do NOT add tools: [] — omit the key entirely when there are no tools
Do NOT invent tool types not listed above
Agent name must be kebab-case: lowercase letters, digits, and hyphens only
If a directory with the agent name already exists, warn the user and stop