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

# Get authentication token
PHENOML_TOKEN=$(curl -X POST "https://experiment.app.pheno.ml/v2/auth/token" \
  -u "$PHENOML_CLIENT_ID:$PHENOML_CLIENT_SECRET" \
  | jq -r '.access_token')

curl -X POST "https://experiment.app.pheno.ml/agent/stream-chat" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "What is the patient'\''s current condition?",
  "agent_id": "agent-123",
  "session_id": "session-abc123"
}'

200 OKExample Response

{
  "type": "content_delta",
  "session_id": "session-abc123",
  "content": "Based on the patient records, "
}