> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.middesk.com/work-with-agents/run-agents/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server.

# Run agents

> Run verification workflows that acquire data, reason across sources, and deliver decisions.

Agents acquire data, reason across sources, and deliver decisions. They close the loop between a Middesk report surfacing a signal and that signal being resolved.

A standard Middesk report might surface an unknown tax ID number (TIN) or a potential watchlist hit. Upon review, you must investigate each signal: pull documents, cross-reference sources, and determine the validity of a match. Working with an agent, you can delegate the work of reading the report, extracting the signals, and gathering the information necessary to move forward. An agent can manage a team of agents to take the steps necessary to resolve each signal, so that your work shifts from investigation to reviewing the outcome and making a decision.

## Understanding agents

Agents plan, research, and reason to advance operational workflows.

<title id="md-agenttypes-title">
  Agent Types
</title>

<desc id="md-agenttypes-desc">
  Orchestrators handle planning, judgment, and reasoning.
  Specialists handle discovery, analysis, and interpretation,
  with access to tools including Middesk data, business entity graph,
  and 3rd party services.
</desc>

<defs>
  <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--md-violet)" />

  <filter id="md-card-shadow-at" x="-6%" y="-6%" width="116%" height="120%" />
</defs>

<g transform="translate(20, 16)" filter="url(#md-card-shadow-at)">
  <rect width="260" height="228" rx="10" />

  <text x="20" y="36">
    Orchestrators
  </text>

  <text x="20" y="62">
    Planning, judgment,
  </text>

  <text x="20" y="78">
    and reasoning
  </text>
</g>

<g transform="translate(360, 16)" filter="url(#md-card-shadow-at)">
  <rect width="260" height="228" rx="10" />

  <text x="20" y="36">
    Specialists
  </text>

  <text x="20" y="62">
    Discovery, analysis,
  </text>

  <text x="20" y="78">
    and interpretation
  </text>
</g>

<g transform="translate(380, 120)">
  <rect width="220" height="108" rx="8" />

  <text x="16" y="30">
    Tools
  </text>

  <text x="16" y="54">
    Middesk data, business entity
  </text>

  <text x="16" y="70">
    graph, and 3rd party services
  </text>
</g>

Agents can delegate work to other agents, and on the Middesk platform are classified as two types:

* **Orchestrators** handle planning, coordination, and synthesis. They determine what work is needed, dispatch agents, and aggregate results to drive action.
* **Specialists** perform research, analysis, and tool calls within a specific domain.

Which agents are fit to run depends on the use case and nature of the operation.

## Executing agents

> **Info**
>
> For details on available and forthcoming agents in the library, reach out to your account manager or [contact sales](https://www.middesk.com/contact-sales).

You interact with agents through the following primitives:

* **Agent** is a defined set of capabilities. You can [list available Agents](/api-reference/agents/agents/list-agents) for your account via the API. See the [Agent reference](/reference/agent).
* **Thread** is a container to hold context and history for agent work. Threads are commonly associated with a specific context, for example, a `business_id`. See the [Thread reference](/reference/thread).
* **Run** is an individual execution of an agent within a thread. See the [Run reference](/reference/run).

Agent run · end-to-end

How an agent executes a run

<title id="md-agent-title">
  Agent Run Lifecycle
</title>

<desc id="md-agent-desc">
  A user verifies a business, reviews results, then runs an agent.
  The agent plans and executes, interrupts the user with results,
  and after the user takes action, resumes to update the business.
</desc>

<defs>
  <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--md-sky)" />

  <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--md-violet)" />

  <filter id="md-card-shadow" x="-6%" y="-6%" width="116%" height="120%" />
</defs>

<rect x="30" y="0" width="220" height="680" rx="12" />

<rect x="390" y="0" width="220" height="680" rx="12" />

<g transform="translate(40, 20)" filter="url(#md-card-shadow)">
  <rect width="200" height="40" rx="6" />

  User
</g>

<g transform="translate(400, 20)" filter="url(#md-card-shadow)">
  <rect width="200" height="40" rx="6" />

  Agent
</g>

<g transform="translate(40, 100)" filter="url(#md-card-shadow)">
  <rect width="200" height="68" rx="10" />

  <text x="20" y="22">
    Client
  </text>

  <text x="20" y="48">
    Verify a Business
  </text>
