# Use AIP Chatbots through Foundry APIs

To build applications on top of the Foundry platform, you can embed chatbots into your applications using the [Palantir APIs](../../api/v2/aip-agents-v2-resources/sessions/create-session/index.md).

## What can I do with the APIs?

Easily build multi-shot interactions with your chatbots over the API, using its options to:

* Start new conversations for a given task or context by [creating](../../api/v2/aip-agents-v2-resources/sessions/create-session/index.md) a new session with your chatbot.
* Orchestrate complex back-and-forth task prompts with the [streaming](../../api/v2/aip-agents-v2-resources/sessions/streaming-continue-session/index.md) or [blocking](../../api/v2/aip-agents-v2-resources/sessions/blocking-continue-session/index.md) APIs, with built-in state management to track these updates to your sessions for you.
* Provide custom application inputs to the chatbot through the options for application state in the API. These use the `parameter` previously used in Chatbot Studio, now available as Application state/variables. Use the `parameterInputs` field in requests to provide inputs. Use the `parameterUpdates` field for blocking responses (or [load the session exchange](../../api/v2/aip-agents-v2-resources/contents/get-content/index.md) after streaming) to read custom outputs.

For straightforward, single-use tasks that do not need extensive session management, consider using [chatbots as functions](../chatbots-as-functions/index.md). You can access a chatbot as a function from a third-party application using the Palantir OSDK.

## Deploy an AIP Chatbot to a Developer Console application

Once you have configured and published your AIP Chatbot, you can create and configure a Developer Console application to interact with your AIP Chatbot in a custom application.

To enable your Developer Console application to interact with your AIP Chatbot using [platform APIs](../../api/aip-agents-v2-resources/agents/agent-basics/index.md), follow the steps in [create a new Developer Console application](../../developer-console/create-application/index.md) to create a new SDK application with access to Platform SDK resources:

:::callout{theme="warning"}
To use an AIP Chatbot from an Ontology SDK application, you must configure the AIP Chatbot to only use object types, action types or function types from a single Ontology.
:::

1. On the **Resources** page, select the Ontology used by your AIP Chatbot, then select all object types, action types and function types used in your AIP Chatbot configuration. Ensure you select the types used for the application state and all tools and retrieval context configured for your AIP Chatbot.
2. Next, select the **Platform SDK** tab. Under **Projects access**, add the project containing your AIP Chatbot. To find the project for the AIP Chatbot, open the AIP Chatbot in Chatbot Studio and inspect the filesystem path details next to the AIP Chatbot's name in the header.
3. If your AIP Chatbot is configured to use any other filesystem resources, such as a media set for [document context](../retrieval-context/index.md#document-context), ensure these are in the same project as your AIP Chatbot, or add all additional projects for these resources to the **Projects access** section.

![Use the Platform SDK tab to add the project for your AIP Chatbot.](../../../assets/991b5ae938b37eb52cb314dd69494ecf5bd57047b7121ed47bf0d3eb8dd64a66.webp)

4. Finally, enable operations for the **AIP Chatbots API** in the **Client allowed operations** table. To check the operations required for the different AIP Chatbot platform APIs, refer to the [platform API](../../api/aip-agents-v2-resources/agents/agent-basics/index.md) documentation.

:::callout{theme="warning"}
To allow your Developer Console application to create and send messages in conversation sessions with an AIP Chatbot, you must enable the **AIP Chatbots write permission**.
:::

![Enable the AIP Chatbot API operations in the Client allowed operations table.](../../../assets/9be1c3fb3f9ea43f0255bfedf59e30551d9468a0c01620ff27f4ff2eda65927a.webp)

5. Refer to the [Developer Console](../../developer-console/create-application/index.md) documentation steps to review and finalize creation of your application.

### Update an AIP Chatbot used in Developer Console applications

Once you have configured a Developer Console application to allow interaction with an AIP Chatbot through **Platform SDK** resources, you will need to update the application if any of the Ontology or platform resources used by your AIP Chatbot are modified.

For example, if you add any new object types, action types or function types to the AIP Chatbot, you must add these to the **Ontology SDK** resources for your application in Developer Console. Similarly, if you add any platform resources to your AIP Chatbot, such as additional media sets for document context retrieval, you must add these to the **Platform SDK** resources for your application. Developer Console application resources *are not* updated automatically when changes occur to the types of resources used by your AIP Chatbot.

### Create conversations with AIP Chatbots in custom applications

To get started bootstrapping a new application, refer to the documentation examples for [TypeScript](../../developer-console/how-to-bootstrapping-typescript/index.md) or [Python](../../developer-console/how-to-bootstrapping-python/index.md), or [add the SDK to an existing application](../../developer-console/how-to-add-to-existing-typescript/index.md).

The **Sessions** APIs for AIP Chatbots require you to specify the `agentRid` for the AIP Chatbot to use for conversation session interactions.

You can find this by opening the project for your AIP Chatbot, selecting the AIP Chatbot and using the **Copy to clipboard** option for the RID under **Metadata** in the file overview.

![Copy the AIP Chatbot RID from the AIP Chatbot file details to use with the platform APIs.](../../../assets/8f25047fedd93514f74d566037dfb8b60c2a0fb022d60e4d9bcc7ce0d3ec4425.webp)

Once you have created your application, use the [Create Session](../../api/aip-agents-v2-resources/sessions/create-session/index.md) platform API to create a new conversation with your AIP Chatbot.

Once you have created a new session, use the `sessionRid` value in the returned response to send a new message to the AIP Chatbot and get responses using the [`Blocking continue session`](../../api/aip-agents-v2-resources/sessions/blocking-continue-session/index.md) or [`Streaming continue session`](../../api/aip-agents-v2-resources/sessions/streaming-continue-session/index.md) platform APIs. Use the blocking API to wait to receive the full AIP Chatbot response once it is fully generated, or use the streaming API to receive a stream of the AIP Chatbot's answer text as it is generated.

You can load conversation metadata for a session using the [`Get Session`](../../api/aip-agents-v2-resources/sessions/get-session/index.md) API, and load the history of exchanges (messages sent by your application and responses from the AIP Chatbot) for a session with the [`Get Content`](../../api/aip-agents-v2-resources/contents/get-content/index.md) API.

You can use the [`Get Session Trace`](../../api/v2/aip-agents-v2-resources/session-traces/get-session-trace/index.md) API to retrieve the sequence of steps taken by the AIP Chatbot, which can be useful for debugging or understanding the chatbot's reasoning process. The endpoint requires a `sessionTraceId` which you can obtain in two ways:

* For new exchanges:
  * Generate a random UUIDv4 to use as the `sessionTraceId` in the request to the [`Blocking continue session`](../../api/v2/aip-agents-v2-resources/sessions/blocking-continue-session/index.md) or [`Streaming continue session`](../../api/v2/aip-agents-v2-resources/sessions/streaming-continue-session/index.md) APIs. This option allows you to poll the ['Get Session Trace'](../../api/v2/aip-agents-v2-resources/session-traces/get-session-trace/index.md) API and see the real-time trace of the chatbot's answer generation.
  * Inspect the `sessionTraceId` field in the response from the [`Blocking continue session`](../../api/v2/aip-agents-v2-resources/sessions/blocking-continue-session/index.md) API.
* For existing exchanges:
  * Inspect the `sessionTraceId` field on the exchange results in the response from the [`Get Content`](../../api/v2/aip-agents-v2-resources/contents/get-content/index.md) API.

Refer to the platform API documentation for code examples on how to use these APIs in your target application language.