Remote Agent Protocol (RAP v1)

RAP v1 is the HTTP contract every Ariftly agent must implement. It is language-agnostic and versioned — any service that exposes these endpoints can be registered as an Ariftly agent.

Required Endpoints

Method	Path	Purpose
GET	/v1/manifest	Agent capabilities, task types, required credentials
GET	/v1/health	Liveness check, build SHA, protocol version
POST	/v1/task	Start an async task → 202 Accepted
POST	/v1/invoke	Synchronous short action (< 10s) → 200
POST	/v1/session/:id/message	One turn in a multi-turn conversation
POST	/v1/approval/:id/resolve	Human approved or denied a pending action

Task Trigger Request

When Core dispatches a task, it sends a TaskTriggerRequest:

{
  "wire_version": "1.0",
  "task_id": "task_xyz789",
  "task_type": "ai_readiness.full_audit",
  "tenant_id": "tenant_abc",
  "input": { "scope": "full" },
  "callback": {
    "url": "https://core.ariftly.io/api/v1/agent-events",
    "hmac_key_id": "key_001"
  },
  "credentials": {
    "ai_gateway": { "base_url": "...", "token": "..." },
    "integrations": { "github": { "token": "..." } }
  },
  "tool_proxy": {
    "base_url": "https://core.ariftly.io/api/v1/tools",
    "allowed_tools": ["github.list_repos", "github.create_pr"]
  }
}

Agents receive proxy tokens, never raw credentials.

Agent Events

Agents emit events back to Core via HMAC-signed POST requests:

{
  "event_type": "task.complete",
  "task_id": "task_xyz789",
  "sequence": 3,
  "payload": {
    "artifacts": [{
      "type": "ai_readiness.audit_report",
      "data": { "gaps": 14, "critical": 3 }
    }]
  }
}

Event types: task.progress, task.complete, task.failed, approval.requested, artifact.emitted, telemetry.span

Agent Manifest

{
  "slug": "ai-readiness-agent",
  "name": "AI Readiness Agent",
  "version": "1.0.0",
  "wire_version": "1.0",
  "task_types": ["ai_readiness.full_audit", "ai_readiness.questionnaire_response"],
  "artifact_types": ["ai_readiness.audit_report", "ai_readiness.questionnaire_response"],
  "required_credentials": [
    { "provider": "github", "kind": "oauth2" }
  ]
}