> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Nanonets Health Agent Runs

> Report an agent run and its items to a Nanonets Health custom-agent dashboard.

These three tools let an agent that runs here record its run on a Nanonets Health custom agent, so that agent's dashboard in Nanonets Health shows the run and each item's outcome. They are for agents migrated from Nanonets Health custom agents.

## Authentication and enablement

The tools use the Nanonets Health integration. The platform injects `api_key`. That key is never part of the model-visible schema, and it scopes every call to the connected Nanonets Health organization. All three tools are disabled by default.

Every tool takes `agent_id`, the Nanonets Health custom-agent id (UUID) whose dashboard the run belongs to. Put it in the agent's instructions; it cannot be discovered.

## Flow

1. Call `nanonetshealth_start_agent_run` once at the start of the run and keep its `run_log_id`.
2. Call `nanonetshealth_report_agent_item` once for every item, including skips and failures.
3. Call `nanonetshealth_complete_agent_run` once, after the last item.

All three are **writes** to the Nanonets Health database.

## `nanonetshealth_start_agent_run`

Inputs:

* `agent_id` (required)
* `external_run_id`: optional. This platform's own run or task id, recorded on the run log for cross-reference.

Output:

```json theme={null}
{ "run_log_id": "…", "workflow_id": "…" }
```

## `nanonetshealth_report_agent_item`

Inputs:

* `agent_id`, `run_log_id`, `item_key`, `status` (all required)
* `patient_id`, `visit_id`, `appointment_date`, `reason`, `decision`, `error`: optional strings
* `item`, `outcome`: optional JSON objects. A string holding a JSON object is also accepted.

`status` is one of `updated`, `mips_found`, `completed`, `skipped`, `needs_va`, `accepted`, `check_required`, `declined`, `dry_run`, `scored`, `reviewed`, `failure`, `failed`. Nanonets Health stores `failed` as `failure`.

**Idempotent per `run_log_id` + `item_key`:** reporting the same key again replaces the earlier row, so a retry never duplicates an item.

Output:

```json theme={null}
{ "id": "…", "status": "accepted", "item_key": "…" }
```

## `nanonetshealth_complete_agent_run`

Inputs:

* `agent_id`, `run_log_id` (required)
* `status`: optional. One of `success`, `partial_success`, `failure`. If you omit it, Nanonets Health derives it from the reported items:
  * `failure` if every item failed
  * `partial_success` if some items failed
  * `success` otherwise
* `output`: optional JSON object, such as counts per status.

Output:

```json theme={null}
{ "run_log_id": "…", "status": "success" }
```

## Expected errors

The tools return Nanonets Health's own error text:

| Error | Meaning |
| - | - |
| `HTTP 404: run log not found for this agent` | `run_log_id` does not belong to this `agent_id` in this organization |
| `HTTP 400: unsupported status "…"` | `status` is not in the list above |
| `HTTP 400: item_key is required` | Missing `item_key` |
| `missing required api_key credential` | Nanonets Health is not connected |

These tools require the Nanonets Health release that adds external runs (fleming PR #467).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.