A2A Protocol

JSON-RPC 2.0

Protocol specification and method reference for agent-native A2A integrations.

The JSON-RPC 2.0 interface provides a single endpoint that routes to any interview management method. This style is preferred for agent-to-agent (A2A) integrations where the caller is itself an AI agent or automated system.

Protocol

Property	Value
Endpoint	POST /api/v1/a2a/task
Content-Type	application/json
Auth	X-API-Key or Bearer JWT
Spec	JSON-RPC 2.0 (https://www.jsonrpc.org/specification)

Every request must include jsonrpc: "2.0", a method, params, and an id.

Request envelope

{
  "jsonrpc": "2.0",
  "method": "<method-name>",
  "params": { ... },
  "id": 1
}

Success response envelope

{
  "jsonrpc": "2.0",
  "result": { ... },
  "id": 1
}

Error response envelope

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": { "field": "candidateEmail", "issue": "Invalid email format" }
  },
  "id": 1
}

Error Codes

Code	Meaning
-32700	Parse error — invalid JSON
-32600	Invalid Request — not a valid JSON-RPC object
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32001	Authentication failed
-32002	Insufficient permissions
-32003	Interview not found
-32004	Invalid state transition

Methods

Method	Permission	Description
interview.create	interview:create	Create a new interview request
interview.getStatus	interview:read	Get current workflow status
interview.approve	interview:approve	Approve or reject a plan
interview.completeInfo	interview:update	Provide missing HITL data
interview.requestModification	interview:approve	Request plan changes

interview.create

Request

bash

curl -X POST http://localhost:3009/api/v1/a2a/task \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "interview.create",
    "params": {
      "candidateName": "Jane Smith",
      "candidateEmail": "jane@example.com",
      "position": "Senior Engineer",
      "level": "SENIOR",
      "skills": ["TypeScript", "React", "Node.js"],
      "jobDescription": "Build scalable platform services.",
      "callbackUrl": "https://ats.example.com/webhook"
    },
    "id": 1
  }'

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "runId": "agno-run-uuid",
    "interviewId": "interview-uuid",
    "state": "VALIDATING_SKILLS",
    "message": "Interview request accepted.",
    "dataQuality": "EXCELLENT"
  },
  "id": 1
}

interview.getStatus

json

{
  "jsonrpc": "2.0",
  "method": "interview.getStatus",
  "params": { "runId": "agno-run-uuid" },
  "id": 2
}

interview.approve

json

{
  "jsonrpc": "2.0",
  "method": "interview.approve",
  "params": {
    "runId": "agno-run-uuid",
    "approved": true,
    "userId": "recruiter-uuid"
  },
  "id": 3
}

For simpler human-readable integrations (ATS webhooks, admin tools), use the REST endpoints instead of JSON-RPC 2.0.

Was this page helpful?

Previous← Overview

NextREST Endpoints →