> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Palantir Foundry AIP Agents

> Connect Palantir Foundry AIP Chatbots to Openlayer for trace ingestion, evaluation, and monitoring

Openlayer connects to your [Palantir Foundry AIP Chatbots](https://www.palantir.com/docs/foundry/chatbot-studio/overview)
to ingest execution traces for online evaluations. AIP Chatbots were formerly called AIP Agents.

The integration polls a [Chatbot Studio session-log streaming dataset](https://www.palantir.com/docs/foundry/chatbot-studio/session-logging),
groups exported rows into complete executions, and writes them to the Openlayer projects linked to your
chatbots.

## How it works

Once connected, Openlayer:

1. **Discovers your chatbots** — walks Compass folders for AIP Chatbot files, or lets you register a
   chatbot by agent RID or filesystem path.
2. **Links Openlayer projects** — enabling a chatbot links it to an Openlayer project and inference
   pipeline. By default, Openlayer creates an LLM project named `Foundry AIP Agent - <name>`.
3. **Syncs executions** — periodic or manual sync polls the session-log stream and ingests completed
   executions for enabled chatbots whose `agent_rid` or `owning_rid` matches.
4. **Builds traces** — Openlayer groups rows by `traceId` and maps chat messages, tool calls, outputs, and
   errors into structured traces.

Unknown chatbots are dropped rather than registered automatically. Incomplete traces remain pending until
the stream includes a `final_response` or `execution_error`.

<Info>
  Cron sync uses the Chatbot Studio session-log dataset rather than AIP Agents
  v2 `listSessions`. That API only returns sessions for the calling user and
  originating client, so it does not expose Studio traffic from other users.
</Info>

***

## Prerequisites

Before connecting, you need:

* A Foundry enrollment with at least one AIP Chatbot.
* A bearer token or third-party application token with `api:aip-agents-read`,
  `api:filesystem-read`, and `api:streams-read`.
* An Org Admin-created Chatbot Studio session-log export using the **Palantir JSON** schema.
* An Openlayer workspace where you are an **admin**.

Your enrollment URL must use HTTPS and contain only the hostname, such as
`https://example.palantirfoundry.com`, with no path.

### Create the session-log export

As a Foundry Org Admin:

1. In **Control Panel**, select your organization.
2. Open **Log observability settings** and click **Create log export**.
3. Select the projects that contain the chatbots you want to monitor.
4. Choose the **Palantir JSON** schema and create the streaming dataset.
5. Copy the dataset RID. Allow up to five minutes for rows to appear.

<Warning>
  Markings are not inherited by the exported dataset. Prompts and user input can
  appear in the stream, so configure the export's projects and access controls
  appropriately.
</Warning>

Use Palantir JSON rather than OpenTelemetry protobuf for this integration.

***

## Set up the integration

### Step 1: Connect your enrollment

1. In Openlayer, go to **Settings → Integrations**.
2. Select **Palantir Foundry AIP Agents**.
3. Under **Connect**, enter:
   * **Enrollment URL** — your HTTPS Foundry enrollment hostname with no path.
   * **Bearer token** — a token with all three required scopes.
   * **Session-log dataset RID (optional)** — the RID from your Org Admin's log export.
   * **Stream branch** — the dataset branch, which defaults to `master`.
4. Click **Connect**.

Openlayer verifies the hostname and token before saving the connection.

<img width="700" style={{ borderRadius: "0.5rem" }} src="https://mintcdn.com/openlayer-44/p2Nha6ZfPRFIpGwK/images/integrations/palantir_foundry_hero.png?fit=max&auto=format&n=p2Nha6ZfPRFIpGwK&q=85&s=601eb239eebf1c13b03b597fe40e62fe" alt="Palantir Foundry connect" data-path="images/integrations/palantir_foundry_hero.png" />

<Note>
  You can connect without entering the dataset RID, but session-log sync fails
  with a configuration error until you add it under **Settings**.
</Note>

### Step 2: Discover or register chatbots

Click **Discover agents** to walk the Compass folders visible to your token for AIP Chatbot files. You can
also click **Register agent** and provide either:

* The agent RID from the Chatbot Studio URL.
* A Foundry filesystem path, such as `/Org/Project/My Agent`.

Discovery only finds Compass files with the `AIP_AGENTS_AGENT` type.

<img width="700" style={{ borderRadius: "0.5rem" }} src="https://mintcdn.com/openlayer-44/p2Nha6ZfPRFIpGwK/images/integrations/palantir_foundry_agents.png?fit=max&auto=format&n=p2Nha6ZfPRFIpGwK&q=85&s=e18017ea0c56ca4b49ffe54bad90996f" alt="Palantir Foundry agents" data-path="images/integrations/palantir_foundry_agents.png" />

### Step 3: Enable chatbots

Click **Enable** for each chatbot you want to monitor. Openlayer links a project and inference pipeline,
then starts ingesting matching executions. The **Agents** table shows each chatbot and its number of
imported sessions.

Enabled AIP Chatbot projects display a Foundry mark in the configured integrations and projects tables.

To stop ingesting future traces for a chatbot, open its **Agent options** menu and select **Disable**.
Existing traces remain available.

### Step 4: Configure sync

Under **Settings**, enter the **Session-log dataset RID** and **Stream branch**, then click **Save session
log**.

Turn on **Periodic sync** to poll the stream every 15 minutes, or click **Sync now** to queue a manual
sync. Periodic sync requires a dataset RID and the `api:streams-read` scope.

***

## Ingest a single session

The session-log stream is the primary sync source. If you have a gateway-originated session's three
identifiers, you can ingest that session directly:

1. Open the chatbot row's **Agent options** menu and select **Ingest**.
2. Enter the **Session RID** and **Session trace ID**. The agent RID is already known from the chatbot row.
3. Click **Ingest**.

This action uses `getSessionTrace` and only works when you have the IDs from the originating client.
Palantir documents that these sessions expire after approximately 24 hours.

***

## Trace mapping

Openlayer maps Palantir JSON session-log events as follows:

| Foundry event                                 | Openlayer trace data                                     |
| --------------------------------------------- | -------------------------------------------------------- |
| `session_metadata`                            | Root metadata, including agent, version, session, caller |
| `user_request`                                | Root input and retriever contexts                        |
| `system`, `user`, or `assistant_chat_message` | Chat completion spans                                    |
| `tool_call` and `tool_call_result`            | Tool spans                                               |
| `final_response`                              | Root output                                              |
| `execution_error`                             | Root error                                               |

Model, token, and cost data appear only when sibling language-model usage events share the same `traceId`.
Chatbot events do not always include these usage events.

<img width="700" style={{ borderRadius: "0.5rem" }} src="https://mintcdn.com/openlayer-44/p2Nha6ZfPRFIpGwK/images/integrations/palantir_foundry_trace.png?fit=max&auto=format&n=p2Nha6ZfPRFIpGwK&q=85&s=2f08e91c5e9e4cea0bdcb728abf0140f" alt="Palantir Foundry trace" data-path="images/integrations/palantir_foundry_trace.png" />

***

## Disconnecting

To disconnect, open **Settings → Integrations → Palantir Foundry AIP Agents** and click **Disconnect**.
Disconnecting stops session-log syncing and deletes registered agent records. Existing Openlayer traces
are preserved.

## Troubleshooting

**Sync fails with a missing dataset RID.**
Configure **Session-log dataset RID** under **Settings**. A Foundry Org Admin must create the export with
the Palantir JSON schema.

**No chatbots appear after discovery.**
Discovery only finds `AIP_AGENTS_AGENT` Compass files. Confirm that the token has
`api:filesystem-read` and can see the folders containing your chatbots. You can also register a chatbot
by RID or filesystem path.

**An enabled chatbot has zero traces.**
Confirm that the session-log export covers the chatbot's project, uses the Palantir JSON schema, and has
started receiving rows. The chatbot must be enabled, and executions remain pending until they include a
`final_response` or `execution_error`.

**A single-session ingest is not ready.**
Confirm that `getSessionTrace` reports a complete session and that you entered the correct session trace
ID. Path A sessions expire after approximately 24 hours.