Types reference

All the types below can be imported directly from runllm, unless noted otherwise. The entrypoint and task decorators live in runllm.decorators. See Entrypoints and tasks.

All types except Client are Pydantic models.

Client

Client(server_address: str = "https://api.runllm.com", api_key: Optional[str] = None)

Publishes workflows to Herald. If api_key isn’t set, the client reads it from the RUNLLM_API_KEY environment variable, and raises an exception if neither is set.

publish()

client.publish(
    name: str,
    entrypoint: EntrypointWrapper,
    config: Optional[Dict[str, Any]] = None,
    tasks: Optional[List[TaskWrapper]] = None,
) -> None

Serializes and uploads the workflow. The workflow is fully rolled out within a few minutes of a successful publish.

Argument	Description
name	The workflow name.
entrypoint	The @entrypoint-decorated function that starts each run.
config	Optional JSON-serializable static config, passed to every entrypoint and task. See Static config.
tasks	Every @task-decorated function the workflow can transition to.

Raises an exception if entrypoint isn’t decorated with @entrypoint, if two tasks have the same name, or if the server rejects the request.

Listeners

SlackListener

Starts workflow runs from Slack messages in a workspace.

Field	Type	Description
team_id	str	Required. The Slack workspace ID (starts with T).
channels	List[SlackChannel]	Optional. Channels with their own triggers. If omitted, the listener covers every channel the Herald bot has access to.
default_trigger	Trigger or List[Trigger]	The triggers for channels that aren’t in channels. Defaults to Mention().

SlackChannel

Field	Type	Description
channel_id	str	Required. The Slack channel ID (starts with C).
trigger	Trigger or List[Trigger]	Optional. The triggers for this channel.

WidgetListener

Starts workflow runs from the Herald chat widget.

Field	Type	Description
domain	str	Required. The domain the chat widget is embedded on, for example docs.example.com.

ZendeskListener

Starts workflow runs from Zendesk ticket activity.

Field	Type	Description
subdomain	str	Required. Your Zendesk subdomain. For https://acme.zendesk.com, use acme.
trigger	Trigger or List[Trigger]	Required. Usually TicketCreated(), TicketComment(), or both.

Triggers

Trigger	Fields	Description
Mention	none	Slack only. A message mentions the Herald bot.
ChannelMessage	none	Slack only. A new top-level message in the channel.
Emoji	shortcode: str, exclude_replies: bool = True	Slack only. An emoji reaction on the last message in the conversation. shortcode excludes the colons.
ConvoMessage	none	A new message in an existing Slack thread or chat widget conversation.
TicketComment	none	Zendesk only. A new comment on a ticket.
TicketCreated	none	Zendesk only. A new ticket.

The TicketComment trigger isn’t exported from the top-level package. Import it with from runllm.bridge.trigger import TicketComment.

Events

Event

Passed to every entrypoint and task.

Field	Type	Description
conversation	Conversation	The conversation the event happened in.
user	UserMetadata	The user who triggered the event. user.email is currently only populated for Slack, and is None otherwise.
trigger	Trigger	The trigger that matched.

Conversation

Field	Type	Description
new_message	UserChatMessage	The user message that triggered the event.
surface	ChatSurface	Where the conversation lives.
tags	List[str]	Tags already applied to the conversation.
session_id	int	Read-only. Shorthand for surface.session_id.

Surfaces

ChatSurface is any of SlackThread, ZendeskTicket, or ChatWidget. Every surface has:

Field	Type	Description
type	str	"slack_thread", "zendesk_ticket", or "chat_widget".
session_id	int	The Herald conversation this surface belongs to.

Check surface.type (or use isinstance) before calling a surface-specific action. For example, send_to_slack_thread() raises an exception if to isn’t a SlackThread.

SlackThread

Property	Type	Description
team_id	str	The Slack workspace ID.
channel	str	The Slack channel ID.
config.thread_ts	Optional[str]	The Slack thread timestamp. None until the thread has been posted to.

ZendeskTicket

Property	Type	Description
id	str	The Zendesk ticket ID.
subdomain	str	The Zendesk subdomain.
status	str	The ticket status, such as "open". Updated in place by update_zendesk_ticket().

ZendeskTicketStatus

An enum of Zendesk’s built-in ticket statuses: NEW, OPEN, PENDING, ON_HOLD, SOLVED, and CLOSED.

ZendeskCustomField

A value for a Zendesk custom ticket field, used with update_zendesk_ticket().

Field	Type	Description
id	int	The Zendesk custom field ID. Numeric strings are accepted.
value	str, List[str], or bool	The value to set.

ChatWidget

Property	Type	Description
config.convo_identifier	str	A unique ID for the widget conversation.
config.chat_user_id	Optional[str]	The end-user ID, if your site passes one to the widget.
config.context	Optional[Dict[str, Any]]	Page context from the widget, such as page_title, page_content, and url.

Messages

UserChatMessage

A message from a user.

Field	Type	Description
text	str	The message text.
chat_id	Optional[int]	The Herald ID for this message.
user_identifier	Optional[str]	The user’s ID. The format depends on the surface: a UUID for the chat widget, <channel_id>:<user_id> for Slack, and the Zendesk user ID for Zendesk.
attachments	Optional[List[Dict[str, Any]]]	Files attached to the message.

AssistantChatMessage

A message generated by the assistant, returned by agent.answer() and agent.chat().

Field	Type	Description
text	str	The answer text.
chat_id	int	The Herald ID for this answer.
category	Optional[AnswerCategory]	How well the assistant was able to answer.

AnswerCategory

Value	Meaning
ANSWERED	The assistant answered with reasonable confidence.
LOW_CONFIDENCE	The assistant answered, but with low confidence.
UNANSWERED	The assistant couldn’t answer, usually because the documentation doesn’t cover the question.
IRRELEVANT	The question is outside the assistant’s scope.

ButtonClicked

Returned by send_to_slack_thread() after a user clicks a button. Import it with from runllm.button import ButtonClicked.

Field	Type	Description
id	str	The id of the button that was clicked.