---
title: Agent Builder
description: >-
  Build and deploy custom AI agents that automate operational tasks using
  Datadog's tools and integrations.
breadcrumbs: Docs > Actions > Agent Builder
---

# Agent Builder

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ().
{% /alert %}

{% /callout %}

{% callout %}
##### Preview

Agent Builder is in Preview.
{% /callout %}

## Overview{% #overview %}

Agent Builder lets you create custom AI agents that use Datadog's tools and integrations to automate operational tasks. Agents can search logs, query metrics, create cases, send messages, or perform any action from the [Action Catalog](https://docs.datadoghq.com/actions/actions_catalog.md).

Use agents to handle work that's too complex for static automation but too repetitive for humans. For example, triaging errors, responding to incidents, analyzing trends, and escalating issues.

{% image
   source="https://docs.dd-static.net/images/actions/agents/agent-builder-interface.a7d1f23bb07d7485f6813ac6154bb102.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/actions/agents/agent-builder-interface.a7d1f23bb07d7485f6813ac6154bb102.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="The Agent Builder editor showing instructions, model, tools, and automation configuration" /%}

## Create an agent{% #create-an-agent %}

From the [Agent Builder page](https://app.datadoghq.com/actions/agents), click **New Agent**. From there, you can create an agent in three ways:

- **Build with AI**: Describe what you want the agent to do in plain language. Agent Builder generates the instructions, selects relevant tools, and configures the agent for you.
- **Start from a blueprint**: Choose a prebuilt template for common use cases such as error triage, incident response, security analysis, or DevOps assistance. Blueprints come preconfigured with instructions, tools, and automations, and are customizable.
- **Start from scratch**: Configure the agent manually—write instructions, pick a model, and add tools.

{% image
   source="https://docs.dd-static.net/images/actions/agents/empty-state.7ac7aba1b74642c1e89fea89a9626921.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/actions/agents/empty-state.7ac7aba1b74642c1e89fea89a9626921.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="The Agent Builder new agent interface showing a text field and blueprint options" /%}

## Configure your agent{% #configure-your-agent %}

### Instructions{% #instructions %}

Instructions tell the agent what to do when it runs. Write them in natural language—describe the goal, the process, and any constraints. Edit instructions directly or refine them through the chat interface.

Write instructions that are specific and outcome-oriented. For example:

```
You are an Incident Responder AI assistant specialized in managing
and coordinating incident response activities.

Your role involves:
- Guiding incident response procedures and best practices
- Helping assess incident severity and impact
- Coordinating communication between teams and stakeholders
- Managing incident lifecycle from detection to resolution
- Facilitating post-incident reviews and improvements

During incident response:
1. Use search_datadog_logs to pull recent error logs for the affected service
2. Help classify incident severity (P0/P1/P2/etc.)
3. Guide through incident response runbooks and procedures
4. Assist with stakeholder communication and updates
5. Track action items and follow-up tasks
6. Support post-mortem analysis and lessons learned

Focus on clear communication, structured processes, and continuous
improvement of incident response capabilities.
```

### Model{% #model %}

Select which LLM powers the agent's reasoning. Models vary in capability, speed, and cost—choose based on your agent's workload. You can compare models using [OpenAI's comparison tool](https://developers.openai.com/api/docs/models) and [Anthropic's models comparison](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison).

### Tools{% #tools %}

Tools define what actions the agent can take. Add tools from the [Action Catalog](https://docs.datadoghq.com/actions/actions_catalog.md). The agent can only use tools that have been added to its configuration.

Click on any added tool to hardcode its parameters. For example, lock a Slack tool to a specific channel or a logs query to a specific service.

The [Datadog MCP Server](https://docs.datadoghq.com/bits_ai/mcp_server.md) is enabled by default. You can connect to any API using [custom HTTP actions](https://docs.datadoghq.com/actions/actions_catalog/http-action.md).

### Automations{% #automations %}

Set up your agent to run automatically with a [schedule](https://docs.datadoghq.com/actions/workflows/trigger.md#scheduled-triggers), or trigger it from a Datadog [monitor](https://docs.datadoghq.com/actions/workflows/trigger.md#monitor-triggers), [incident](https://docs.datadoghq.com/actions/workflows/trigger.md#incident-triggers), or [security signal](https://docs.datadoghq.com/actions/workflows/trigger.md#security-triggers). These automations use [Workflow Automation](https://app.datadoghq.com/workflow).

## Test your agent{% #test-your-agent %}

Use the built-in chat interface to test your agent. Send messages, review the agent's reasoning, and verify it takes the right actions. Chat history is preserved across sessions.

## Agent orchestration{% #agent-orchestration %}

Use agents in [Workflow Automation](https://app.datadoghq.com/workflow) and [App Builder](https://app.datadoghq.com/app-builder/apps/list) through the **Run Agent** action. This lets you embed AI reasoning into any workflow:

{% image
   source="https://docs.dd-static.net/images/actions/agents/run-agent-step.037b3a9ea211023403c3a092dc384268.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/actions/agents/run-agent-step.037b3a9ea211023403c3a092dc384268.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="The Run Agent step configuration in a workflow, showing agent selection, run instructions, conversation ID, and output schema fields" /%}

1. Open or create a workflow in [Workflow Automation](https://app.datadoghq.com/workflow), or open or create an app in [App Builder](https://app.datadoghq.com/app-builder/apps/list).
1. Add the **Run Agent** step from the action catalog.
1. Select which agent to run.
1. Write the **Run Instructions**—the prompt the agent receives each time it runs. Use variables such as `{{Source.form}}` to pass in trigger data.

The **Run Agent** step also supports the following optional fields:

- **Output Schema**: Define a JSON schema for the agent's response. When set, the agent structures its output to match the schema for use in downstream steps. For example, you can define a schema with a `requestType` field, then branch on `Run Agent.finalResponse.requestType` in an If condition step.

  {% image
     source="https://docs.dd-static.net/images/actions/agents/output-schema-example.9b600a749c2c20fab3d1fa6b05130301.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/actions/agents/output-schema-example.9b600a749c2c20fab3d1fa6b05130301.png?auto=format&fit=max&w=850&dpr=2 2x"
     alt="A workflow using output schema to branch on agent response fields" /%}

- **Conversation ID**: By default, each Run Agent invocation is a standalone, single-turn execution. Passing a Conversation ID lets the agent retain context across multiple workflow runs. Multi-turn sessions are subject to the same context window limits as the chat UI.

The agent executes with its configured tools and instructions, then returns its output to the workflow. You can combine rule-based automation with AI reasoning in a single workflow.

## Troubleshooting{% #troubleshooting %}

**Agent not using a tool**: Verify the tool has been added to the agent's configuration. Agents can use only tools that are explicitly added.

**Automation not running**: Verify the automation is published and the Run Agent step is fully configured.

**Conversation length limit**: Long conversations may reach the context length limit. If this happens, start a new conversation.

**Unexpected configuration changes**: Use [Audit Trail](https://docs.datadoghq.com/account_management/audit_trail.md) filtered to your agent's ID to review the history of changes.

## Further Reading{% #further-reading %}

- [Action Catalog](https://docs.datadoghq.com/actions/actions_catalog.md)
- [Workflow Automation](https://docs.datadoghq.com/actions/workflows.md)
- [What are AI agents and how do they work?](https://www.datadoghq.com/knowledge-center/aiops/ai-agents/)