Agent Integration

Kafka: skill.validation.requested
    │  (position, level, qualifications[]?, skills[]?, jobDescription?, company context)
    ▼
Agno Planner Agent (Python, port 7777)
    ├── pgvector similarity search → map qualifications/skills to knowledge base
    ├── Extract qualification criteria:
    │     • must_have  ← critical requirements (e.g. "5+ years TypeScript")
    │     • nice_to_have ← preferred but not blocking (e.g. "GraphQL experience")
    ├── Build prompt: qualifications + company context + candidate profile
    ├── Vertex AI Gemini 2.0 Flash (fine-tuned) → generate structured plan JSON:
    │     • competencies + scoring rubrics (with is_required flag)
    │     • questions with follow-ups
    │     • must_have[]     ← qualification criteria array
    │     • nice_to_have[]  ← preferred criteria array
    │     • greeting_script ← Hiring Assistant's opening for this specific interview
    │     • inmail_draft    ← LinkedIn InMail with {{INTERVIEW_LINK}} placeholder
    └── Kafka: interview.plan.created → API Gateway saves plan
                   │
                   ▼
          API Gateway: state → PENDING (or APPROVED if autoApprovePlans)
          Webhook: interview.plan_generated → tenant callbackUrl

# From apps/agno-agents/
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
export KAFKA_BROKERS=<kafka-broker>
export DATABASE_URL=postgresql://...

uvicorn agents.planner.main:app --host 0.0.0.0

Kafka: audio.candidate.spoken (key=sessionId)
    │  WebM/Opus blob OR streaming STT chunk from browser
    ▼
Agno Hiring Assistant (Python, port 7778)
    │  Per-session FIFO worker thread (ThreadPoolExecutor — sessions never block each other)
    ├── Load session state from Redis
    │     (plan, current_question_idx, follow_up_idx, greeting_sent, messages[], pending_answers[])
    ├── Streaming STT path (streaming="chunk"/"end")
    │     └── StreamingSTTSession → accumulates partial transcript; final cached in _streaming_transcripts
    ├── Batch STT path (full audio blob)
    │     └── Reuse cached streaming transcript if ≥ 12 words; else call Google Cloud STT batch API
    │           RecognitionConfig: LINEAR16, sample_rate=48000, en-US, enhanced model, auto_punctuation
    ├── Answer debounce: FRAGMENT_DEBOUNCE (1.5s) for short; ANSWER_DEBOUNCE (0.8s) for substantial
    ├── Confusion / off-topic detection → redirect question
    ├── Compute context: remaining_minutes, questions_remaining, follow_ups_remaining, evidence_requirements
    ├── Vertex AI Gemini 2.0 Flash (fine-tuned)
    │     └── System prompt includes: time remaining, question progress, follow-up probes left,
    │           evidence to verify, NVC techniques (mirroring, labeling, calibrated questions)
    ├── Follow-up logic: exhaust plan follow_ups[] before advancing to next question
    └── Gemini 2.5 Flash TTS (Vertex AI, voice: Kore)
          └── emotion tags: [encouraging], [thoughtful], [pause], etc.
          └── Raw PCM L16 24kHz mono output
          └── Kafka: audio.agent.spoken (key=sessionId, base64 PCM in JSON)
                  │
                  ▼
          Vert.x Kafka consumer → WebSocket { type: "AGENT_RESPONSE", data: base64_pcm }
                  │
                  ▼
          Browser: AgentResponseHandler decodes Int16→Float32 + plays via AudioContext

# From apps/agno-agents/
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json  # Must be OS env var, not just dotenv
export KAFKA_BROKERS=<kafka-broker>
export REDIS_HOST=<redis-host>

PYTHONUNBUFFERED=1 uvicorn agents.interviewer.main:app --host 0.0.0.0 --log-level info

{
  "assessmentId": "assessment-uuid",
  "overallScore": 82,
  "recommendation": "STRONG_HIRE",
  "finalVerdict": "HIRE",
  "verdictBy": "recruiter-uuid",
  "summary": "The candidate demonstrated strong TypeScript and distributed systems skills...",
  "strengths": ["Strong system design thinking", "Clear communication"],
  "weaknesses": ["Limited experience with distributed tracing"],

  "mustHaveMet": 3,
  "mustHaveTotal": 3,
  "mustHaveEvaluations": [
    {
      "criterion": "5+ years TypeScript experience",
      "category": "MUST_HAVE",
      "met": true,
      "confidence": 0.95,
      "evidence": "Demonstrated advanced generics, decorators, and strict mode patterns"
    }
  ],
  "niceToHaveEvaluations": [
    {
      "criterion": "GraphQL experience",
      "category": "NICE_TO_HAVE",
      "met": false,
      "confidence": 0.8,
      "evidence": "GraphQL was not discussed during the session"
    }
  ],
  "required_competency_failures": [],

  "competencyScores": [
    {
      "competency": "TypeScript Proficiency",
      "weight": 0.35,
      "aggregated_score": 4.2,
      "is_required": true,
      "below_minimum": false
    }
  ]
}

curl http://<planner-host>/health/ready      # Planner (default dev port: 7777)
curl http://<interviewer-host>/health/ready  # Hiring Assistant (default dev port: 7778)
curl http://<assessor-host>/health/ready     # Assessor (default dev port: 7779)

{ "status": "ready", "kafka": "connected", "redis": "connected" }

AGNO_PLANNER_URL=http://planner-agent
AGNO_INTERVIEWER_URL=http://interviewer-agent
AGNO_ASSESSOR_URL=http://assessor-agent
A2A_INTERNAL_TOKEN=<secret>  # Shared auth between NestJS and agents