Invoking Agents

POST /v1/a2a/invoke

Invoke an agent using JSON-RPC 2.0 SendMessage:


curl -X POST https://api.cendriix.ai/v1/a2a/invoke \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "jsonrpc": "2.0",
    "method": "a2a.sendMessage",
    "params": {
      "agentId": "code-reviewer",
      "message": {
        "role": "user",
        "parts": [{ "text": "Review PR #42 for security issues" }]
      }
    }
  }'

Request format


interface InvokeRequest {
  jsonrpc: '2.0';
  method: 'a2a.sendMessage';
  params: {
    agentId: string;              // Agent slug or UUID
    sessionId?: string;           // Group messages in a session
    message: {
      role: 'user';
      parts: A2aPart[];           // Content parts (text, data, url, raw)
    };
    skillIds?: string[];          // Scope to specific skills
    configuration?: {
      acceptedOutputModes?: string[];
      taskPushNotificationConfig?: {
        url: string;
        headers?: Record<string, string>;
      };
      historyLength?: number;
      returnImmediately?: boolean;
    };
  };
}

Response format


interface InvokeResponse {
  jsonrpc: '2.0';
  result: {
    task: {
      id: string;
      agentId: string;
      status: A2aTaskState;
      artifacts: A2aArtifact[];
      messages: A2aMessage[];
      createdAt: string;
      updatedAt: string;
    };
  };
}

For long-running tasks, the response returns immediately with status: 'SUBMITTED'. Poll via GET /v1/a2a/tasks/:id or subscribe via SSE streaming.

Content parts

Each message contains one or more parts. Exactly one content field must be set per part:

Field	Type	Use case
`text`	`string`	Plain text or markdown content
`data`	`unknown`	Structured JSON payload
`url`	`string`	URL reference (file, webpage, API endpoint)
`raw`	`string`	Base64-encoded binary data

Additional fields: metadata, filename, mediaType.

Task states


SUBMITTED → WORKING → COMPLETED
                   → FAILED
                   → CANCELED
                   → REJECTED
           → INPUT_REQUIRED
           → AUTH_REQUIRED

State	Terminal	Description
`SUBMITTED`	No	Task received, queued for execution
`WORKING`	No	Agent actively processing
`INPUT_REQUIRED`	No	Agent paused, waiting for additional input
`AUTH_REQUIRED`	No	Agent paused, waiting for auth action
`COMPLETED`	Yes	Task finished successfully
`FAILED`	Yes	Task failed with error
`CANCELED`	Yes	Task canceled by client
`REJECTED`	Yes	Task rejected (unauthorized, invalid, or quota exceeded)

Idempotency

Include an Idempotency-Key header with a unique value (UUID recommended). If a request is retried within 24 hours with the same key, the original result is returned instead of re-executing.