Python SDK

The Herald Python SDK (runllm) lets you write support workflows in plain Python. A workflow listens for activity on a surface (a Slack thread, a Zendesk ticket, or the chat widget on your site), and then drives your Herald assistant step by step: answer the question, tag and categorize the conversation, escalate to a ticket, wait for a button click, hand off to a human, and so on.

You write the workflow locally and publish it with the SDK. Herald then hosts and runs it for you, so there is no server to deploy or keep running.

Requirements

• Python 3.10 or later
• A Herald API key. Create one from your account menu in the admin console.
• The surfaces you want to use (Slack, Zendesk, or the chat widget) already connected to your assistant. See Deploy Your Agent.

Installation

pip install runllm-sdk

The package is imported as runllm.

Previously RunLLM

Herald was previously known as RunLLM. The SDK still uses the original names: the package is runllm-sdk, the module is runllm, and environment variables are prefixed with RUNLLM_.

Authentication

The SDK reads your API key from the RUNLLM_API_KEY environment variable:

export RUNLLM_API_KEY="<your-api-key>"

You can also pass it to the client directly with Client(api_key="...").

Quickstart

The workflow below answers every question that mentions the Herald bot in a Slack workspace. If the assistant isn’t confident, it offers to escalate the question to a Zendesk ticket.

from runllm import (
    Agent,
    AnswerCategory,
    Client,
    Event,
    Mention,
    SlackListener,
)
from runllm.decorators import entrypoint


@entrypoint(listeners=[SlackListener(team_id="T0123456789", default_trigger=Mention())])
def answer_question(agent: Agent, event: Event) -> None:
    convo = event.conversation
    thread = convo.surface

    answer = agent.answer(convo)
    agent.send_to_slack_thread(answer, to=thread)

    if answer.category in (AnswerCategory.UNANSWERED, AnswerCategory.LOW_CONFIDENCE):
        clicked = agent.send_to_slack_thread(
            "Want me to open a support ticket for this?",
            to=thread,
            enable_feedback=False,
            blocks=[
                {
                    "type": "buttons",
                    "buttons": [
                        {"id": "yes", "style": "primary", "text": "Yes, open a ticket"},
                        {"id": "no", "text": "No thanks"},
                    ],
                }
            ],
        )
        if clicked and clicked.id == "yes":
            ticket = agent.create_zendesk_ticket(subdomain="acme", conversation=convo)
            agent.send_to_slack_thread(f"Opened ticket #{ticket.id}.", to=thread)


if __name__ == "__main__":
    Client().publish(name="slack-support", entrypoint=answer_question)

Run the script to publish:

python workflow.py

📤 Publishing workflow 'slack-support'
✅ Workflow 'slack-support' has been published successfully!
🕒 The workflow will be fully rolled out within a few minutes.

Once it’s rolled out, mention the Herald bot in any channel in that workspace to trigger the workflow.

How it works

1. Publish. Client.publish() serializes your entrypoint function and any tasks with cloudpickle and uploads them to Herald, along with the listeners and an optional static config.
2. Trigger. When an event matches one of the entrypoint’s listeners (for example, someone mentions the bot in Slack), Herald starts a new workflow run and calls your entrypoint with an Agent and the triggering Event.
3. Act. Each agent.* call is an action that runs on the Herald server: generating an answer, posting to Slack, creating a ticket, and so on.
4. Transition. A task can call agent.listen(...) to hand the run off to another task, which is invoked on the next matching event on the surfaces it’s listening to.

Read Core concepts for the details, Agent actions for every action the agent can take, and the Types reference for listeners, triggers, surfaces, and message types.

Your code runs on Herald’s infrastructure

Published functions run in a hosted Python environment that matches the Python version you published from. Only the SDK and its dependencies (requests, pydantic, aiohttp, loguru) are installed there, so:

• Don’t import other third-party packages in your workflow code.
• Define helper functions in the same script as your workflow rather than in separate local modules.
• Don’t rely on local files or environment variables from your machine. Pass settings through the static config instead.

Debug logging

By default, the SDK prints only short progress messages. Set RUNLLM_DEBUG=true to enable full debug logging:

RUNLLM_DEBUG=true python workflow.py