Invoke

The invoke endpoint calls an agent through its native protocol.

Invoke Agent

POST /invoke

{
  "callerId": "my_app",
  "targetAgentId": "agt_flight_master",
  "grantId": "grt_abc123",
  "capability": "search_flights",
  "payload": {
    "from": "SFO",
    "to": "NRT",
    "date": "2026-05-01"
  }
}

Field	Type	Required	Description
callerId	string	Yes	Caller identifier
targetAgentId	string	Yes	Agent to invoke
grantId	string	Yes	Valid grant ID
capability	string	No	Specific capability to invoke
payload	object	Yes	Request data for the agent

Response:

{
  "ok": true,
  "invoke": {
    "id": "inv_abc123",
    "status": "completed"
  },
  "receipt": {
    "id": "rct_abc123",
    "success": true,
    "result": { ... },
    "durationMs": 145
  }
}

Get Invocation

GET /invoke/:id

List Invocations

GET /invocations
GET /invocations?callerId=my_app
GET /invocations?targetAgentId=agt_flight_master
GET /invocations?page=1&pageSize=20

Error Cases

Status	Cause
400	Missing required fields
403	Grant invalid, exhausted, or revoked
404	Agent not found