5.1.1 Set Up Conversational Agent Chat

Prerequisites

Before setting up the conversational agent chat, complete the following steps:

• Configure the LLM provider and model that the agent uses. See Create an LLM Definition.
• Create an agent profile. See Create an Agent Profile.
  • Define the agent role, instructions, LLM profile, model, prompt variables, tools, MCP servers, guardrails, and model parameters.
  • Enable the CONVERSATIONAL capability. If the same profile must also run inside workflows, enable the WORKFLOW capability too.
  • Enable or disable memory on the agent profile. Memory is enabled by default. When enabled, MicroTx Workflows includes recent chat messages and a conversation summary in the prompt context.
• Configure tools if required. Create tool configurations for RAG retrieval, agent execution, workflow invocation, APIs, databases, files, or MCP servers, and attach the required tools to the agent profile. See Create an Internal Tool Configuration.
• Secure API access. Ensure the client application obtains an OAuth 2.0 access token from the configured identity provider and passes it when invoking the chat APIs. RBAC permissions control who can execute chat and read or delete chat history.
• Configure streaming and memory settings if needed. Optional runtime properties include chat stream executor settings, SSE timeout and heartbeat settings, chat context cache TTL, maximum context tokens, maximum message tokens, and maximum short-term window messages.
• Plan deployment for multi-pod environments. The current implementation uses local in-memory cache for recent chat context. For multi-pod deployments, configure session affinity so requests for the same chat session are routed consistently. Align SSE heartbeat and timeout settings with load balancer and proxy idle timeouts.

Use the conversational agent through the chat REST APIs:

1. Build or configure a client application to call the chat streaming API.
2. Obtain an OAuth 2.0 access token from the configured identity provider.
3. Invoke POST /api/conversational-agent/chat with the agent name, chat session ID, and user input.
4. Consume the streamed SSE response events from the API, including tool execution events, heartbeat events, and the final agent response.
5. Use the history APIs as needed to list, retrieve, or delete chat sessions.

Example

{
  "agentName": "medical_history_agent",
  "chatSessionId": "session-001",
  "userInput": "Summarize the patient history and highlight open risks."
}

You can either integrate this API directly into your own application or invoke it directly for testing. You can also refer to a sample Python-based chat application in the GitHub samples repository that demonstrates use of the chat streaming API. See https://github.com/oracle-samples/microtx-samples/tree/main/workflow/RAG-ingestion-retrieval-workflows.