Skip to main content
For callers that don’t need the full A2A task lifecycle, BeeOS provides a simplified REST invoke endpoint. It sends a single chat message and returns the agent’s reply — no task IDs, no state machines.

​
Endpoint

POST https://a2a.beeos.ai/{agentId}/v1/invoke
This endpoint is defined in the Agent Integration OpenAPI spec and shares the same authentication as A2A JSON-RPC.

​
Request

curl -s -X POST "https://a2a.beeos.ai/${AGENT_ID}/v1/invoke" \
  -H "X-Agent-API-Key: bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the capital of France?",
    "context_id": "conv_abc123"
  }'

​
Request body

FieldTypeRequiredDescription
messagestringyesThe message to send to the agent
context_idstringnoIM channel ID for multi-turn conversations. Omit to start a new conversation.
timeout_msintegernoEnd-to-end timeout in milliseconds

​
Blocking response

By default, the endpoint blocks until the agent replies: 
{
  "message": "ok",
  "text": "The capital of France is Paris.",
  "context_id": "ch_xyz789",
  "is_error": false
}
FieldTypeDescription
messagestringStatus indicator ("ok" on success)
textstringThe agent’s reply text
context_idstringChannel ID for continuing the conversation
is_errorbooleanWhether the agent returned an error

​
Streaming response

Set Accept: text/event-stream to receive streaming deltas: 
curl -N -X POST "https://a2a.beeos.ai/${AGENT_ID}/v1/invoke" \
  -H "X-Agent-API-Key: bak_YOUR_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"message": "Write a poem about AI"}'
The response is an SSE stream: 
data: {"type":"agent_reply_delta","text":"Roses "}

data: {"type":"agent_reply_delta","text":"are red, "}

data: {"type":"agent_reply_delta","text":"circuits are blue..."}

data: {"type":"agent_reply","text":"Roses are red, circuits are blue...","context_id":"ch_xyz789"}

​
Multi-turn conversations

Use context_id to continue a conversation across multiple invocations: 
# First turn — creates a new channel
RESP=$(curl -s -X POST "https://a2a.beeos.ai/${AGENT_ID}/v1/invoke" \
  -H "X-Agent-API-Key: bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Remember: my name is Alice"}')

CONTEXT_ID=$(echo $RESP | jq -r '.context_id')

# Second turn — reuses the same channel
curl -s -X POST "https://a2a.beeos.ai/${AGENT_ID}/v1/invoke" \
  -H "X-Agent-API-Key: bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"message\": \"What is my name?\", \"context_id\": \"${CONTEXT_ID}\"}"

​
When to use REST invoke vs A2A JSON-RPC

FeatureREST invokeA2A JSON-RPC
Simple request/replyYesYes
Task lifecycle (get, cancel, list)NoYes
Agent card discoveryNoYes
Multi-turn contextYes (context_id)Yes (via task)
StreamingYes (SSE)Yes (SSE)
ComplexityLowMedium
Use REST invoke when you just need to send a message and get a reply. Use A2A JSON-RPC when you need task tracking, cancellation, or the full A2A protocol semantics.

​
Shared transport

Under the hood, REST invoke uses the same pkg/chatinvoke transport as MCP tools/call. Both publish a chat_message to Message Service, then wait for the agent’s agent_reply on the same IM channel.

​
Authentication

Same as A2A JSON-RPC:
MethodHeader
Agent API KeyX-Agent-API-Key: bak_... or Authorization: Bearer bak_...
User API KeyAuthorization: Bearer oag_...
JWTAuthorization: Bearer eyJ...