Skip to content
Back to search

hayhooks

Easily deploy Haystack pipelines as REST APIs and MCP Tools.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/deepset-ai/hayhooks with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/deepset-ai/hayhooks'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/deepset-ai--hayhooks/badge.svg)](/listings/deepset-ai--hayhooks)

HTML

<a href="/listings/deepset-ai--hayhooks"><img src="/api/listings/deepset-ai--hayhooks/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install Hayhooks

# Install Hayhooks
pip install hayhooks

2. Start Hayhooks

hayhooks run

3. Create a simple agent

Create a minimal agent wrapper with streaming chat support and a simple HTTP POST API:

from typing import AsyncGenerator
from haystack.components.agents import Agent
from haystack.dataclasses import ChatMessage
from haystack.tools import Tool
from haystack.components.generators.chat import OpenAIChatGenerator
from hayhooks import BasePipelineWrapper, async_streaming_generator

# Define a Haystack Tool that provides weather information for a given location.
def weather_function(location):
    return f"The weather in {location} is sunny."

weather_tool = Tool(
    name="weather_tool",
    description="Provides weather information for a given location.",
    parameters={
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
    },
    function=weather_function,
)

class PipelineWrapper(BasePipelineWrapper):
    def setup(self) -> None:
        self.agent = Agent(
            chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
            system_prompt="You're a helpful agent",
            tools=[weather_tool],
        )

    # This will create a POST /my_agent/run endpoint
    # `question` will be the input argument and will be auto-validated by a Pydantic model
    async def run_api_async(self, question: str) -> str:
        result = await self.agent.run_async(messages=[ChatMessage.from_user(question)])
        return result["last_message"].text

    # This will create an OpenAI-compatible /chat/completions endpoint
    async def run_chat_completion_async(
        self, model: str, messages: list[dict], body: dict
    ) -> AsyncGenerator[str, None]:
        chat_messages = [
            ChatMessage.from_openai_dict_format(message) for message in messages
        ]

        return async_streaming_generator(
            pipeline=self.agent,
            pipeline_run_args={
                "messages": chat_messages,
            },
        )

Save as `my_agent_dir/pipeline_wrapper.py`.

4. Deploy it

hayhooks pipeline deploy-files -n my_agent ./my_agent_dir

5. Run it

Call the HTTP POST API (`/my_agent/run`):

curl -X POST http://localhost:1416/my_agent/run \
  -H 'Content-Type: application/json' \
  -d '{"question": "What can you do?"}'

Call the OpenAI-compatible chat completion API (streaming enabled):

curl -X POST http://localhost:1416/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "my_agent",
    "messages": [{"role": "user", "content": "What can you do?"}]
  }'

