feat: add health endpoints by JeffreyJPZ · Pull Request #590 · dapr/dapr-agents

JeffreyJPZ · 2026-04-29T05:22:22Z

Description

Changes

Exposes /livez and /readyz endpoints when agents are hosted as a service.
Refactors runtime config updates and agent config resolution so that they use the same coerce/validate/transform/apply logic.
Creates a agent execution ToolChoice enum for consistency.
Move config resolution logic from the agent to the config classes.
Extracts agent execution defaults to named constants.

Issue reference

We strive to have all PR being opened based on an issue, where the problem or feature have been discussed prior to implementation.

Please reference the issue this PR closes: #375

Checklist

Please make sure you've completed the relevant tasks for this PR, out of the following list:

Created/updated tests
Tested this change against all the quickstarts
Extended the documentation
- Created the dapr/docs PR:

Note: We expect contributors to open a corresponding documentation PR in the dapr/docs repository. As the implementer, you are the best person to document your work! Implementation PRs will not be merged until the documentation PR is opened and ready for review.

TODO:

Update docs
Update 03-message-router-workflow example

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

Copilot

Pull request overview

Adds service health endpoints for hosted agents and introduces a readiness signal path from pub/sub consumer subscriptions up to the agent runner.

Changes:

Add /livez and /readyz endpoints to AgentRunner.serve() and implement readiness logic based on runner/agent wiring state.
Extend pub/sub subscription registration to return per-consumer “ready” status functions (in addition to closers), and thread this through runners.
Add/adjust tests to validate route registration return values and health endpoint behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`dapr_agents/workflow/runners/agent.py`	Mounts health/readiness endpoints and checks readiness conditions.
`dapr_agents/workflow/runners/base.py`	Stores/clears pubsub consumer status functions alongside closers.
`dapr_agents/workflow/utils/registration.py`	Changes route registration APIs to return `(closers, status_functions)`.
`dapr_agents/workflow/utils/subscription.py`	Builds status functions per streaming subscription and returns them with closers.
`tests/workflow/test_message_router.py`	Updates tests for new `(closers, status_functions)` return shape.
`tests/workflow/test_agent_runner.py`	Adds tests covering `/livez` and `/readyz` behavior under different states.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

JeffreyJPZ · 2026-04-29T05:23:21Z

        entry_path: str = "/agent/run",
        status_path: str = "/agent/instances/{instance_id}",
+        health_check_path: str = "/livez",
+        readiness_check_path: str = "/readyz",


Should Dapr Agent app health endpoints point to /readyz rather than /livez since it better aligns with Dapr health checks goals (i.e. "can it accept traffic?")

You've done the right thing here. In k8s lingo it's /readyz and /livez. We should update the default dapr to deprecate /healtz. Keep as-is in this pr :-)

Since both app health checks and K8s health checks are opt-in, should there also be a flag to determine if these endpoints should be exposed (similar to expose_entry)?

Yes that would be great. If you can add both an ENV variable + a setting in the agent execution config.
You can see the agent observability config. We should let the priority be agent execution config > env variable > default

If i'm not misunderstanding something, most CLI flags/K8s annotations aren't automatically made available as env variables in the app? Should we expect the env variable names to follow the CLI flags/K8s annotations (e.g. ENABLE_APP_HEALTH_CHECK, APP_HEALTH_CHECK_PATH)?

I'd go with ENABLE_APP_HEALTH_CHECK and ENABLE_APP_READY_CHECK.
You are correct that CLI flags and annotations aren't available as env vars.
In the real deployment model you'd either serve them as env vars on the manifest or you'd mount a configmap as env vars with the details.

We shouldn't let the path be overwritten imo.

When running locally you can just run export ENABLE_APP_HEALTH_CHECK in the terminal for it to be available as env var.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Casper Nielsen <whopsec@protonmail.com>

CasperGN · 2026-05-01T08:46:52Z

@JeffreyJPZ thank you for this one!

Can you move your comments to address the copilot review as it's a little confusing to me which belongs where?

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

CasperGN

A few comments for changes

CasperGN · 2026-05-04T09:11:06Z

