Chat with agent (streaming)

POST/agent/stream-chat

Send a message to an agent and receive the response as a Server-Sent Events (SSE) stream. Events include message_start, content_delta, tool_use, tool_result, message_end, and error.

RequiresBearerauthentication

Header parameters

X-Phenoml-On-Behalf-Ofstringoptional

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

X-Phenoml-Fhir-Providerstringoptional

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

Body parameters

messagestringrequired

The message to send to the agent

contextstringoptional

Optional context for the conversation

session_idstringoptional

Optional session ID for conversation continuity. Only one request may be active for a session at a time; overlapping turns for the same session return 409 Conflict.

agent_idstringrequired

The ID of the agent to chat with

enhanced_reasoningbooleanoptionaldefault false

Enable enhanced reasoning capabilities. Increases latency but improves response quality and reliability.

Returns

Streaming chat response. Each frame is a standard SSE record (event: line + data: JSON line). The example shows a single content_delta payload — multiple frames stream until message_end.

Response fields

typestringoptional

The event type

message_startcontent_deltatool_usetool_resultmessage_enderror

session_idstringoptional

Chat session ID

contentstringoptional

Incremental text content (present in content_delta events)

successbooleanoptional

Whether the operation was successful

messagestringoptional

Status message

function_namestringoptional

Tool/function name (present in tool_use and tool_result events)

function_argsobjectoptional

Tool arguments (present in tool_use events)

function_resultobjectoptional

Tool execution result (present in tool_result events)

POSTRequest

curl -X POST 'https://experiment.app.pheno.ml/agent/stream-chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "message": "What is the patient'\''s current condition?",
  "context": "Respond concisely and with clear rationale",
  "session_id": "session-abc123",
  "agent_id": "agent-123",
  "enhanced_reasoning": false
}'

200 OKResponse

{
  "type": "content_delta",
  "session_id": "session_123",
  "content": "I'll create a patient record...",
  "success": true,
  "message": "Streaming chat response. Each frame is a standard SSE record\n(`event:` line + `data:` JSON line). The example shows a single\n`content_delta` payload — multiple frames stream until `message_end`.",
  "function_name": "lang2fhir_search",
  "function_args": {},
  "function_result": {}
}