# /interact /interact provides a natural language interface for reasoning over your knowledge graph, allowing you to provide unstructured data and queries, but receiving deterministic results. This enables you to embed deterministic, explainable decisions, into: * User-facing chatbots * Agentic AI solutions * Retrieval Augmented Generation (RAG) solutions * Fully autonomous workflows * Custom software integrations {% hint style="info" %} All features delivered by Rainbird Labs are beta. They may contain bugs, are subject to change and are not covered by our platform SLAs. Your feedback can help shape development. {% endhint %} ## Getting Started /interact is in open beta and details can be found in our [API reference](/rainbird/developer-docs/api-reference.md). From here you download the OpenAPI specification to import into, for example Postman. Once you have API access you can do the following: 1. Establish a session with your chosen knowledge map through the /start endpoint. (Authentication uses your Rainbird account API key passed in the header as `X-API-Key)` 2. Call /interact with a user prompt containing a question (the query) and/or data from which to extract facts 3. /interact will respond with a question, result or an error 1. Given you receive a question, send your answer to /interact (using the same SessionID). Repeat until a decision is returned. 2. Given you receive a result, you can make additional queries within the same session or use the FactID to get an explanation {% hint style="info" %} For details of how to test this functionality within the Studio, see our page on the Natural Language test agent. {% endhint %} ## /interact response guide Given a Session ID, set of data and a query, you will receive a response containing either a question, result or error. For simplicity, this is indicated in the `responseType` field. {% tabs %} {% tab title="Question" %} The question object uses our standard questionResponse schema used by our core APIs. The `prompt` contains the question to present to a user or AI agent. Additional properties can be used to control the experience, but this is not mandatory: 1. `dataType` : data expected of the response, which will be string, number, date or truth. 2. `plural`: when this is `true`, multiple answers are allowed. If multiple answers are received when this is `false`, an error will be returned. 3. `concepts` : this array provides a list of concept instances as possible answers (relevant only when the answer expected is a string). These could be presented to the user as options, summarised or ignored. 4. `canAdd` : when this is `true`, any string will be accepted. When `false`, only known instances listed in the concept array above will be accepted. If an undefined instance is provided, an error will be returned 5. `allowUnknown` : when this is `true`, it means the data is optional and can be skipped (e.g. you could return a userPrompt of "I don't know"). When `false` the data is mandatory and we will continue to respond with the same question. {% endtab %} {% tab title="Result" %} The result array uses our standard resultResponse schema also used in our Core endpoints. You can use the `SubjectValue`, `Relationship`, `ObjectValue` and `Certainty` to construct the result. If you know which side of the query was the target (e.g. the object) you could present just the object and certainty as the answer. You can also use the FactID to get a natural language explanation of the result, using our /explain endpoint. {% endtab %} {% tab title="Error" %} In the event of an error you will receive a HTTP status code, internal code, error description and a suggested chat response. If you don’t want to use the suggested chat responses, please contact us at to obtain a set of the latest error codes. {% endtab %} {% endtabs %} In addition to this the response also contains: * `query` - details of the query in progress * `facts` - a list of facts extracted from the request data which provides real-time ability to validate the accuracy of extracted facts * `metadata` - API and request metadata ## Best Practice To optimise performance of /interact, it is recommended that the language used in the knowledge graph is reviewed in context of samples of the unstructured input. {% hint style="info" %} A useful exercise can be to consider whether someone with limited knowledge of the domain could be given sample input and the graph be able to successfully map data to the knowledge graph. {% endhint %} Relationships you want to query should be given names with similarity to the questions that will be asked. For example, a query of `Is Sarah be eligible for remortgage?` when the relationship is called `overall result` is unlikely to succeed. We are testing out functionality to tag relationships as queryable and to assign example questions to improve query detection, although there is no set release date. It is recommended to avoid 1st person queries such as `Am I eligible for a remortgage?` as the subject extracted for the query will be `I` . Although this can be done if the questions in the knowledge graph are designed with this in mind and it is understood the evidence tree will not reference the subject by name/ID. ## Integration Patterns These design patterns highlight different approaches to using interact:
Fully autonomous Where you expect to provide all data and be given a result. No human or AI agent in the loop and therefore question-asking is turned off in the knowledge graph. 1. Start session 2. Send data plus question (query) to /interact 3. Receive result 4. Optionally call /explain
Semi-autonomous Where your data is variable and you expect some straight-through processing, but anticipate some requests might require follow-up questions to route to a human or AI agent to answer. 1. Send data plus question to /interact 2. Receive result or question 1. in event of a question, send to human or AI agent or search a vector store to solicit answer 2. Reusing the Session ID post the answer to interact 3. Repeat until a result is provided 3. Optionally call the /explain endpoint
Interactive Where you expect a question to be ask and a consultation-style interaction to occur. 1. Start session 2. Ask question 3. Receive question 1. present to user to solicit answer 2. post response back via interact, using the same session ID 3. Repeat until a result is provided 4. Optionally call the /explain endpoint
Depending on the end-solution, a layer of middleware may be required to identify **when** to call Rainbird in the context of a message (e.g. a user message in a 3rd party agent) and which knowledge graph is most appropriate (if you have multiple). Within a session, you can also mix and match our core API and NL endpoints to combine structured queries, fact injection or question responses with unstructured queries or fact injection. ## Data Accuracy and Quality Control Our integration of knowledge graphs with LLMs provides several built-in safeguards to ensure data quality: ### Knowledge Graph Controls * Validates data against defined value ranges and relationships * Processes facts within established business rules * Returns null results for unrecognised values, preventing incorrect decisions ### Validation Tools * Review extracted facts in real-time via `/interact` * Trace decision paths through evidence trees * Verify data against your defined model These controls work together to maintain accuracy and we will continue improving our approaches. However whilst the risk is reduced, it's important to be aware inaccurate facts are still possible within the constraints of the knowledge graph. ## Important Information ### Data Security /interact uses third-party AI services (Anthropic hosted in AWS Bedrock). However this data will be encrypted in transit and at rest by AWS Bedrock and will not be used for training purposes. Data will be processed within the EU and continues to be ISO27001 compliant. Any request made via /interact shares the request and a subset of the knowledge graph with the LLM provider. ### System Parameters * One active query per session. Additional queries detected whilst a query is in progress will be ignored. Only when a query completes (result is provided) can further queries be made in the same session. * Facts cannot be updated, therefore user requests to change any previous statements is not possible. A new session must be established. * Token limits apply. For large content and/or large knowledge maps, limits may be reached and not all facts extracted. * Service may be interrupted during peak periods. * Varying behaviour: LLMs are not deterministic so you will likely see different responses when testing the same content. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.rainbird.ai/rainbird/developer-docs/api-guide/beta-apis/interact.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.