Skip to content

🌐 Frappe Helpdesk Agent REST API Reference

This document describes the local API client implemented in agents_crew/tools/frappe_tool.py used by autonomous agents to interact with Frappe Helpdesk.

1. Local Network Endpoint & Authentication

  • Base URL: http://127.0.0.1:8088 (Internal Docker network / Loopback)
  • Authentication Header: Authorization: token <api_key>:<api_secret>
  • Content-Type: application/json

2. Agent Client Operations

1. create_ticket()

Creates a new ticket under the agent's account.

client = FrappeHelpdeskClient("orchestrator")
ticket = client.create_ticket(
    subject="Bug in points moderation",
    description="Maker-Checker button visibility error.",
    ticket_type="Bug Fix",
    priority="High"
)

2. add_comment()

Appends a threaded message with optional screenshot or log attachments.

client = FrappeHelpdeskClient("qc_agent")
client.add_comment(
    ticket_id="HD-20260924025519",
    comment="Playwright visual suite passed. Verified on Staging.",
    attachment_paths=["/path/to/screenshot.png"]
)

3. create_kb_article()

Creates a mandatory Knowledge Base article, dual-published to Frappe Helpdesk and the authenticated MkDocs manual (/docs).

client = FrappeHelpdeskClient("doc_manager")
client.create_kb_article(
    title="Troubleshooting Passwordless OTP Login",
    content_markdown="## Details\n...",
    category="Authentication & Security",
    ticket_id="HD-20260924025519"
)

4. request_human_review()

Transitions the ticket status to Pending Review. Enforces that a KB article must be linked before this call succeeds.

client = FrappeHelpdeskClient("orchestrator")
client.request_human_review(
    ticket_id="HD-20260924025519",
    summary="Code tested and KB published. Ready for human lead sign-off."
)

3. Resilient Local State Fallback

When the remote container is in an offline maintenance state, all tickets and comments are persisted in high-speed local JSON stores: * Tickets Ledger: tests/artifacts/helpdesk_state/tickets.json * Knowledge Base Ledger: tests/artifacts/helpdesk_state/kb_articles.json