</g>

<g filter="url(#md-card-shadow)">
  <polygon points="140,200 186,240 140,280 94,240" />
</g>

Review?

<g transform="translate(40, 320)" filter="url(#md-card-shadow)">
  <rect width="200" height="68" rx="10" />

  <text x="20" y="22">
    Client
  </text>

  <text x="20" y="48">
    Run an Agent
  </text>
</g>

<rect x="255" y="344" width="130" height="20" rx="4" />

Creates agent run

<g transform="translate(400, 320)" filter="url(#md-card-shadow)">
  <rect width="200" height="68" rx="10" />

  <text x="20" y="22">
    Agent
  </text>

  <text x="20" y="48">
    Plan
  </text>
</g>

<g transform="translate(400, 440)" filter="url(#md-card-shadow)">
  <rect width="200" height="68" rx="10" />

  <text x="20" y="22">
    Agent
  </text>

  <text x="20" y="48">
    Execute
  </text>
</g>

<rect x="260" y="452" width="120" height="44" rx="4" />

Interrupts with

results

<g transform="translate(40, 440)" filter="url(#md-card-shadow)">
  <rect width="200" height="68" rx="10" />

  <text x="20" y="22">
    Client
  </text>

  <text x="20" y="48">
    Take Action
  </text>
</g>

<rect x="255" y="592" width="130" height="20" rx="4" />

Resumes agent run

<g transform="translate(400, 572)" filter="url(#md-card-shadow)">
  <rect width="200" height="68" rx="10" />

  <text x="20" y="22">
    Agent
  </text>

  <text x="20" y="48">
    Update a Business
  </text>
</g>

The above example demonstrates an end-to-end workflow:

#### Verify a business

Use the [Business Lifecycle](/lifecycle-of-business) to initiate and advance the business verification process. For more details, see [Verify a business](/verify-business).

#### Run an agent

Next, when the business verification order completes, a Business may need review depending on its [review insights](/review-insights). From here, an agent can be dispatched to develop a plan and perform the review.

> **Info**
>
> If you use a Middesk policy or a similar rule-based system, you can automatically trigger an agent to run. Accounts with the CIP, CDD, or EDD orchestrator agents include matching default trigger policies. Enable them, or configure your own [Policy](/use-rulesets-policies) to run the agents you choose.

#### Take action

Once its work is complete, the agent returns a structured response for your team. Based on subsequent input or feedback, the agent can then close the loop and complete the review. For more details, see [Take action](/work-with-agents/take-action).

## Integrating agent runs

Agent runs are asynchronous, so most integrations react to webhooks rather than polling. The typical loop is:

1. An agent run starts from the Dashboard, through the [Create an agent run API](/api-reference/agents/runs/create-agent-run), or from a [Policy](/use-rulesets-policies) action when a business enters review.
2. When the run proposes changes, it pauses for review by default. An [interrupt policy](/work-with-agents/interrupt-policy) of `auto_approve` or `skip` lets the run proceed without pausing. Reviews happen in your own system or in the Middesk Dashboard.
3. Each time a review is resolved, Middesk records the result so you can [review the work](/work-with-agents/review-work), and sends `business.updated` so your system can refresh the Business. When the run finishes, `run.completed` fires.

For choosing events by review model and payload examples, see [Agent webhook events](/work-with-agents/webhooks). For general webhook setup, see [Implement webhooks](/build/webhooks).

## Viewing agent activity

As an agent performs a run, it maintains a full record of what it performed and what it found, captured through steps and artifacts. This provides a complete audit trail of the agent's work.

**Steps** represent the trail of work the agent performed. Each step captures an individual action, such as researching a data source, analyzing a result, or requesting your input. Steps can be nested, reflecting how an orchestrator delegates to specialists.

**Artifacts** represent what the agent found. Each artifact is a structured result that includes a confidence score and source references, tracing the finding back to the specific data that informed it.

Together, steps and artifacts give you the context to understand how the agent reached its conclusion and the evidence behind it. For the full response structure, see the [Run reference](/reference/run).

> **Get a demo**
>
> Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.

> Run verification workflows that acquire data, reason across sources, and deliver decisions.