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

> Create custom Atlas AI agents using the low-code Agent builder to solve business problems and automate workflows.

Use the low-code **Agent builder** to create Atlas AI agents that solve business problems and automate workflows. Create a blank agent or use a template.

Test your agent in the Agent builder, then publish it to the **Agent library** to make it available across your CDF project.

## Before you start

Complete these steps before building your agent.

1. **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.

2. **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.

3. **Choose a language model.** Select the [language model](/cdf/atlas_ai/references/atlas_ai_agent_language_models) that fits your agent's task complexity. See [About language models](/cdf/atlas_ai/concepts/atlas_ai_agent_choosing_lm) for guidance.

## Build and publish an agent

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Set up prompting">
    Select the [**Language model**](/cdf/atlas_ai/references/atlas_ai_agent_language_models) you identified earlier.

    Write **Instructions** that define the agent's behavior for every interaction. Effective instructions cover four elements.

    <Tabs>
      <Tab title="Scope and identity">
        Define what the agent is for and what requests it should decline.

        <Prompt description="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." actions={["copy"]}>
          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.
        </Prompt>
      </Tab>

      <Tab title="Universal rules">
        Write rules that apply to every interaction, regardless of what the user asks.

        <Prompt description="If the data is incomplete or ambiguous, say so explicitly rather than making assumptions. State your assumptions when more than one interpretation is possible." actions={["copy"]}>
          If the data is incomplete or ambiguous, say so explicitly rather than making assumptions. State your assumptions when more than one interpretation is possible.
        </Prompt>
      </Tab>

      <Tab title="Output format">
        Describe what a complete, well-formed response should include.

        <Prompt description="When listing work orders, always include the work order ID, description, priority, status, and planned start date." actions={["copy"]}>
          When listing work orders, always include the work order ID, description, priority, status, and planned start date.
        </Prompt>
      </Tab>

      <Tab title="Boundaries">
        State what the agent must not do without explicit confirmation from the user.

        <Prompt description="Do not create or modify work orders. Do not recommend specific maintenance actions. Present findings and let the engineer decide." actions={["copy"]}>
          Do not create or modify work orders. Do not recommend specific maintenance actions. Present findings and let the engineer decide.
        </Prompt>
      </Tab>
    </Tabs>

    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.
  </Step>

  <Step title="Configure skills">
    [Skills](/cdf/atlas_ai/concepts/atlas_ai_agent_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.

    1. In the Agent builder, select **Skills**, then **+ Add skill**.
    2. 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.
    3. Attach the skill to your agent and test with questions that should trigger it.

    For guidance on structuring skills, see [Configuring skills for agents](/cdf/atlas_ai/guides/atlas_ai_agent_configure_skills).
  </Step>

  <Step title="Configure tools">
    Add [**Tools**](/cdf/atlas_ai/references/atlas_ai_agent_tools) to let the agent access CDF data, perform calculations, or interact with other applications.

    * **Start with the Query tool.** The [Query tool](/cdf/atlas_ai/references/atlas_ai_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](/cdf/atlas_ai/guides/atlas_ai_agent_configure_skills) 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](/cdf/locations) configured in CDF to determine which data to find.      |
    | Inherit scope based on user's access rights | Finds data without filtering on [spaces](/cdf/dm/dm_concepts/dm_spaces_instances#space).    |
    | Follow access scope defined manually        | Limits the query to the [spaces](/cdf/dm/dm_concepts/dm_spaces_instances#space) you select. |

    <Note>
      Agent actions inherit CDF access controls. The agent can only access data the user has permission to view.
    </Note>
  </Step>

  <Step title="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](/cdf/atlas_ai/concepts/atlas_ai_agent_debugging) for guidance on reading traces.
  </Step>

  <Step title="Evaluate">
    Run your evaluation test cases to verify the agent's responses before publishing.

    See [Running agent evaluations](/cdf/atlas_ai/guides/atlas_ai_agent_evaluating) for the step-by-step walkthrough.
  </Step>

  <Step title="Publish">
    Select **Publish** to make the agent available in the **Agent library** to everyone in your CDF project.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Related information

* [About Atlas AI agents](/cdf/atlas_ai/concepts)
* [About Atlas AI agent skills](/cdf/atlas_ai/concepts/atlas_ai_agent_skills)
* [Configuring skills for agents](/cdf/atlas_ai/guides/atlas_ai_agent_configure_skills)
* [About language models](/cdf/atlas_ai/concepts/atlas_ai_agent_choosing_lm)
* [Running agent evaluations](/cdf/atlas_ai/guides/atlas_ai_agent_evaluating)
* [Debugging and tracing agents](/cdf/atlas_ai/concepts/atlas_ai_agent_debugging)
* [Agent tools library](/cdf/atlas_ai/references/atlas_ai_agent_tools)