Or chat with it in the [embedded Chainlit UI](docs/features/chainlit-integration.md) (`hayhooks run --with-chainlit`) or [integrate it with Open WebUI](docs/features/openwebui-integration.md)!

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 287 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="docs/assets/haystack-icon.png" width="80" alt="">
  3. # Hayhooks
  4. **Serve [Haystack](https://haystack.deepset.ai/) pipelines and agents as APIs.**
  5. REST APIs, OpenAI-compatible chat, MCP tools, and A2A agents, with durable execution and built-in tracing.
  6. [![PyPI - Version](https://img.shields.io/pypi/v/hayhooks.svg)](https://pypi.org/project/hayhooks)
  7. [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hayhooks.svg)](https://pypi.org/project/hayhooks)
  8. [![Docker image release](https://github.com/deepset-ai/hayhooks/actions/workflows/docker.yml/badge.svg)](https://github.com/deepset-ai/hayhooks/actions/workflows/docker.yml)
  9. [![Tests](https://github.com/deepset-ai/hayhooks/actions/workflows/tests.yml/badge.svg)](https://github.com/deepset-ai/hayhooks/actions/workflows/tests.yml)
  10. [**Documentation**](https://deepset-ai.github.io/hayhooks/) · [Quick start](#quick-start) · [Dashboard](#terminal-dashboard) · [Durable execution](#durable-execution)
  11. </div>
  12. ## Serve your pipelines and agents
  13. Write a Python wrapper around your pipeline or agent. Choose the interfaces and runtime features you need:
  14. - **REST APIs.** Deploy Python wrappers or YAML pipelines as typed, validated endpoints with OpenAPI docs, file uploads, and custom routes.
  15. - **[OpenAI-compatible APIs](docs/features/openai-compatibility.md).** Serve streaming Chat Completions and Responses endpoints. Connect [Open WebUI](docs/features/openwebui-integration.md) or use the embedded [Chainlit UI](docs/features/chainlit-integration.md).
  16. - **[MCP support](docs/features/mcp-support.md).** Run an MCP server that exposes pipelines and agents as tools for Cursor, Claude Desktop, and other Model Context Protocol clients.
  17. - **[A2A support](docs/features/a2a-support.md).** Expose chat-capable pipelines and agents through the Agent2Agent protocol, with generated agent cards for discovery and task delegation.
  18. - **[Durable execution](#durable-execution).** Checkpoint long-running work in Redis, wait for human approval, retry failures, and recover after restarts.
  19. - **[Tracing and observability](docs/reference/tracing.md).** Inspect executions and component traces in the terminal dashboard, or export spans to an OpenTelemetry backend with `hayhooks[tracing]`.
  20. ## Terminal dashboard
  21. Inspect deployments, follow executions, and find slow components in your terminal.
  22. [![Hayhooks terminal dashboard showing five deployments and a selected research agent's status](docs/assets/terminal-dashboard/overview-120x36.png)](docs/assets/terminal-dashboard/overview-120x36.png)
  23. *Actual terminal UI with demo data.* [Explore the dashboard](docs/features/terminal-dashboard.md).
  24. ## Quick start
  25. Serve a Haystack agent through a typed HTTP endpoint. You need Python 3.10 through 3.14 and an OpenAI API key.
  26. ### Install and start
  27. In your Python environment, install Hayhooks and set the API key before starting the server:
  28. ```bash
  29. pip install hayhooks
  30. export OPENAI_API_KEY="your-api-key"
  31. hayhooks run
  32. ```
  33. Leave the server running. Use a second terminal for the following commands.
  34. ### Create an agent
  35. Create a directory named `my_agent_dir` and save this as `my_agent_dir/pipeline_wrapper.py`:
  36. ```python
  37. from haystack.components.agents import Agent
  38. from haystack.components.generators.chat import OpenAIResponsesChatGenerator
  39. from haystack.dataclasses import ChatMessage
  40. from haystack.tools import tool
  41. from hayhooks import BasePipelineWrapper
  42. @tool
  43. def search(query: str) -> str:
  44. """Search the knowledge base."""
  45. return f"This is a demo tool."
  46. class PipelineWrapper(BasePipelineWrapper):
  47. def setup(self) -> None:
  48. self.pipeline = Agent(
  49. chat_generator=OpenAIResponsesChatGenerator(model="gpt-4o-mini"),
  50. tools=[search],
  51. )
  52. async def run_api_async(self, question: str) -> str:
  53. result = await self.pipeline.run_async(messages=[ChatMessage.from_user(question)])
  54. return result["last_message"].text
  55. ```
  56. Hayhooks uses the method's type hints to validate requests and generate the API schema.
  57. ### Deploy and run
  58. ```bash
  59. hayhooks pipeline deploy-files -n my_agent ./my_agent_dir
  60. curl http://localhost:1416/my_agent/run \
  61. -H 'Content-Type: application/json' \
  62. -d '{"question": "What can you do?"}'
  63. ```
  64. The response contains the agent's answer. Open [the API docs](http://localhost:1416/docs) to inspect and try the endpoint.
  65. <details>
  66. <summary><strong>Add streaming chat</strong></summary>
  67. Implement `run_chat_completion_async` to expose the agent through the [OpenAI-compatible Chat Completions API](docs/features/openai-compatibility.md#async-chat-completion-with-streaming).
  68. Add these imports at the top of `pipeline_wrapper.py`:
  69. ```python
  70. from collections.abc import AsyncGenerator
  71. from hayhooks import async_streaming_generator
  72. ```
  73. Add this method inside `PipelineWrapper`:
  74. ```python
  75. async def run_chat_completion_async(
  76. self, model: str, messages: list[dict], body: dict
  77. ) -> AsyncGenerator[str, None]:
  78. return async_streaming_generator(
  79. pipeline=self.pipeline,
  80. pipeline_run_args={
  81. "messages": [ChatMessage.from_openai_dict_format(m) for m in messages],
  82. },
  83. )
  84. ```
  85. Redeploy the wrapper, then request a streamed response:
  86. ```bash
  87. hayhooks pipeline deploy-files -n my_agent ./my_agent_dir --overwrite
  88. curl -N http://localhost:1416/chat/completions \
  89. -H 'Content-Type: application/json' \
  90. -d '{
  91. "model": "my_agent",
  92. "messages": [{"role": "user", "content": "What can you do?"}],
  93. "stream": true
  94. }'
  95. ```
  96. The response arrives as server-sent events. Connect [Open WebUI](docs/features/openwebui-integration.md) or use the [embedded Chainlit UI](docs/features/chainlit-integration.md) to chat with the agent.
  97. </details>
  98. <details>
  99. <summary><strong>Inspect your run in the dashboard</strong></summary>
  100. On macOS or Linux, open the dashboard in the second terminal under the same OS account as the server:
  101. ```bash
  102. pip install "hayhooks[tui]"
  103. hayhooks dashboard
  104. ```
  105. Press `e` for executions or `v` for traces, then Enter for details. Local capture is enabled by default. Recent ordinary runs remain available until the server restarts or the buffer evicts them.
  106. For Windows or remote access, follow the [dashboard connection guide](docs/features/terminal-dashboard.md#connect-to-a-remote-server). To export spans to an external OpenTelemetry backend, see [tracing and OpenTelemetry](docs/reference/tracing.md).
  107. </details>
  108. ## Durable execution
  109. Run work beyond the lifetime of a request. Hayhooks checkpoints pipelines and agents in Redis so another worker can resume after a restart.
  110. Suspend a run for human approval, retry failures, or reconnect to its output stream from any replica.
  111. ```mermaid
  112. stateDiagram-v2
  113. direction LR
  114. [*] --> queued: submit (202)
  115. queued --> running: worker claims
  116. running --> waiting: suspend for a human
  117. waiting --> queued: resume
  118. running --> queued: retry or crash recovery
  119. running --> completed
  120. running --> failed
  121. running --> canceled
  122. ```
  123. <details>
  124. <summary><strong>Run an agent with human approval</strong></summary>
  125. This example waits for approval before calling a demo search tool. Save the wrapper as `pipelines/research_agent/pipeline_wrapper.py`.
  126. ```python
  127. from haystack.components.agents import Agent
  128. from haystack.components.generators.chat import OpenAIResponsesChatGenerator
  129. from haystack.dataclasses import ChatMessage
  130. from haystack.tools import tool
  131. from pydantic import BaseModel
  132. from hayhooks import BasePipelineWrapper, DurableContext
  133. @tool
  134. def search(query: str) -> str:
  135. """Search the knowledge base."""
  136. return f"Hayhooks serves Haystack pipelines and agents; results for {query!r}."
  137. class Task(BaseModel):
  138. question: str
  139. class Approval(BaseModel):
  140. approved: bool
  141. class Report(BaseModel):
  142. answer: str
  143. class PipelineWrapper(BasePipelineWrapper):
  144. durable_revision = "research-agent-v1" # compatibility key for persisted inputs and checkpoints
  145. durable_resume_model = Approval # typed input for human-in-the-loop waits
  146. def setup(self) -> None:
  147. generator = OpenAIResponsesChatGenerator(model="gpt-4o-mini")
  148. self.pipeline = Agent(chat_generator=generator, tools=[search])
  149. async def run_durable_async(self, context: DurableContext, task: Task) -> Report:
  150. # Persist the wait in Redis so a worker serving this revision can resume it.
  151. if not context.state.get("approved"):
  152. decision = context.resume_input # consumed on first read
  153. if decision is None:
  154. await context.suspend({"kind": "approval", "message": f"Research {task.question!r}?"})
  155. if not Approval.model_validate(decision).approved:
  156. raise ValueError("research was rejected")
  157. context.state["approved"] = True
  158. # Agent state is checkpointed after tool calls: recovery continues the loop.
  159. result = await context.run_agent_async(messages=[ChatMessage.from_user(task.question)])
  160. return Report(answer=result["last_message"].text)
  161. ```
  162. Stop the quick-start server if it is still running. Install the extra, start Redis, and serve the pipelines directory in durable mode:
  163. ```bash
  164. pip install "hayhooks[durable]"
  165. docker run -d -p 6379:6379 redis
  166. export OPENAI_API_KEY="your-api-key"
  167. HAYHOOKS_DURABLE_MODE=true hayhooks run --pipelines-dir ./pipelines
  168. ```
  169. In a second terminal, submit the run:
  170. ```bash
  171. curl -i http://localhost:1416/research_agent/run-durable \
  172. -H 'Content-Type: application/json' -d '{"question": "What does Hayhooks do?"}'
  173. ```
  174. The server returns `202 Accepted` with the execution ID and links. Replace `EXECUTION_ID` below with that ID and check the run's status:
  175. ```bash
  176. curl http://localhost:1416/research_agent/executions/EXECUTION_ID
  177. ```
  178. When the status is `waiting`, you can test recovery: stop the server and start it again with the same command. The wait survives the restart.
  179. Recovery requires a worker serving the same revision. When deploying an incompatible change, keep the old revision running until its work finishes. See [revision compatibility](docs/features/durable-execution.md#revisions).
  180. Approve the run and follow its output:
  181. ```bash
  182. curl -X POST http://localhost:1416/research_agent/executions/EXECUTION_ID/resume \
  183. -H 'Content-Type: application/json' -d '{"approved": true}'
  184. curl -N http://localhost:1416/research_agent/executions/EXECUTION_ID/stream
  185. ```
  186. </details>
  187. Read the [durable execution guide](docs/features/durable-execution.md) for checkpoint behavior and the [operations guide](docs/deployment/durable-operations.md) for deployment and recovery. The same engine also [embeds in any FastAPI app](docs/examples/durable-fastapi.md).
  188. ## Next steps
  189. - [Quick Start Guide](docs/getting-started/quick-start.md) - Get started with Hayhooks
  190. - [Installation](docs/getting-started/installation.md) - Install Hayhooks and dependencies
  191. - [Configuration](docs/getting-started/configuration.md) - Configure Hayhooks for your needs
  192. - [Terminal Dashboard](docs/features/terminal-dashboard.md) - Inspect deployments, executions, and component traces
  193. - [Durable Execution](docs/features/durable-execution.md) - Run Pipelines and Agents beyond the request
  194. - [Examples](docs/examples/overview.md) - Explore example implementations
  195. ## Community & Support
  196. - **GitHub**: [deepset-ai/hayhooks](https://github.com/deepset-ai/hayhooks)
  197. - **Issues**: [GitHub Issues](https://github.com/deepset-ai/hayhooks/issues)
  198. - **Documentation**: [Full Documentation](https://deepset-ai.github.io/hayhooks/)
  199. Hayhooks is actively maintained by the [deepset](https://deepset.ai/) team.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.