A2A Protocol - AI Interview Docs

A2A Protocol

Agent-to-agent integration for external systems via JSON-RPC 2.0 and REST.

The A2A (Agent-to-Agent) protocol enables external systems — ATS platforms, HR tools, scheduling services — to programmatically create and manage interviews. It supports two interface styles: JSON-RPC 2.0 for agent-native integrations and REST for human-readable ones.

Style	Endpoint	Use Case
JSON-RPC 2.0	POST /api/v1/a2a/task	Agent-to-agent programmatic calls
REST	POST /api/v1/a2a/interview	ATS integrations, human-readable APIs

Guides

JSON-RPC 2.0

Protocol specification and method reference.

HITL Workflow

Human-in-the-loop approval gates and state machine.

Webhooks

Signed webhook events with retry policy.

Complete Workflow

A typical integration flows from interview creation to candidate link generation:

text

External System                    AI Interview System
      |                                    |
      |-- POST /a2a/interview ----------->|
      |                                    |-- Validate data
      |                                    |
      |   IF data complete:                |
      |<-- 201 { state: VALIDATING } ------|
      |<-- webhook: plan_generated --------|  (when plan ready)
      |                                    |
      |   IF data incomplete:              |
      |<-- 201 { state: INFO_NEEDED } -----|
      |<-- webhook: info_needed ----------|
      |                                    |
      |   [HITL completes missing info]    |
      |-- PATCH /a2a/:id/complete-info -->|
      |<-- webhook: info_completed --------|
      |<-- webhook: plan_generated --------|
      |                                    |
      |   [Recruiter reviews plan]         |
      |-- POST /a2a/:runId/approve ------->|
      |<-- 200 { interviewLink: ... } -----|
      |<-- webhook: approved --------------|

Endpoints

Method	Endpoint	Description
POST	/a2a/task	JSON-RPC 2.0 dispatch — routes to any method
POST	/a2a/interview	Create interview request
GET	/a2a/interview/:runId/status	Poll interview status
PATCH	/a2a/interview/:id/complete-info	HITL: provide missing fields
POST	/a2a/interview/:runId/approve	HITL: approve or reject plan
PATCH	/a2a/interview/:runId/request-modification	HITL: request plan changes
POST	/a2a/interview/:id/approve-assessment	HITL: approve/reject assessment

Quick Start

bash

# Create an interview with all required fields
curl -X POST http://localhost:3009/api/v1/a2a/interview \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "candidateName": "Jane Smith",
    "candidateEmail": "jane@example.com",
    "position": "Senior Engineer",
    "level": "SENIOR",
    "skills": ["TypeScript", "React", "Node.js"],
    "jobDescription": "Join our platform team to build scalable web applications with modern tech stack.",
    "callbackUrl": "https://ats.example.com/webhook"
  }'

Response 201

{
  "runId": "agno-run-uuid",
  "interviewId": "interview-uuid",
  "state": "VALIDATING_SKILLS",
  "message": "Interview request accepted. Skill validation in progress.",
  "dataQuality": "EXCELLENT"
}

Workflow States

State	Description
RECEIVED	Request received, data validation running
INFO_NEEDED	Missing critical data — HITL required to complete
VALIDATING_SKILLS	MCP validating skills, Agno generating plan
GENERATING_PLAN	Plan generation in progress (modification requested)
PENDING	Plan ready — awaiting recruiter approval
APPROVED	Plan approved, candidate interview link generated
REJECTED	Plan rejected by recruiter
SCHEDULED	Interview scheduled
IN_PROGRESS	Interview currently running
COMPLETED	Interview completed, assessment available
ASSESSMENT_PENDING	Awaiting recruiter assessment verdict
ASSESSMENT_APPROVED	Assessment approved by recruiter
CANCELLED	Interview cancelled

Always provide a callbackUrl to receive webhook notifications instead of polling. See the Webhooks guide for event schemas and HMAC signature verification.

Was this page helpful?

Previous← Health Checks

NextJSON-RPC 2.0 →