+            self._default_http_paths.add(health_check_path)
+
+            async def _get_health_status() -> dict[str, str]:
+                return {"status": "ok"}


As done with the _is_ready() func, can we also include a check for the health endpoint so we know that the agent is actually running healthy?

Would this be the same as _is_ready excluding checking pub/sub consumers and HTTP routes (and shutdown signals)?

Hm. I think I was more referring to checking the internals of the agent. The agent could in theory be stuck in a workflow or throwing unrecoverable errors while this would still return ok

Thats fair. My initial thoughts are on some sort of heartbeat mechanism/watcher thread. I'm also looking at the unrecoverable error path in the subscription code, it looks like the consumer thread just logs the error and exits? Should there be self-healing by recreating consumer threads, or should it just report unhealthy and have K8s restart the container?

Some questions building off of my initial thoughts:

What if the watcher thread goes down? Can it be reactivated somehow (maybe reminders?)

How can one distinguish between a really long workflow and a "stuck" workflow, if that even is possible? AFAIK there's no "global" timeout for workflows (which I guess would defeat the point of a workflow), but maybe this can be configured on the agent somehow?

Regarding the subscription, I think it's fine to report unhealthy and restart. We gotta be careful not to interfere with the expected behavior of retries etc as that comes from the retry policies.

@JoshVanL do you have some input here about how we could probe the wf runtime to infer if it's "running healthy" or not?

Looks like there's only the wait_for_worker_ready method, but that's probably not enough

CasperGN · 2026-05-04T09:19:44Z

        entry_path: str = "/agent/run",
        status_path: str = "/agent/instances/{instance_id}",
+        health_check_path: str = "/livez",
+        readiness_check_path: str = "/readyz",


Yes that would be great. If you can add both an ENV variable + a setting in the agent execution config.
You can see the agent observability config. We should let the priority be agent execution config > env variable > default

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

JeffreyJPZ · 2026-05-16T04:59:17Z


 [mypy]
-python_version = 3.10
+python_version = 3.11


Needed to bump the version since StrEnum is only supported in >=3.11, and some tests rely on str(enum) being equal to the string value which only works in >=3.11. I think it was stale anyway since the pyproject file specifies >=3.11.

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

…-agents into health-endpoints

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

JeffreyJPZ · 2026-05-19T23:31:42Z

+        except RuntimeError as e:
+            # Fall through if the agent could not be updated but the value is otherwise valid
+            logger.debug(f"Agent {self.name}: {e}")
+            applied_value = None


Was this behaviour intended from the beginning? Had to split the config update in two which leads to a bit of redundant processing because of this, not sure if there's another way.

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

github-actions · 2026-07-20T22:39:20Z

This pull request has been automatically marked as stale because it has not had activity in the last 60 days. It will be closed in 7 days if no further activity occurs. Please feel free to give a status update now, ping for review, or re-open when it's ready. Thank you for your contributions!

JeffreyJPZ · 2026-07-20T23:06:59Z

keep-alive

JeffreyJPZ added 3 commits April 28, 2026 20:51

feat: add agent health endpoints

a3a2be5

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

test: add agent health endpoint tests

60e52fe

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

test: update failing message router tests

384a589

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

JeffreyJPZ requested a review from a team as a code owner April 29, 2026 05:22

Copilot AI review requested due to automatic review settings April 29, 2026 05:22

JeffreyJPZ requested a review from a team as a code owner April 29, 2026 05:22

Copilot started reviewing on behalf of JeffreyJPZ April 29, 2026 05:22 View session

Copilot AI reviewed Apr 29, 2026

View reviewed changes

JeffreyJPZ commented Apr 29, 2026

View reviewed changes

CasperGN and others added 2 commits May 1, 2026 10:28

Potential fix for pull request finding

eda8f22

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Casper Nielsen <whopsec@protonmail.com>

Merge branch 'main' into health-endpoints

bea2d70

JeffreyJPZ added 4 commits May 1, 2026 12:03

fix: address copilot feedback

b6b2218

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

test: add test for partial consumer readiness

b9c2231

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

