Skip to main content

AI Agent Chat Panel — Backend Requirements

Summary of Changes​

The AI chat panel is now available on both company and jobseeker dashboards as a collapsible side panel. It sends page context with each message so the agent can provide contextual suggestions and actions.

CRITICAL: Backend Schema Changes Required​

1. Make companyId optional in StartConversationInput​

Currently companyId is String! (required) and has a foreign key to the Company table. Jobseekers don't have a company, so this must be nullable.

# BEFORE
input StartConversationInput {
  agentId: String!
  userId: String!
  companyId: String!    # <-- FK to Company table
  title: String
}

# AFTER
input StartConversationInput {
  agentId: String!
  userId: String!
  companyId: String     # <-- Make nullable, remove FK constraint for jobseekers
  title: String
}

Database migration needed: AgentConversation.companyId must be nullable.

2. Make companyId optional in GET_CONVERSATIONS query​

# BEFORE
conversations(companyId: String!, ...): ConversationList

# AFTER  
conversations(companyId: String, userId: String, ...): ConversationList

When companyId is null, filter by userId instead.

3. Make companyId optional in CreateAgentInput​

For jobseeker agents, there's no company. The agent belongs to the user directly.

# BEFORE
input CreateAgentInput {
  companyId: String!
  ...
}

# AFTER
input CreateAgentInput {
  companyId: String     # nullable — if null, agent belongs to user
  userId: String        # new field — owner when no company
  ...
}

4. Make companyId optional in GET_AGENTS query​

# Allow fetching agents by userId when no companyId
agents(companyId: String, userId: String, ...): AgentList

5. Accept pageContext and entityId in messages​

Add fields to SendMessageInput​

input SendMessageInput {
  conversationId: String!
  content: String!
  attachments: [AttachmentInput!]
  forcedTools: [String!]
  pageContext: String     # NEW — e.g. "talents", "pipeline", "js_jobs"
  entityId: String        # NEW — UUID of entity being viewed
}

Page Context Values​

Company pages:

pageContextRouteEntity
dashboard/company/dashboard—
pipeline/company/pipeline—
talents/company/resume/talents—
talent_detail/company/resume/talents/:idtalent UUID
talentpool/company/resume/talentpool—
candidates/company/resume/candidates—
candidate_detail/company/resume/candidates/:idcandidate UUID
sharelist/company/resume/sharelist—
jobs/company/jobs—
job_detail/company/jobs/:idjob UUID
interviews/company/interviews—
meetings/company/meetings—
team/company/team—
connections/company/connections—

Jobseeker pages:

pageContextRouteEntity
js_dashboard/jobseeker/dashboard—
js_jobs/jobseeker/jobs—
js_job_detail/jobseeker/jobs/:idjob UUID
js_applications/jobseeker/application—
js_interviews/jobseeker/interviews—
js_interview_detail/jobseeker/interviews/:idinterview UUID
js_resume/jobseeker/resume—
js_connections/jobseeker/connections—

6. System Prompt Injection by Page Context​

When pageContext is provided, inject context into the system prompt:

For list pages:​

The user is currently on the "{label}" page.
Prefer tools relevant to this context: {relevant tool names}.

For detail pages (entityId present):​

The user is viewing a specific {entity type} (ID: {entityId}).
You can perform actions on this entity.
When the user says "edit this", "contact them", etc., use the entity ID.

For jobseeker pages:​

The user is a job seeker on the "{label}" page.
Help them with job search, applications, CV improvement, and interview preparation.

7. Required Tools — Company​

Search / Query​

ToolDescriptionPriority pages
search_talentsFind talent profilestalents, talentpool
search_jobsSearch job listingsjobs
search_candidatesPipeline candidatespipeline, candidates
get_company_infoCompany detailsdashboard
get_pipeline_overviewPipeline stages & countspipeline, dashboard
get_interviewsInterview listinterviews
get_meetingsMeeting listmeetings
get_team_membersTeam members & rolesteam
get_connectionsPartners & contactsconnections
rag_searchKnowledge base searchknowledge base
database_queryCustom SQL queryany (advanced)

Create / Action​

ToolDescriptionPriority pages
create_talentAdd talent profiletalents
create_jobPost new jobjobs
extract_cvParse CV from filetalents, candidates, talent_detail
parse_jobParse job descriptionjobs, job_detail
import_talentsBulk import CSV/PDFtalents
share_talentShare talent profilesharelist, talent_detail

Entity Actions (detail pages)​

