API · POST
POST /v1/agents/{id}/invoke
Invoke an agent with a goal — synchronous or streaming response.
Overview
POST /v1/agents/{id}/invoke
Invokes a deployed agent with a high-level goal. Returns a workflow ID for tracking and either a synchronous result or a stream of progress events. Every invocation inherits the caller's RBAC scope.
All xyner API calls require an OAuth2 bearer token with the appropriate scope. Every request is identity-bound and audit-captured.
Request
Example request
{
"goal": "Triage claim CLM-298471 and route to the correct queue.",
"context": {
"claim_id": "CLM-298471",
"customer_id": "CUST-014892"
},
"stream": true,
"max_tool_calls": 25,
"idempotency_key": "claim-CLM-298471-v1"
}
Response
Example response
A successful response has shape:
data: {"event":"step","step":1,"agent":"claims-triage-agent","action":"retrieve_policy"}
data: {"event":"step","step":2,"agent":"claims-triage-agent","action":"fraud_score","score":0.18}
data: {"event":"step","step":3,"agent":"claims-triage-agent","action":"route_to_queue","queue":"standard"}
data: {"event":"complete","workflow_id":"wf_01H8Z","outcome":"routed","duration_ms":2843}
Notes
Things worth knowing
Useful behavioural details for this endpoint.
- All endpoints support OpenTelemetry trace-context propagation via standard W3C headers.
- Idempotency keys are honoured for 24 hours (or longer for endpoints that explicitly support extended idempotency).
- Errors follow RFC 7807 problem+json with a stable error code in
type. - Every successful action produces one or more audit records, queryable via /v1/audit/query.
- Rate limits apply per-tenant; current limits are returned in
X-RateLimit-*response headers.
See also
Related endpoints and concepts
This endpoint is part of the broader xyner platform API. For an end-to-end view, see the platform overview and the documentation hub.
Get started
Ready to put autonomous agents to work?
See xyner in your environment with a guided executive demo.