A2A Protocol

HITL Workflow

Human-in-the-loop approval gates for data completion, plan review, and assessment verdicts.

The Human-in-the-Loop (HITL) workflow provides approval gates at three stages: data completion when interview information is incomplete, plan approval before a candidate receives their interview link, and assessment review after the interview completes.

State Machine

text

RECEIVED
    │
    ├── Data complete? ──────────────────► VALIDATING_SKILLS
    │                                           │
    └── Data incomplete? ──► INFO_NEEDED        │
              │                  │             ▼
              │              HITL fills    GENERATING_PLAN
              │              missing data      │
              │                  │             ▼
              └──────────────────┘         PENDING
                                               │
                              ┌────────────────┤
                              │                │
                           APPROVED         REJECTED
                              │
                              ▼
                         SCHEDULED ──► IN_PROGRESS ──► COMPLETED
                                                           │
                                                    ASSESSMENT_PENDING
                                                           │
                                            ┌──────────────┤
                                            │              │
                                   ASSESSMENT_APPROVED  CANCELLED

Stage 1: Data Completion

When a create request has missing or low-quality fields, the system enters INFO_NEEDED state and sends a webhook with the missing fields and questions to guide the recruiter.

Severity	Fields	Impact
CRITICAL	candidateName, candidateEmail, position	Blocks all processing
HIGH	jobDescription (50+ chars), skills (1+), level	Degrades quality, triggers INFO_NEEDED
MEDIUM	skills < 3, jobDescription < 100 chars	Informational warning only

bash

# HITL provides missing fields
curl -X PATCH http://localhost:3009/api/v1/a2a/interview/:id/complete-info \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "recruiter-uuid",
    "jobDescription": "We are looking for a senior engineer to lead our platform team with 5+ years of TypeScript experience.",
    "skills": ["TypeScript", "React", "Node.js", "PostgreSQL"],
    "level": "SENIOR"
  }'

Response 200 — transitions to VALIDATING_SKILLS

{
  "message": "Interview information completed. Skill validation starting.",
  "state": "VALIDATING_SKILLS"
}

Stage 2: Plan Approval

When the AI generates an interview plan, the workflow enters PENDING state and sends a webhook. The recruiter reviews the plan in the admin dashboard and approves, rejects, or requests modifications.

bash

# Approve the plan
curl -X POST http://localhost:3009/api/v1/a2a/interview/:runId/approve \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "approved": true,
    "userId": "recruiter-uuid"
  }'

Response 200

{
  "message": "Interview plan approved. Candidate link generated.",
  "workflowState": "APPROVED",
  "interviewLink": "https://app.ai-interview.com/interview/join/abc123token",
  "inmailDraft": {
    "subject": "Senior Software Engineer Opportunity at Acme Corp — Interview Invitation",
    "body": "Hi Jane,\n\nI came across your profile and was impressed by your TypeScript and React expertise...\n\nPlease click the link below to begin your interview:\nhttps://app.ai-interview.com/interview/join/abc123token\n\nBest regards,\nThe Acme Corp Recruiting Team"
  }
}

The inmailDraft is generated by the Planner AI using the company name, position, and key required skills. Send it directly to the candidate as a LinkedIn InMail invitation — the interview link is already substituted in the body. It is only present on approval, not rejection.

bash

# Request modifications
curl -X PATCH http://localhost:3009/api/v1/a2a/interview/:runId/request-modification \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "recruiter-uuid",
    "comments": "Please add more system design questions and reduce basic syntax questions. Candidate has 8 years experience."
  }'

Stage 3: Assessment Review

After the interview completes, the AI generates a structured assessment. The workflow enters ASSESSMENT_PENDING state for recruiter review.

bash

# Approve assessment with score overrides
curl -X POST http://localhost:3009/api/v1/a2a/interview/:id/approve-assessment \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "recruiter-uuid",
    "approved": true,
    "recruiterScores": {
      "technical": {
        "typescript_proficiency": 4,
        "system_design": 3,
        "problem_solving": 4
      },
      "communication": {
        "clarity": 4,
        "structure": 3
      }
    },
    "biasAnnotations": "Candidate was direct and confident. No bias concerns."
  }'

HITL Endpoints Summary

Stage	Endpoint	Permission
Data Completion	PATCH /a2a/interview/:id/complete-info	interview:update
Plan Approval	POST /a2a/interview/:runId/approve	interview:approve
Plan Modification	PATCH /a2a/interview/:runId/request-modification	interview:approve
Assessment Review	POST /a2a/interview/:id/approve-assessment	interview:approve

The admin dashboard at /admin/approvals provides a UI for all HITL operations. Recruiters can review plans, approve/reject, and provide feedback without making direct API calls.

Was this page helpful?

Previous← REST Endpoints

NextWebhooks →