Skip to content

A Markdown file and after_run ​

The agent prepares a file and a script posts it to the helpdesk. The publication token is supplied only to hooks through top-level services.

Create the task ​

before_run writes replies/<run_id>.md to reply-path.txt. Instructions tell the agent to read that path and atomically save the completed Markdown. A per-run path prevents publishing an old reply.

py
"""Illustrative admission request, not a webhook server."""
import json
import os
from pathlib import Path
from urllib.request import Request, urlopen

body = {
    "namespace": "helpdesk",
    "external_key": "support.example.com:ticket:4821",
    "configuration": {
        "agent": {
            "profile": "default",
            "instructions": "Prepare an internal reply. Read reply-path.txt and atomically save the finished Markdown reply to that path. Do not publish it yourself.",
        },
        "sandbox": {"template": "codex"},
        "hooks": {
            "before_run": '#!/bin/sh\nset -eu\nmkdir -p replies\nprintf "replies/%s.md\\n" "$ORPHEUS_RUN_ID" > reply-path.txt\n',
            "after_run": Path(__file__).with_name("publish.py").read_text(),
        },
    },
    "env": {"TICKET_ID": "4821"},
    "services": ["helpdesk"],
    "messages": [{"text": "Ticket 4821: export permission denied. Suggest what the operator should check."}],
}
request = Request(
    os.environ["ORPHEUS_URL"].rstrip("/") + "/api/v1/sessions",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['ORPHEUS_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "helpdesk:ticket:4821:event:105",
    },
    method="POST",
)
with urlopen(request, timeout=30) as response:
    print(response.read().decode())

Publication script ​

Save publish.py beside create.py:

py
#!/usr/bin/env python3
"""Illustrative hook. Adapt the URL and payload to your helpdesk API."""
import json
import os
from pathlib import Path
from urllib.request import Request, urlopen

if os.environ.get("ORPHEUS_AGENT_STATUS") != "completed":
    raise SystemExit("Agent did not complete. No comment published.")
reply = Path(os.environ["ORPHEUS_WORKSPACE_PATH"], "replies", os.environ["ORPHEUS_RUN_ID"] + ".md")
text = reply.read_text().strip()
if not text:
    raise SystemExit("Reply file is empty.")
request = Request(
    f"{os.environ['HELPDESK_URL'].rstrip('/')}/tickets/{os.environ['TICKET_ID']}/comments",
    data=json.dumps({"body": text, "internal": True}).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['HELPDESK_TOKEN']}",
        "Content-Type": "application/json",
        "Idempotency-Key": os.environ["ORPHEUS_HOOK_OPERATION_ID"],
    },
    method="POST",
)
with urlopen(request, timeout=30) as response:
    print(f"Comment published: HTTP {response.status}")

Set ORPHEUS_URL and ORPHEUS_API_KEY in the connector environment. Define the helpdesk service on API and worker, and supply its HELPDESK_URL and HELPDESK_TOKEN values to the worker. The example selects the service only for run hooks. The template needs Python 3.

The code uses the hypothetical helpdesk contract. If your API does not support Idempotency-Key, check for an existing comment before retrying. An arbitrary header alone does not prevent duplicates.

Verify it ​

Test a normal reply, a missing file, an empty file and a helpdesk API failure. On publication errors, inspect after_run in run details. Do not blindly repeat the entire assignment. First check whether the comment was created.

The hook-only selection in this request does not prevent selecting the same catalog service for an agent elsewhere. See request scopes and catalog visibility when a publication token should stay outside service selectors.