style: lint fixes

1baa6c4

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

style: formatting fix

0a95ef8

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

CasperGN requested changes May 4, 2026

View reviewed changes

CasperGN self-assigned this May 4, 2026

JeffreyJPZ added 4 commits May 4, 2026 16:43

style: rename status function factory for consistency

adec6bd

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

style: use f-strings for agent serve logs

5b72c6c

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

fix: check fastapi app existence in agent routes check

032a2b4

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

style: lint fix

aa08f79

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

seherv reviewed May 5, 2026

View reviewed changes

Comment thread dapr_agents/workflow/utils/registration.py

seherv reviewed May 5, 2026

View reviewed changes

Comment thread dapr_agents/workflow/utils/registration.py Outdated

seherv reviewed May 5, 2026

View reviewed changes

Comment thread dapr_agents/workflow/utils/subscription.py Outdated

seherv reviewed May 5, 2026

View reviewed changes

Comment thread dapr_agents/workflow/runners/agent.py Outdated

JeffreyJPZ and others added 4 commits May 5, 2026 17:04

style: remove redundant stack trace flag

8c8fe42

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

Merge branch 'main' into health-endpoints

f53cf14

style: f-string logging for registration methods

e29bb08

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

chore: expose readiness details

ad1d162

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

JeffreyJPZ added 5 commits May 15, 2026 17:23

fix: merge approval config

d5a26f8

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

chore: change log level to warning on already mounted health endpoints

e86f2be

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

fix: change agent execution config priority

267e26e

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

refactor: move agent execution enums to types to avoid circular imports

3d5fbd1

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

feat: add any, required, none tool choices

a2be6fb

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

JeffreyJPZ force-pushed the health-endpoints branch from e42cd3d to a2be6fb Compare May 16, 2026 04:54

JeffreyJPZ commented May 16, 2026

View reviewed changes

sicoyle and others added 5 commits May 18, 2026 10:23

Merge branch 'main' into health-endpoints

a1ef95f

refactor: create process and apply config update methods

5a75f7d

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

Merge branch 'health-endpoints' of https://github.com/JeffreyJPZ/dapr…

38046bf

…-agents into health-endpoints

chore: update docstring

00663b5

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

chore: make agent default constant naming consistent

5489489

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

JeffreyJPZ commented May 19, 2026

View reviewed changes

JeffreyJPZ added 11 commits May 19, 2026 16:49

chore: update docstrings

3740d59

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

fix: add apply config update guards

f97e168

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

style: add whitespace

8bc0af3

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

chore: add defensive check comment

84ab1d9

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

refactor: create merge config method

e7f92d2

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

refactor: move config resolution logic out of agent

40e247f

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

refactor: mutate config during resolution

db217bf

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

refactor: remove redundant resolution logic

7b841e0

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

style: lint fixes

7fbe7f5

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

refactor: change error handling for config resolution

9e193b1

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

style: formatting fix

1bd3973

Signed-off-by: Jeffrey Zhang <jeffreyjpizhang@gmail.com>

JeffreyJPZ marked this pull request as draft May 21, 2026 22:24

JeffreyJPZ mentioned this pull request Jun 12, 2026

feat: add config resolution for agent execution config #642

Draft

4 tasks

github-actions Bot added the stale label Jul 20, 2026

github-actions Bot removed the stale label Jul 20, 2026

Uh oh!

Conversation

JeffreyJPZ commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Issue reference

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JeffreyJPZ May 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CasperGN commented May 1, 2026

Uh oh!

CasperGN left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JeffreyJPZ May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JeffreyJPZ May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JeffreyJPZ May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 20, 2026

Uh oh!

JeffreyJPZ commented Jul 20, 2026

Uh oh!

Reviewers

Assignees

Labels

JeffreyJPZ commented Apr 29, 2026 •

edited

Loading

JeffreyJPZ May 2, 2026 •

edited

Loading

JeffreyJPZ May 5, 2026 •

edited

Loading

JeffreyJPZ May 16, 2026 •

edited

Loading

JeffreyJPZ May 19, 2026 •

edited

Loading