Creating assistants

Assistants (agents) are chat backends that you implement and register in Admin → Agents. Each has an alias and base URL (e.g. http://your-server.com:8020 — no trailing slash). Users choose an assistant from the sidebar; the portal provides the chat UI, embed, and multi-language.

Required endpoints

1. GET /metadata

Return JSON with at least name; recommended: description, capabilities, supported_models, sample_prompts, status ("active" | "inactive").

Example call:

curl -s http://your-server:8020/metadata

Example response (JSON):

{
  "name": "Document Assistant",
  "description": "Search and summarize documents",
  "capabilities": ["search", "summarize"],
  "supported_models": [
    { "model_id": "gpt-4o-mini", "name": "GPT-4o Mini", "accepted_file_types": ["pdf", "docx"] }
  ],
  "sample_prompts": ["Summarize an article about AI"],
  "provided_data_types": [{ "type": "documents", "description": "List of documents" }],
  "status": "active"
}

2. POST /ask — Request and response (important for developers)

Request body the Portal sends: session_id, model_id, user, prompt, output_type, and context.

• output_type — output_type — The Portal always sends "markdown". If your agent API validates output type, it must accept "markdown". Using only "text" as valid will cause errors (e.g. "Invalid output type: text") when users chat from the portal.
• context — context — May include language, project, extra_data.document (file URLs), history (previous messages).

Response your agent must return: JSON with status: "success" and at least one of content_markdown, answer, or content (string). Prefer content_markdown for rich display. Without these, the Portal shows "Agent error" to the user.

Base URL: Use no trailing slash (e.g. http://host:8020). A trailing slash can cause 404 on /ask when the portal calls your agent.

Example call:

curl -X POST 'http://your-server:8020/ask' \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"test-123","model_id":"gpt-4o-mini","user":"admin-test","prompt":"Hello","output_type":"markdown","context":{}}'

Example request body (Portal sends):

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "model_id": "gpt-4o-mini",
  "user": "https://portal.example.com/api/users/email/user@example.com",
  "prompt": "Summarize this document",
  "output_type": "markdown",
  "context": {
    "language": "en",
    "extra_data": { "document": ["https://.../file.pdf"] },
    "history": []
  }
}

Example response (agent must return):

{
  "status": "success",
  "content_markdown": "## Summary\n\nSummary content here..."
}

3. GET /data (optional)

Use when your agent has data to list (documents, experts, …). The Portal calls with query type (e.g. documents, experts).

Example call:

curl -s 'http://your-server:8020/data?type=documents'

Example response (JSON):

{
  "status": "success",
  "data_type": "documents",
  "items": [
    { "id": "1", "title": "Document A", "url": "https://..." },
    { "id": "2", "title": "Document B", "url": "https://..." }
  ]
}

Registration & testing

Admin → Agents → Add: alias (e.g. papers), base URL, icon. You can set a routing hint so the Central assistant selects this agent when the user does not choose one. Use Test API in Admin to send a sample request.

Full request/response examples and system APIs (user, project) that the portal sends in context: frontend/docs/README.md (Agent API) and docs/DEVELOPERS.md in the repository.