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):

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

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

1. Confirm agent.yaml, README.md, and eval/cases.yaml were all created
2. 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