run-llama/workflows-py
1
0
Fork 0
mirror of https://github.com/run-llama/workflows-py.git synced 2026-07-19 08:46:21 -04:00
Code Issues 18 Packages Projects Releases 10 Wiki Activity

[PR #89] [MERGED] feat: Add POST /events/{handler_id} endpoint and /handlers endpoint #107

New Issue
Closed
opened 2026-02-16 02:16:37 -05:00 by yindo · 0 comments
yindo commented 2026-02-16 02:16:37 -05:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/run-llama/workflows-py/pull/89
Author: @zhaotai
Created: 9/9/2025
Status: ✅ Merged
Merged: 9/10/2025
Merged by: @zhaotai

Base: main ← Head: feat/add-post-events-endpoint

📝 Commits (4)

  • cd0b378 feat: Add POST /events/{handler_id} endpoint and /tasks endpoint
  • 190fe9b fix lint
  • 03abc10 refactor: Update /tasks endpoint to /handlers with enhanced status tracking
  • 396287f update comments

📊 Changes

5 files changed (+414 additions, -4 deletions)

View changed files

📝 pyproject.toml (+1 -1)
📝 src/workflows/server/server.py (+160 -0)
📝 tests/server/conftest.py (+17 -0)
📝 tests/server/test_server_endpoints.py (+234 -1)
📝 uv.lock (+2 -2)

📄 Description

Summary

  • Added GET /handlers endpoint to get information about all workflow handlers
  • Added POST /events/{handler_id} endpoint to send events to running workflows
  • Enables external event injection into workflow contexts for interactive use cases

Changes

1. GET /handlers Endpoint

  • Returns list of all workflow handlers with their current status
  • Each handler includes:
    • handler_id: Unique identifier
    • status: Current state (running, completed, or failed)
    • result: Result value if completed
    • error: Error message if failed
  • Provides complete visibility into workflow execution state

2. POST /events/{handler_id} Endpoint

  • Allows sending events to running workflows via HTTP POST
  • Validates handler exists and workflow is still running
  • Deserializes events from JSON and sends to workflow context
  • Supports optional step parameter to target specific workflow steps

3. Error Handling

  • 200: Event sent successfully
  • 400: Invalid event data or deserialization error
  • 404: Handler not found
  • 409: Workflow already completed
  • 500: Context not available

Test Plan

  • Added InteractiveWorkflow test fixture that waits for external events
  • Test successful event sending to running workflow
  • Test error case: handler not found
  • Test error case: workflow already completed
  • Test error case: invalid event data
  • Test error case: missing event data
  • Test GET /handlers with empty list
  • Test GET /handlers with running workflows
  • Test GET /handlers with completed workflows
  • Test GET /handlers with failed workflows
  • All 55 server tests passing

Use Cases

This enables developers to:

  1. Monitor all workflow handlers and their execution state via /handlers endpoint
  2. Send events to running workflows for interactive/human-in-the-loop use cases
  3. Build event-driven integrations with external systems
  4. Implement pause/resume functionality in workflows
  5. Track workflow execution results and failures

API Examples

Get all handlers

GET /handlers

Response:
{
  "handlers": [
    {
      "handler_id": "abc123",
      "status": "running",
      "result": null,
      "error": null
    },
    {
      "handler_id": "def456", 
      "status": "completed",
      "result": "processed: data",
      "error": null
    }
  ]
}

Send event to running workflow

POST /events/{handler_id}
{
  "event": "{\"__is_pydantic\": true, \"value\": {\"message\": \"Hello\"}, \"qualified_name\": \"ExternalEvent\"}",
  "step": "optional_target_step"
}

Response:
{
  "status": "sent"
}

🤖 Generated with Claude Code

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/run-llama/workflows-py/pull/89 **Author:** [@zhaotai](https://github.com/zhaotai) **Created:** 9/9/2025 **Status:** ✅ Merged **Merged:** 9/10/2025 **Merged by:** [@zhaotai](https://github.com/zhaotai) **Base:** `main` ← **Head:** `feat/add-post-events-endpoint` --- ### 📝 Commits (4) - [`cd0b378`](https://github.com/run-llama/workflows-py/commit/cd0b378549a463e215e110abf480082461ce7958) feat: Add POST /events/{handler_id} endpoint and /tasks endpoint - [`190fe9b`](https://github.com/run-llama/workflows-py/commit/190fe9be69a3ce2c15ec169c68a68a8aa5e6831a) fix lint - [`03abc10`](https://github.com/run-llama/workflows-py/commit/03abc105e41f2d6c90a83fe3dc86a36c8d1cf6c8) refactor: Update /tasks endpoint to /handlers with enhanced status tracking - [`396287f`](https://github.com/run-llama/workflows-py/commit/396287ff4442b2ffff5fe60cad7d648de213abd5) update comments ### 📊 Changes **5 files changed** (+414 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `pyproject.toml` (+1 -1) 📝 `src/workflows/server/server.py` (+160 -0) 📝 `tests/server/conftest.py` (+17 -0) 📝 `tests/server/test_server_endpoints.py` (+234 -1) 📝 `uv.lock` (+2 -2) </details> ### 📄 Description ## Summary - Added GET `/handlers` endpoint to get information about all workflow handlers - Added POST `/events/{handler_id}` endpoint to send events to running workflows - Enables external event injection into workflow contexts for interactive use cases ## Changes ### 1. GET /handlers Endpoint - Returns list of all workflow handlers with their current status - Each handler includes: - `handler_id`: Unique identifier - `status`: Current state (running, completed, or failed) - `result`: Result value if completed - `error`: Error message if failed - Provides complete visibility into workflow execution state ### 2. POST /events/{handler_id} Endpoint - Allows sending events to running workflows via HTTP POST - Validates handler exists and workflow is still running - Deserializes events from JSON and sends to workflow context - Supports optional `step` parameter to target specific workflow steps ### 3. Error Handling - 200: Event sent successfully - 400: Invalid event data or deserialization error - 404: Handler not found - 409: Workflow already completed - 500: Context not available ## Test Plan - [x] Added `InteractiveWorkflow` test fixture that waits for external events - [x] Test successful event sending to running workflow - [x] Test error case: handler not found - [x] Test error case: workflow already completed - [x] Test error case: invalid event data - [x] Test error case: missing event data - [x] Test GET /handlers with empty list - [x] Test GET /handlers with running workflows - [x] Test GET /handlers with completed workflows - [x] Test GET /handlers with failed workflows - [x] All 55 server tests passing ## Use Cases This enables developers to: 1. Monitor all workflow handlers and their execution state via `/handlers` endpoint 2. Send events to running workflows for interactive/human-in-the-loop use cases 3. Build event-driven integrations with external systems 4. Implement pause/resume functionality in workflows 5. Track workflow execution results and failures ## API Examples ### Get all handlers ```bash GET /handlers Response: { "handlers": [ { "handler_id": "abc123", "status": "running", "result": null, "error": null }, { "handler_id": "def456", "status": "completed", "result": "processed: data", "error": null } ] } ``` ### Send event to running workflow ```bash POST /events/{handler_id} { "event": "{\"__is_pydantic\": true, \"value\": {\"message\": \"Hello\"}, \"qualified_name\": \"ExternalEvent\"}", "step": "optional_target_step" } Response: { "status": "sent" } ``` 🤖 Generated with [Claude Code](https://claude.ai/code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
yindo added the pull-request label 2026-02-16 02:16:37 -05:00
yindo closed this issue 2026-02-16 02:16:37 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
enhancement
enhancement
good first issue
pull-request
Mirrored from GitHub Pull Request
 question
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: run-llama/workflows-py#107
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?