Skip to main content

Python SDK

The RunLLM 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 RunLLM 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. RunLLM then hosts and runs it for you, so there is no server to deploy or keep running.

Requirements​

  • Python 3.10 or later
  • A RunLLM 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.

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 RunLLM 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 RunLLM 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 RunLLM, 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), RunLLM 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 RunLLM 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 RunLLM'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