ToolDescriptionPages
edit_talentEdit talent profile fieldstalent_detail
contact_talentSend message to talenttalent_detail
add_to_pipelineAdd to job pipelinetalent_detail
get_match_scoreCalculate job match scoretalent_detail, candidate_detail
edit_jobEdit job postingjob_detail
duplicate_jobCopy job to other companiesjob_detail
edit_candidateEdit candidate detailscandidate_detail
update_candidate_statusChange pipeline stagecandidate_detail

8. Required Tools — Jobseeker​

Search / Query​

ToolDescriptionPriority pages
search_jobsFind job listingsjs_jobs, js_dashboard
get_applicationsView application statusjs_applications, js_dashboard
get_interviewsUpcoming interviewsjs_interviews, js_dashboard
get_match_scoreJob match scorejs_job_detail
get_profile_tipsProfile improvement tipsjs_dashboard

Actions​

ToolDescriptionPages
apply_jobApply to a jobjs_job_detail
save_jobSave job for laterjs_job_detail
withdraw_applicationWithdraw applicationjs_applications
improve_cvGet CV suggestionsjs_resume
create_cvBuild a new CVjs_resume
prepare_interviewPractice questions & tipsjs_interviews, js_interview_detail

9. Default Agent Auto-Creation​

When to create​

The frontend auto-creates a default agent when:

  1. A new company is created (onboarding + add-company flows)
  2. The chat panel opens and no agents exist for the user/company

Default agent config​

{
  "name": "AI Assistant",
  "type": "RECRUITMENT_ASSISTANT",
  "ragEnabled": true,
  "llmModel": "eu.amazon.nova-lite-v1:0",
  "enabledTools": ["RAG_SEARCH"]
}

Backend recommendation​

Make CreateAgent idempotent — if the company/user already has an agent, return the existing one instead of creating a duplicate.

10. Tool Priority by Page Context​

When the frontend sends pageContext and no forcedTools, the backend should prefer tools matching that context. This is a hint, not a restriction.

Company​

pageContextPriority tools
dashboardget_company_info, get_pipeline_overview, search_jobs
pipelinesearch_candidates, get_pipeline_overview, update_candidate_status
talentssearch_talents, create_talent, extract_cv, import_talents
talent_detailedit_talent, contact_talent, add_to_pipeline, get_match_score
candidatessearch_candidates, get_match_score
candidate_detailedit_candidate, update_candidate_status, get_match_score
jobssearch_jobs, create_job, parse_job
job_detailedit_job, duplicate_job, search_candidates
interviewsget_interviews
meetingsget_meetings
teamget_team_members
connectionsget_connections
sharelistshare_talent, search_talents

Jobseeker​

pageContextPriority tools
js_dashboardsearch_jobs, get_applications, get_interviews, get_profile_tips
js_jobssearch_jobs, get_match_score
js_job_detailapply_job, save_job, get_match_score
js_applicationsget_applications, withdraw_application
js_interviewsget_interviews, prepare_interview
js_interview_detailprepare_interview
js_resumeimprove_cv, create_cv

11. Implementation Steps (Backend)​

  1. Database migration: Make AgentConversation.companyId nullable, add userId index
  2. GraphQL schema: Make companyId optional in StartConversationInput, CreateAgentInput, GET_CONVERSATIONS, GET_AGENTS
  3. Add pageContext and entityId fields to SendMessageInput
  4. System prompt builder: Inject page context into the system prompt when provided
  5. Tool priority resolver: When pageContext is provided without forcedTools, use the priority mapping above to hint which tools to prefer
  6. Implement jobseeker tools: apply_job, save_job, withdraw_application, improve_cv, create_cv, prepare_interview, get_profile_tips
  7. Implement entity action tools: edit_talent, contact_talent, add_to_pipeline, edit_job, duplicate_job, edit_candidate, update_candidate_status
  8. Default agent creation: Make CreateAgent idempotent — return existing agent if one exists for the company/user
  9. Agent ownership model: Support agents owned by userId (jobseekers) in addition to companyId (companies)

12. Frontend Access to Agent Management & Knowledge Base​

Company users can still manage agents and knowledge base from the sidebar:

  • AI Agents: /company/chatbot/agents — create, edit, enable/disable agents
  • Knowledge Base: /company/chatbot/knowledge — upload documents for RAG

These pages are accessible from the sidebar nav under "AI".

For jobseekers, agent management is not exposed — they use the auto-created default agent.