Building agents - Cognite Docs

Build Atlas AI agents that solve business problems and automate workflows. Use the Cognite CLI for a file-based workflow you can version in Git, review in pull requests, and reuse across projects. You can also build in the low-code Agent builder in Cognite Data Fusion (CDF). Both paths produce agents you can publish to the Agent library for your CDF project.

Before you start

Complete these steps before building your agent.

Define your agent’s scope. Each agent should handle one specific workflow or question type, such as equipment fault diagnosis, work order triage, or document Q&A.
Identify an evaluation dataset. Gather 10 to 20 representative questions your users will ask, along with the answers you would consider correct, to use as test cases after building.
Choose a language model. Select the language model that fits your agent’s task complexity. See About language models for guidance.

Choose how to build

Build with the Cognite CLI or the Agent builder in Cognite Data Fusion (CDF).

Cognite CLI (recommended)
Agent builder in CDF

Use @cognite/cli to scaffold an agent project (<name>.agent.yaml, evaluation cases, and coding-assistant guidance), push drafts to CDF, run evaluations, and publish. Follow the guide linked below.

Requires @cognite/cli 1.10.0 or later.

Use the low-code Agent builder in CDF for interactive configuration.

Navigate to Agent builder

In CDF, navigate to Atlas AI > Agent builder.Select + Create agent or select a template to use as a starting point.

Configure basic information

Enter a Name that clearly describes the agent’s purpose.Write a Description that explains what problems the agent solves or tasks it automates.Add Sample prompts that show users how to interact with the agent. Make these specific and representative of real use cases.

Set up prompting

Select the Language model you identified earlier.Write Instructions that define the agent’s behavior for every interaction. Effective instructions cover four elements.

Scope and identity
Universal rules
Output format
Boundaries

Define what the agent is for and what requests it should decline.

You are a maintenance assistant for rotating equipment. You help engineers diagnose faults, review work order history, and retrieve sensor data. You do not provide recommendations on staffing or procurement.

Keep instructions focused on universal behavior. Workflow-specific guidance, vocabulary mappings, and tool sequencing belong in skills, which the agent loads on demand when relevant.

Configure skills

Skills give the agent domain-specific knowledge for specific workflows. Use a separate skill for each distinct workflow or dataset so the agent loads only what is relevant to the current question.

In the Agent builder, select Skills, then + Add skill.
Use the skill builder to generate a skill from an existing document such as an SOP, engineering specification, or naming convention guide. Review and adjust the generated draft before saving. You can also write skills manually.
Attach the skill to your agent and test with questions that should trigger it.

For guidance on structuring skills, see Configuring skills for agents.

Configure tools

Add Tools to let the agent access CDF data, perform calculations, or interact with other applications.

Start with the Query tool. The Query tool works across your entire data model without requiring separate configuration per view.
Enable only the tools your agent needs. Each additional tool increases the chance the agent selects the wrong one.
Document tool combinations in skills. When a question requires more than one tool, add sequencing instructions to the relevant skill rather than relying on the agent to infer the order. See Configuring skills for agents for examples.

For the data retrieval tools, specify which access scope to use.

Option	What it does
Inherit scope from the user’s location	Uses the location configured in CDF to determine which data to find.
Inherit scope based on user’s access rights	Finds data without filtering on spaces.
Follow access scope defined manually	Limits the query to the spaces you select.

Agent actions inherit CDF access controls. The agent can only access data the user has permission to view.

Configure subagents

Optionally add subagents (Preview) so this agent can delegate tasks to other specialized agents. Add them from the Subagents section in the Agent builder. Requires runtime version 1.3.0 or later.

Test and refine

Test the agent in Atlas AI. Refine the language model, instructions, tools, and skills as needed.Test with questions that cover a range of scenarios.

Typical questions your users will ask
Questions that involve multiple tools or data types
Edge cases, such as equipment that does not exist or questions outside the agent’s scope
Follow-up questions that build on a previous response

When a response is unexpected, expand the reasoning field and tool call logs to see what the agent did. See Debugging and tracing agents for guidance on reading traces.

Evaluate

Run the test cases you gathered before you started. Use Running agent evaluations in CDF, or Agent evaluation cases if you want a file-based suite in Git.

Publish

Select Publish to make the agent available in the Agent library to everyone in your CDF project.

Monitor and iterate

Monitor the agent’s performance and update its skills, instructions, and tools based on user feedback and usage patterns. Re-run your evaluation test cases after any configuration change to confirm that existing behavior is not affected.

​Before you start

​Choose how to build

​Related information

Before you start

Choose how to build

Related information