# CCPA
Source: https://docs.contextual.ai/admin-setup/ccpa





# GDPR
Source: https://docs.contextual.ai/admin-setup/gdpr





# HIPAA
Source: https://docs.contextual.ai/admin-setup/hipaa





# LLMs.txt
Source: https://docs.contextual.ai/admin-setup/llms-txt

Helping LLMs index Contextual AI content more efficiently

Contextual AI documentation is provided in the llms.txt format — a standardized, LLM-friendly structure that makes it easy for large language models to parse and reference.

## Available Formats

We provide two versions of our documentation:

* [llms.txt](/llms.txt): A concise overview containing brief descriptions of key features and direct links to detailed documentation sections.
* [llms-full.txt](/llms-full.txt): A comprehensive version that includes the same structure as llms.txt but with expanded details for each section.


# Overview
Source: https://docs.contextual.ai/admin-setup/overview

Everything You Need to Get Up & Running with Contextual AI

This section provides the core tools and guidance to configure, secure, and manage your Contextual AI environment. Start here to establish a reliable, governed foundation for building and running contextual AI workflows.

### [RBAC](/admin-setup/rbac)

Manage access with fine-grained, role-based permissions that control who can view, modify, and administer your Contextual AI resources. Use RBAC to enforce least privilege, streamline collaboration, and maintain strong governance across teams.

### [Pricing & Billing](/admin-setup/pricing-billing)

View and manage your organization’s subscription details, usage, and invoicing. This section explains how Contextual AI tracks consumption and helps you stay aligned with your plan as your workloads grow.

### [Security & Compliance](/admin-setup/soc2)

Learn how Contextual AI protects your data through enterprise-grade security controls, encryption, governance policies, and compliance certifications. This section outlines the safeguards that keep your contextual workloads secure and audit-ready.

### [LLMs.txt](/admin-setup/llms-txt)

Configure the `LLMs.txt` file to declare which models your organization uses, define model access rules, and ensure consistent behavior across environments. This section covers the file format, best practices, and how Contextual AI interprets these settings.


# Pricing & Billing
Source: https://docs.contextual.ai/admin-setup/pricing-billing

Pricing overview and how to manage billing in your workspace

## Pricing Overview

Contextual AI offers two pricing options:

* **On-Demand**: Pay-as-you-go pricing with \$25 in free credits to start. No commitments or minimums.
* **Enterprise**: Custom pricing with guaranteed throughput, SLAs, VPC deployment, and dedicated support.

We also offer **Component APIs** (Parse, Rerank, Generate, LMUnit) with usage-based pricing for teams integrating with existing architectures.

<Card title="View Full Pricing" icon="arrow-up-right-from-square" href="https://contextual.ai/pricing">
  See complete pricing details, feature comparison, and enterprise options
</Card>

***

## Managing Your Billing

### Monitoring Usage

To view your usage statistics:

1. Click on **Usage** in the sidebar

<img alt="" />

The usage page shows a month-by-month breakdown of your spend across components and endpoints.

<img alt="" />

### Adding Payment Methods

To link a payment method:

1. Navigate to the **Billing** page in your workspace
2. Click on **Payment Methods** in the **Learn More** section
3. Click the **+New** button
4. Fill out the card or bank information, then click **Next**
5. Fill out your billing address, then click **Save Payment Method**

<img alt="" />

To remove a payment method:

1. Locate it in the list of payment methods
2. Click the menu icon
3. Click **Remove Payment Method**

<img alt="" />

### Adding Credits

To top-up your credits:

1. Navigate to the **Billing** page in your workspace
2. Add a valid credit card under **Payment Methods** if you haven't already
3. Click **Add Credits** and fill out the form
4. Click **Next** and confirm the payment

<img alt="" />

***

<Info>For enterprise pricing or questions, contact [sales@contextual.ai](mailto:sales@contextual.ai)</Info>


# Role-Based Access Control (RBAC)
Source: https://docs.contextual.ai/admin-setup/rbac

Define custom roles and permission bundles across agents, datastores, and more.

*********Contextual AI is excited to introduce Role-Based Access Control (RBAC). RBAC is exclusive to customers on our Provisioned Throughput plan. Please contact your account team for more information.*********

Admins can now define custom roles with tailored permission bundles across key objects — including Agents, Datastores, Billing, and other administrative features. Permissions can be scoped to specific Agents or Datastores, enabling finer-grained governance so every team member has the right level of access for their role.

**Groups** make access management even simpler: add multiple users to a Group, then assign that Group to a Role.

## Roles

### Navigating to the Roles Page

First, click `Settings` under `Admin` in the side-panel.

<img alt="Screenshot 2025-11-12 at 2.23.28 PM.png" title="Screenshot 2025-11-12 at 2.23.28 PM.png" />

Next, click `Roles` under `Access Control`.

<img alt="Untitled 2.001.jpeg" />

### Default Roles

Your tenant comes with three default roles:

* `Admin`: Default role with full access to agents, datastores, and workspace settings.
* `User`: Default role that every new user is automatically assigned to. This role **does not** come with any access to agents or datastores.
* `Power User`: Default role that grants read access to all agents and datastores.

By default, all new users are given the `User` role. They won't be able to access agents or datastores until they’re assigned a Role with higher-level permissions.

<img alt="Screenshot 2025-11-12 at 4.00.25 PM.png" />

### Creating a Custom Role

You can create custom roles to meet your governance needs. Here are examples of custom roles you can create:

* **Billing Admin** – Access to billing and usage features
* **Data Ingestor** – Manage and ingest documents within specific Datastores
* **Agent User** – Query and interact with designated Agents
* **Agent Admin** – Maintain and optimize designated Agents

First, click "New Role" in the **Roles** page.

<img alt="Screenshot 2025-11-12 at 2.36.20 PM.png" />

Second, input a Role Name and Description. Click "Create role".

<img alt="Screenshot 2025-11-12 at 2.48.07 PM.png" />

### Configuring Role Permissions

After creating a Role, you will be automatically directed to the Role page. The first tab is for you to configure permissions. Click “Add Permission” to associate a permission with the Role.

<img alt="Screenshot 2025-11-12 at 2.49.20 PM.png" />

You will need to select what type of object you want to grant access to. You have three options:

* `Agents`: Select this to give permissions on an agent
* `Datastores`: Select this to give permissions on a Datastore
* `Admin Tools`: Select this to give access to admin functions like billing and [annotating feedback](/how-to-guides/feedback).

<img alt="Screenshot 2025-11-12 at 2.54.03 PM.png" />

You can then configure permissions relevant to the object type you selected.

#### Configuring Agent Permissions

On the left, you’ll see a **list of available permissions**. Each defines what actions the Role can take.

* `Query Agents`: This permission will let assigned users query the agent.
* `Manage Agents`: This permission will let assigned users query the agent and edit its configs. It is a superset of `Query Agents`.
* `Create Agents`: This permission will let assigned users create an agent.

On the **right**, you’ll see the **objects** these permissions apply to.

* For `Query Agents` and `Manage Agents`, you can select specific agents or select `All Agents`.
* The`Create Agents` permission will apply globally.

<img alt="Screenshot 2025-11-12 at 3.00.35 PM.png" />

<Note>
  **Important:** To query data from an agent’s linked datastores, a user must have both (i) `Query Agents` or `Manage Agents` and (ii) `Read Documents` (or higher) on the specific datastores. This ensures that when an agent is linked to multiple datastores, users can only query the ones they are permitted to access.

  Example:

  * `Agent_1` is linked to `Datastore_1` and `Datastore_2`.
  * The user has `Query Agents` on `Agent_1` and `Read Documents` on `Datastore_1` only.
  * As a result, only documents from `Datastore_1` will be retrieved.
</Note>

#### Configuring Datastore Permissions

On the left, you’ll see a **list of available permissions**. Each defines what actions the Role can take.

* `Read Documents`: This permission will let assigned users see the datastore and read documents inside.
* `Manage Documents`: This permission will let assigned users read documents, as well as upload/delete them. It is a superset of `Read Documents`.
* `Manage Datastores`: This permission will let assigned users manage documents, as well as edit the datastore configs. It is a superset of `Manage Documents`.
* `Create Datastores`: This permission will let assigned users create a datastore.

On the **right**, you’ll see the **objects** these permissions apply to.

* For `Read Documents` , `Manage Documents` and `Manage Datastores`, you can select specific datastores or select `All Datastores`.
* The`Create Datastores` permission will apply globally.

<img alt="Screenshot 2025-11-12 at 3.04.27 PM.png" />

<Note>
  **Important:** To query data from an agent’s linked datastores, a user must have both (i) `Query Agents` or `Manage Agents` and (ii) `Read Documents` (or higher) on the specific datastores. This ensures that when an agent is linked to multiple datastores, users can only query the ones they are permitted to access.
</Note>

#### Configuring Admin Permissions

On the left, you’ll see a **list of available permissions**. Each defines what actions the Role can take.

* `Create Agents`: This permission will let assigned users create an agent.
* `Create Datastores`: This permission will let assigned users create a datastore.
* `Manage Billing & Usage`: This permission will let assigned users view and configure the `Billing` page.
* `Manage Feedback Annotation`: This permission will let assigned users [view and annotate agent-level feedback](/how-to-guides/feedback).

All these permissions apply globally.

<img alt="Screenshot 2025-11-12 at 3.11.26 PM.png" />

### Review your Permissions

Review all the permissions that you have provisioned for the Role. You can add more permissions or remove existing ones by clicking on the three dots beside each permission and clicking "Remove".

<img alt="Screenshot 2025-11-12 at 3.13.23 PM.png" />

### Assigning a User to a Role

To assign a user to the Role, click the `Assigned Users` tab in the Roles Page.

<img alt="Screenshot 2025-11-12 at 3.14.24 PM.png" />

Next, click "Assign Users". You'll be able to select multiple users to add to the role. Click "Confirm".

<img alt="Screenshot 2025-11-12 at 3.15.16 PM.png" title="Screenshot 2025-11-12 at 3.15.16 PM.png" />

Third, review the users you've added. You can add more users or remove existing ones by clicking on the three dots beside a user and clicking "Remove".

<img alt="Screenshot 2025-11-12 at 3.16.16 PM.png" />

**You’re all set!** The assigned users now have the access defined in this Role.

### Dealing with Role Conflicts

If a user is assigned to two roles with different permissions on the same object, we will take the **union of permissions**. Example:

* User is assigned to `Role A` which is given `Query Agents` on `All Agents`
* User is also assigned to `Role B` which is given the higher-level `Manage Agents` on `Agent A`.
* Outcome:
  * User will have `Manage Agents` on `Agent A`
  * User will have `Query Agents` on every other agent.

### Managing Roles

After creating a Role, you can return to its configuration page at any time. To do so, navigate to the **Roles** page and click on the Role you want to edit.

<img alt="Screenshot 2025-11-12 at 3.30.02 PM.png" />

You can also delete a Role by clicking on the three dots beside it and clicking "Delete".

<img alt="Screenshot 2025-11-12 at 3.26.12 PM.png" />

### Creating Agents and Datastores

If a user has created an Agent or Datastore, an owner Role will automatically be created with `Manage Agent` or `Manage Datastore` permissions. The user will automatically be assigned to that Role.

<img alt="Screenshot 2025-11-12 at 3.45.49 PM.png" />

## Groups

### Navigating to the Groups page

Groups can help simplify access management. You can add multiple users to a Group and assign the Group to a Role.

First, click `Settings` under `Admin` in the side-panel.

<img alt="Screenshot 2025-11-12 at 2.23.28 PM.png" title="Screenshot 2025-11-12 at 2.23.28 PM.png" />

Next, click "Groups" under "Access Control".

<img alt="Untitled 4.001.jpeg" />

### Creating a Group

Click "New Group".

<img alt="Screenshot 2025-11-12 at 3.36.38 PM.png" />

Fill in Group Name and Description

<img alt="Screenshot 2025-11-12 at 3.37.52 PM.png" />

Click "Create group". You'll be automatically redirected to the Group page.

### Assigning Users to the Group

Click the tab "Assigned Users".

<img alt="Screenshot 2025-11-12 at 3.40.01 PM.jpg" />

Click "Assign Users" and select the users you want to include in the Group. Click "Confirm".

<img alt="Screenshot 2025-11-12 at 3.39.02 PM.png" title="Screenshot 2025-11-12 at 3.39.02 PM.png" />

Review the users you have added. You can add more users to the Group or remove existing users by clicking the three dots and clicking "Remove".

<img alt="Screenshot 2025-11-12 at 3.39.32 PM.png" />

### Associating a Group with a Role

Navigate to the first tab: "Roles".

<img alt="Screenshot 2025-11-12 at 3.43.47 PM.png" />

Click "Add Roles".

You can select roles to associate with your Group.

<img alt="Screenshot 2025-11-12 at 3.41.42 PM.png" title="Screenshot 2025-11-12 at 3.41.42 PM.png" />

Click "Add Roles". You can add more roles or remove existing ones by clicking on the three dots and clicking "Remove".

<img alt="Screenshot 2025-11-12 at 3.46.40 PM.png" />

**You're set!** Members of the Group now have have the access defined in the attached Roles.

### Managing a Group

After creating a Group, you can return to its configuration page at any time. To do so, navigate to the **Groups** page and click on the Group you want to edit.

<img alt="Screenshot 2025-11-12 at 3.48.21 PM.png" />

You can also delete a Group by clicking on the three dots beside it and clicking "Delete".

<img alt="Screenshot 2025-11-12 at 3.48.37 PM.png" />

## User Management

You can view the roles and groups associated with each user.

First, navigate to `Members` in the `Access Control` tab. You will see the list of members in your workspace.

<img alt="Screenshot 2025-11-24 at 11.53.27 AM.png" />

To see the **roles** assigned to the user, click the `Expand` button in the `Roles` column. You will see (i) the assigned roles, (ii) the permissions included in each role, and (iii) whether it was assigned directly to the user or inherited via group membership. You can also open up the Role Page with the top-left button.

<img alt="Screenshot 2025-11-24 at 11.57.04 AM.png" />

To see the **groups** that the user belongs to, click the `Expand` button in the `Groups` column.  You will see (i) the user's groups and (ii) the roles associated with each group. You can also open up the Group Page with the top-left button.

<img alt="Screenshot 2025-11-24 at 12.03.25 PM.png" />


# SOC 2
Source: https://docs.contextual.ai/admin-setup/soc2

Contextual AI SOC 2 Compliance

## Overview

Contextual AI is **SOC 2 Type II certified**, demonstrating that our security controls and operational practices meet the highest standards for protecting enterprise data.

![Alt Text](https://cdn.sanity.io/images/aw1pcv4c/production/1676425030178745ab94dfe0a96604369d93aa9b-5760x3240.png?w=3840\&fm=webp\&q=75\&dpr=2)

This certification verifies that our systems, processes, and safeguards operate effectively over time—not just at a single point of audit.

***

## What SOC 2 Type II Means

SOC 2 Type II evaluates how well an organization upholds the **Trust Service Criteria**:

* **Security**
* **Availability**
* **Confidentiality**

An independent auditor verified that Contextual AI maintains strong, continuously monitored controls across all three criteria.

***

## Security at Every Layer

### Proven Security Controls

Our compliance audit confirms consistent adherence to stringent policies and processes governing data handling, infrastructure, and operations.

### Data Protection

* **Encryption in transit:** TLS 1.2+
* **Encryption at rest:** AES-256
* **Key management:** Cloud-native KMS services with restricted access

### Deployment Options

Choose the environment that fits your organization’s security posture:

* **SaaS** (fully managed)
* **VPC** (private cloud)
* **On-premises** (self-managed)

### Authentication & Access

* Enterprise **SSO** with **SAML** or **OIDC**
* **Role-based access control (RBAC)** for fine-grained permissions

***

## Core Security Controls

| Category                  | Description                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------- |
| **Application Security**  | Continuous SAST/SCA scanning, dependency monitoring, and vulnerability management              |
| **Business Continuity**   | Kubernetes-based orchestration, automated failover, distributed infrastructure                 |
| **Monitoring & Response** | Real-time detection via centralized security data lake and defined incident-response playbooks |
| **Bug Bounty Program**    | Ongoing responsible-disclosure program with independent security researchers                   |

***

## Continuous Compliance

* SOC 2 Type II is one component of our broader compliance framework.
* Contextual AI is hosted on **Google Cloud Platform**, which maintains its own certifications: SOC 2, SOC 3, PCI DSS, ISO/IEC 27017, and CSA STAR.
* We continuously evaluate and update controls to address evolving security and privacy requirements for enterprise AI systems.

***

## Learn More

* [SOC 2 Announcement](https://contextual.ai/blog/contextual-ai-is-soc-2-type-2-certified)
* [Security Overview](https://contextual.ai/security)
* [Trust Center](https://trust.contextual.ai/resources) – Request a copy of our SOC 2 Type II report
* [Contact Support](https://contextual.ai/contact-us) for compliance or security-related inquiries


# Get Metrics
Source: https://docs.contextual.ai/api-reference/agents-query/get-metrics

/api-reference/openapi.json get /agents/{agent_id}/metrics
Returns usage and user-provided feedback data. This information can be used for data-driven improvements and optimization.



# Get Retrieval Info
Source: https://docs.contextual.ai/api-reference/agents-query/get-retrieval-info

/api-reference/openapi.json get /agents/{agent_id}/query/{message_id}/retrieval/info
Return metadata of the contents used to generate the response for a given message.



# Provide Feedback
Source: https://docs.contextual.ai/api-reference/agents-query/provide-feedback

/api-reference/openapi.json post /agents/{agent_id}/feedback
Provide feedback for a generation or a retrieval. Feedback can be used to track overall `Agent` performance through the `Feedback` page in the Contextual UI, and as a basis for model fine-tuning.



# Query
Source: https://docs.contextual.ai/api-reference/agents-query/query

/api-reference/openapi.json post /agents/{agent_id}/query/acl
Start a conversation with an `Agent` and receive its generated response, along with relevant retrieved data and attributions.



# Query
Source: https://docs.contextual.ai/api-reference/agents-query/query-1

/api-reference/openapi.json post /agents/{agent_id}/query
Start a conversation with an `Agent` and receive its generated response, along with relevant retrieved data and attributions.



# Copy Agent
Source: https://docs.contextual.ai/api-reference/agents/copy-agent

/api-reference/openapi.json post /agents/{agent_id}/copy
Copy an existing agent with all its configurations and datastore associations. The copied agent will have "[COPY]" appended to its name.



# Create Agent
Source: https://docs.contextual.ai/api-reference/agents/create-agent

/api-reference/openapi.json post /agents
Create a new `Agent` with a specific configuration.

This creates a specialized RAG `Agent` which queries over one or multiple `Datastores` to retrieve relevant data on which its generations are grounded.

Retrieval and generation parameters are defined in the provided `Agent` configuration.

> Note that self-serve users are currently required to create agents through our UI. Otherwise, they will receive the following message: "This endpoint is disabled as you need to go through checkout. Please use the UI to make this request."



# Delete Agent
Source: https://docs.contextual.ai/api-reference/agents/delete-agent

/api-reference/openapi.json delete /agents/{agent_id}
Delete a given `Agent`. This is an irreversible operation.

Note: `Datastores` which are associated with the `Agent` will not be deleted, even if no other `Agent` is using them. To delete a `Datastore`, use the `DELETE /datastores/{datastore_id}` API.



# Edit Agent
Source: https://docs.contextual.ai/api-reference/agents/edit-agent

/api-reference/openapi.json put /agents/{agent_id}
Modify a given `Agent` to utilize the provided configuration.

Fields not included in the request body will not be modified.



# Get Agent Metadata
Source: https://docs.contextual.ai/api-reference/agents/get-agent-metadata

/api-reference/openapi.json get /agents/{agent_id}/metadata
Get metadata and configuration of a given `Agent`.



# Get Template Configuration
Source: https://docs.contextual.ai/api-reference/agents/get-template-configuration

/api-reference/openapi.json get /agents/templates/{template}



# List Agent Composer Templates
Source: https://docs.contextual.ai/api-reference/agents/list-agent-composer-templates

/api-reference/openapi.json get /agents/templates/acl
Retrieve a list of all available Agent Composer Templates.



# List Agents
Source: https://docs.contextual.ai/api-reference/agents/list-agents

/api-reference/openapi.json get /agents
Retrieve a list of all `Agents`.



# List Templates
Source: https://docs.contextual.ai/api-reference/agents/list-templates

/api-reference/openapi.json get /agents/templates
Retrieve a list of all available Templates.



# Reset Agent
Source: https://docs.contextual.ai/api-reference/agents/reset-agent

/api-reference/openapi.json put /agents/{agent_id}/reset
Reset a given `Agent` to default configuration.



# Save Template
Source: https://docs.contextual.ai/api-reference/agents/save-template

/api-reference/openapi.json post /agents/{agent_id}/template



# Get Agent Composer Step Usage
Source: https://docs.contextual.ai/api-reference/billing/get-agent-composer-step-usage

/api-reference/openapi.json get /billing/usages/acl
Get Agent Composer step-level usage data for a specific month.

This API returns daily usages of advance queries grouped by steps. The data is used for visualization purposes to show users which Agent Composer steps were executed and their associated costs and token consumption.

Note: The costs returned here are already included in the ACL_COST entry from the daily_usages table and should not be double-counted in billing.

Args: request: Request object containing year, month, and optional resource_id user_context: User context with tenant admin permissions

Returns: Agent Composer step usage data aggregated by step and date



# Get Balance
Source: https://docs.contextual.ai/api-reference/billing/get-balance

/api-reference/openapi.json get /billing/balance
Get the remaining balance for a tenant



# Get Billing Metadata
Source: https://docs.contextual.ai/api-reference/billing/get-billing-metadata

/api-reference/openapi.json get /billing/metadata
Non admin endpoint for getting the billing metadata for a tenant.



# Get Billing Mode History
Source: https://docs.contextual.ai/api-reference/billing/get-billing-mode-history

/api-reference/openapi.json get /billing/billing_mode/history
Get the billing mode history for a tenant for a specific month.

Args: request: Request object containing year and month with validation user_context: User context with tenant admin permissions

Returns: Billing mode history records for the specified month and year Returns at least one entry which is the mode of the first date of the given month, with potential mode changes in the middle of the month. If no record found, defaults to LEGACY mode.



# Get Earliest Usage Date Endpoint
Source: https://docs.contextual.ai/api-reference/billing/get-earliest-usage-date-endpoint

/api-reference/openapi.json get /billing/usages/earliest_date
Get the earliest usage date for a tenant



# Get Monthly Usage Endpoint
Source: https://docs.contextual.ai/api-reference/billing/get-monthly-usage-endpoint

/api-reference/openapi.json get /billing/usages/monthly
Get monthly usage data for a tenant with validation for year and month parameters.

Args: request: Request object containing year and month with validation user_context: User context with tenant admin permissions resource_id: Optional[UUID]. If provided, get usage data for a specific resource. Otherwise, get aggregated usage data across all resources.

Returns: Monthly usage records for the specified month and year



# Get Top Up History Endpoint
Source: https://docs.contextual.ai/api-reference/billing/get-top-up-history-endpoint

/api-reference/openapi.json get /billing/balance/top-ups
Get the top-up history for a tenant. Paginated.



# Get Content Metadata
Source: https://docs.contextual.ai/api-reference/contents/get-content-metadata

/api-reference/openapi.json get /datastores/{datastore_id}/contents/{content_id}/metadata



# Get Document Contents
Source: https://docs.contextual.ai/api-reference/contents/get-document-contents

/api-reference/openapi.json get /datastores/{datastore_id}/contents



# Delete Document
Source: https://docs.contextual.ai/api-reference/datastores-documents/delete-document

/api-reference/openapi.json delete /datastores/{datastore_id}/documents/{document_id}
Delete a given document from its `Datastore`. This operation is irreversible.



# Edit Chunk Content
Source: https://docs.contextual.ai/api-reference/datastores-documents/edit-chunk-content

/api-reference/openapi.json put /datastores/{datastore_id}/chunks/{content_id}/content
Edit the content of a specific chunk in a datastore. This operation updates the chunk's text content and regenerates its embeddings.



# Get Document Metadata
Source: https://docs.contextual.ai/api-reference/datastores-documents/get-document-metadata

/api-reference/openapi.json get /datastores/{datastore_id}/documents/{document_id}/metadata
Get details of a given document, including its `name` and ingestion job `status`.



# Get Parse Results
Source: https://docs.contextual.ai/api-reference/datastores-documents/get-parse-results

/api-reference/openapi.json get /datastores/{datastore_id}/documents/{document_id}/parse
Get the parse results that are generated during ingestion for a given document. Retrieving parse results for existing documents ingested before the release of this endpoint is not supported and will return a 404 error.



# Ingest Document
Source: https://docs.contextual.ai/api-reference/datastores-documents/ingest-document

/api-reference/openapi.json post /datastores/{datastore_id}/documents
Ingest a document into a given `Datastore`.

Ingestion is an asynchronous task. Returns a document `id` which can be used to track the status of the ingestion job through calls to the `GET /datastores/{datastore_id}/documents/{document_id}/metadata` API.

This `id` can also be used to delete the document through the `DELETE /datastores/{datastore_id}/documents/{document_id}` API.

`file` must be a PDF, HTML, DOC(X), PPT(X), PNG, JPG, or JPEG file. The filename must end with one of the following extensions: `.pdf`, `.html`, `.htm`, `.mhtml`, `.doc`, `.docx`, `.ppt`, `.pptx`, `.png`, `.jpg`, `.jpeg`.



# List Documents
Source: https://docs.contextual.ai/api-reference/datastores-documents/list-documents

/api-reference/openapi.json get /datastores/{datastore_id}/documents
Get list of documents in a given `Datastore`, including document `id`, `name`, and ingestion job `status`.

Performs `cursor`-based pagination if the number of documents exceeds the requested `limit`. The returned `cursor` can be passed to the next `GET /datastores/{datastore_id}/documents` call to retrieve the next set of documents.



# Update Document Metadata
Source: https://docs.contextual.ai/api-reference/datastores-documents/update-document-metadata

/api-reference/openapi.json put /datastores/{datastore_id}/documents/{document_id}/metadata
Post details of a given document that will enrich the chunk and be added to the context or just for filtering. If Just for filtering, start with "_" in the key.



# Create Datastore
Source: https://docs.contextual.ai/api-reference/datastores/create-datastore

/api-reference/openapi.json post /datastores
Create a new `Datastore`.

A `Datastore` is a collection of documents. Documents can be ingested into and deleted from a `Datastore`.

A `Datastore` can be linked to one or more `Agents`, and conversely, an `Agent` can be associated with one or more `Datastores` to ground its responses with relevant data. This flexible many-to-many relationship allows `Agents` to draw from multiple sources of information. This linkage of `Datastore` to `Agent` is done through the `Create Agent` or `Edit Agent` APIs.

> Note that self-serve users are currently required to create datastores through our UI. Otherwise, they will receive the following message: "This endpoint is disabled as you need to go through checkout. Please use the UI to make this request."



# Delete Datastore
Source: https://docs.contextual.ai/api-reference/datastores/delete-datastore

/api-reference/openapi.json delete /datastores/{datastore_id}
Delete a given `Datastore`, including all the documents ingested into it. This operation is irreversible.

This operation will fail with status code 400 if there is an active `Agent` associated with the `Datastore`.



# Edit Datastore Configuration
Source: https://docs.contextual.ai/api-reference/datastores/edit-datastore-configuration

/api-reference/openapi.json put /datastores/{datastore_id}



# Get Datastore Metadata
Source: https://docs.contextual.ai/api-reference/datastores/get-datastore-metadata

/api-reference/openapi.json get /datastores/{datastore_id}/metadata
Get the details of a given `Datastore`, including its name, create time, and the list of `Agents` which are currently configured to use the `Datastore`.



# List Datastores
Source: https://docs.contextual.ai/api-reference/datastores/list-datastores

/api-reference/openapi.json get /datastores
Retrieve a list of `Datastores`.

Performs `cursor`-based pagination if the number of `Datastores` exceeds the requested `limit`. The returned `cursor` can be passed to the next `GET /datastores` call to retrieve the next set of `Datastores`.



# Reset Datastore
Source: https://docs.contextual.ai/api-reference/datastores/reset-datastore

/api-reference/openapi.json put /datastores/{datastore_id}/reset
Reset the give `Datastore`. This operation is irreversible and it deletes all the documents associated with the datastore.



# Create Schema
Source: https://docs.contextual.ai/api-reference/extract/create-schema

/api-reference/openapi.json post /extract/schemas
Create a new extraction schema.

Creates a JSON Schema that defines the structure of data to extract from documents. The schema must conform to our supported subset of JSON Schema 2020-12 features.

Supported Schema Features:

Basic Types:

1. `string`: Text data with optional constraints (`minLength`, `maxLength`, `pattern`, `enum`)
2. `integer`: Whole numbers with optional constraints (`minimum`, `maximum`, `enum`)
3. `number`: Decimal numbers with optional constraints (`minimum`, `maximum`, `enum`)
4. `boolean`: True/false values
5. `null`: Null values (often used with `anyOf` for optional fields)

Complex Types:

1. `object`: Key-value pairs with defined properties
2. `array`: Lists of items with defined item schemas
3. `anyOf`: Union types (e.g., string or null for optional fields)

String Formats:

Supported formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, `uuid`, `uri`

Schema Structure:

1. Root schema must be an `object` type
2. Use `$defs` for reusable schema components
3. Use `$ref` to reference definitions
4. Arrays must have `items` schema defined

Constraints:

1. Maximum 10 leaf nodes per array (prevents overly complex schemas)
2. No circular references in `$ref` definitions
3. String formats must be from the supported list

Example Schemas:

Simple Company Schema:
```json
{
  "type": "object",
  "properties": {
    "company_name": {
      "type": "string",
      "description": "The name of the company exactly as it appears in the document"
    },
    "form_type": {
      "type": "string",
      "enum": ["10-K", "10-Q", "8-K", "S-1"],
      "description": "The type of SEC form"
    },
    "trading_symbol": {
      "type": "string",
      "description": "The trading symbol of the company"
    },
    "zip_code": {
      "type": "integer",
      "description": "The zip code of the company headquarters"
    }
  },
  "required": ["company_name", "form_type", "trading_symbol", "zip_code"]
}
```

Complex Resume Schema:
```json
{
  "type": "object",
  "properties": {
    "personalInfo": {
      "type": "object",
      "properties": {
        "fullName": {"type": "string"},
        "contact": {
          "type": "object",
          "properties": {
            "emails": {
              "type": "array",
              "items": {"type": "string", "format": "email"}
            },
            "phones": {
              "type": "array",
              "items": {"type": "string"}
            }
          }
        }
      },
      "required": ["fullName"]
    },
    "workExperience": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "jobTitle": {"type": "string"},
          "company": {"type": "string"},
          "startDate": {"type": "string"},
          "endDate": {"type": ["string", "null"]},
          "isCurrent": {"type": "boolean"}
        },
        "required": ["jobTitle", "company", "startDate"]
      }
    }
  },
  "required": ["personalInfo", "workExperience"]
}
```

Schema with References:
```json
{
  "type": "object",
  "properties": {
    "algorithms": {
      "type": "array",
      "items": {"$ref": "#/$defs/algorithm"}
    }
  },
  "$defs": {
    "algorithm": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "description": {"type": "string"}
      },
      "required": ["name"]
    }
  }
}
```

Best Practices:

1. Use descriptive field names that clearly indicate what data should be extracted
2. Add detailed descriptions to help the AI understand what to extract
3. Use `enum` for known values (e.g., form types, status values)
4. Make fields optional by using `anyOf` with `null` or omitting from `required`
5. Use arrays for lists of similar items (e.g., work experience, education)
6. Keep schemas focused - avoid overly complex nested structures
7. Test with sample documents to ensure the schema captures the expected data



# Delete Document
Source: https://docs.contextual.ai/api-reference/extract/delete-document

/api-reference/openapi.json delete /extract/documents/{document_id}
Delete a document.



# Delete Schema
Source: https://docs.contextual.ai/api-reference/extract/delete-schema

/api-reference/openapi.json delete /extract/schemas/{schema_id}
Delete a schema.



# Get Document
Source: https://docs.contextual.ai/api-reference/extract/get-document

/api-reference/openapi.json get /extract/documents/{document_id}
Get document information by ID.



# Get Job Results
Source: https://docs.contextual.ai/api-reference/extract/get-job-results

/api-reference/openapi.json get /extract/jobs/{job_id}/results
Get the results of a completed extraction job.



# Get Job Status
Source: https://docs.contextual.ai/api-reference/extract/get-job-status

/api-reference/openapi.json get /extract/jobs/{job_id}
Get the status of an extraction job.

For running jobs with a Temporal workflow, returns accumulated results and failed subtrees from workflow queries. For completed/failed jobs or jobs without workflow, these fields are empty.



# Get Schema
Source: https://docs.contextual.ai/api-reference/extract/get-schema

/api-reference/openapi.json get /extract/schemas/{schema_id}
Get schema information by ID.



# List Documents
Source: https://docs.contextual.ai/api-reference/extract/list-documents

/api-reference/openapi.json get /extract/documents
List documents for structured extraction.



# List Jobs
Source: https://docs.contextual.ai/api-reference/extract/list-jobs

/api-reference/openapi.json get /extract/jobs
List extraction jobs.



# List Schemas
Source: https://docs.contextual.ai/api-reference/extract/list-schemas

/api-reference/openapi.json get /extract/schemas
List schemas with optional search.



# Resume Streaming Extraction
Source: https://docs.contextual.ai/api-reference/extract/resume-streaming-extraction

/api-reference/openapi.json get /extract/jobs/{job_id}/stream
Resume streaming events for an existing extraction job.

This endpoint:
1. Validates the job exists and is still processing
2. Queries Temporal workflow for current state (accumulated_results)
3. Sends current state as initial event
4. Streams new events going forward



# Start Extraction Job
Source: https://docs.contextual.ai/api-reference/extract/start-extraction-job

/api-reference/openapi.json post /extract/jobs
Start a new structured extraction job.

Extracts structured data from a PDF document using AI models based on a JSON Schema. The `document_id` and `schema_id` must be valid UUIDs of previously uploaded documents and created schemas.

How It Works:

1. Document Processing: The system analyzes the PDF document and splits it into manageable sections
2. Schema Analysis: Your JSON schema is parsed and validated for supported features
3. Extraction: The pipeline processes each section and extracts data according to your schema
4. Validation: Extracted data is validated against your schema to ensure constraints and requirements are met
5. Results: Structured data is returned in the format defined by your schema

Supported Models:

1. `gemini-2.5-flash`: Fast, cost-effective model for most use cases (default)
2. `gemini-2.5-pro`: More powerful model for complex extractions

Configuration Options:

Basic Settings:

1. `model`: AI model to use for extraction
2. `max_num_concurrent_requests`: Number of parallel processing requests (1-20)
3. `validate_response_schema`: Whether to validate extracted data against schema

Advanced Settings:

1. `per_key_attribution`: Enable detailed reasoning and confidence scores for each field
2. `temperature`: Control randomness in AI responses (0.0-2.0)
3. `seed`: Set random seed for reproducible results
4. `enable_thinking`: Show AI reasoning process
5. `n_max_retries`: Maximum retry attempts for failed requests

Streaming Mode (`stream=true`):

When `stream=true`, the endpoint returns an SSE stream instead of a job ID. Results are streamed as subtrees complete, enabling real-time progress visibility in the frontend.

- Response: SSE stream (`text/event-stream`) with events: `start`, `subtree_result`, `subtree_error`, `agentic_array_progress`
- Job records are still created and results persisted (retrievable via `GET /jobs/{job_id}`)
- Always durable: Uses Temporal workflow—job continues running even if client disconnects
- Automatic retries: Temporal handles activity failures and retries automatically
- Use case: Interactive frontend UI where users want real-time extraction progress

SSE Event Types:

1. `start`: Emitted once with `job_id`, `total_subtrees`, and `start_time`
2. `subtree_result`: Emitted per successful subtree with `extracted_result`, `attributions`, `usage_metadata`
3. `subtree_error`: Emitted per failed subtree with `error_message` and `error_type`

See `STREAMING-DESIGN.md` for full protocol specification.

Job Lifecycle:

1. `pending`: Job is queued and waiting to start
2. `processing`: AI is actively extracting data from the document
3. `completed`: Extraction finished successfully with results
4. `failed`: Extraction failed due to an error
5. `cancelled`: Job was cancelled before completion

Monitoring Progress:

Use the `GET /jobs/{job_id}` endpoint to check job status and progress:

1. `completion_percentage`: Overall progress (0-100)
2. `current_step`: Current processing stage
3. `fields_processed`: Number of schema fields completed
4. `total_fields`: Total number of schema fields to process

Getting Results:

Once a job is completed, use `GET /jobs/{job_id}/results` to retrieve:

1. `results`: Extracted data conforming to your schema
2. `metadata`: Processing information, costs, and performance metrics
3. `attributions`: (if enabled) Reasoning and confidence scores for each field

Example Request:
```json
{
  "document_id": "123e4567-e89b-12d3-a456-426614174000",
  "schema_id": "987fcdeb-51a2-43d1-b456-426614174000",
  "config": {
    "model": "gemini-2.5-flash",
    "per_key_attribution": true,
    "temperature": 0.1,
    "enable_thinking": true
    "additional_instructions": "Extract information only about company X. Do not include information about company Y."
  }
}
```

Example Response:
```json
{
  "job_id": "456e7890-e89b-12d3-a456-426614174000",
  "status": "pending",
  "created_at": "2025-01-11T18:35:00Z",
  "estimated_completion": "2025-01-11T18:40:00Z"
}
```

Error Handling:

Document and schema validation occurs before job creation for both streaming and non-streaming paths:

- `400`: Bad Request (invalid `document_id` or `schema_id` format)
- `404`: Not Found (document or schema not found)
- `422`: Unprocessable Entity (invalid schema definition)
- `429`: Too Many Requests (user has exceeded concurrency limit of 5 active jobs)
- `500`: Internal Server Error (processing error)



# Update Job Results
Source: https://docs.contextual.ai/api-reference/extract/update-job-results

/api-reference/openapi.json put /extract/jobs/{job_id}/results
Update the results of a completed extraction job.



# Update Schema
Source: https://docs.contextual.ai/api-reference/extract/update-schema

/api-reference/openapi.json put /extract/schemas/{schema_id}
Update an existing schema.



# Upload Document
Source: https://docs.contextual.ai/api-reference/extract/upload-document

/api-reference/openapi.json post /extract/documents/upload
Upload a document for structured extraction.

Uploads a PDF document that can be used for structured data extraction. Only PDF files are supported.

Supported File Types:

1. PDF files only (`.pdf` extension)
2. Maximum file size: 50MB (recommended)
3. Documents are processed and validated upon upload

Document Processing:

1. File size and page count are automatically calculated
2. Document is validated for PDF format and readability
3. Metadata is extracted and stored for future reference
4. Document is stored securely and can be referenced by ID

Usage:

After uploading, you'll receive a `document_id` that can be used with:

1. `POST /jobs` endpoint to start extraction jobs
2. `GET /documents/{document_id}` to retrieve document information
3. `DELETE /documents/{document_id}` to remove the document

Example Response:
```json
{
  "document_id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "financial_report.pdf",
  "file_size": 2048576,
  "page_count": 45,
  "uploaded_at": "2025-01-11T18:35:00Z",
  "status": "uploaded"
}
```



# Generate
Source: https://docs.contextual.ai/api-reference/generate/generate

/api-reference/openapi.json post /generate
Generate a response using Contextual's Grounded Language Model (GLM), an LLM engineered specifically to prioritize faithfulness to in-context retrievals over parametric knowledge to reduce hallucinations in Retrieval-Augmented Generation and agentic use cases.

The total request cannot exceed 32,000 tokens.

See our [blog post](https://contextual.ai/blog/introducing-grounded-language-model/) and [code examples](https://colab.research.google.com/github/ContextualAI/examples/blob/main/03-standalone-api/02-generate/generate.ipynb). Email [glm-feedback@contextual.ai](mailto:glm-feedback@contextual.ai) with any feedback or questions.



# LMUnit
Source: https://docs.contextual.ai/api-reference/lmunit/lmunit

/api-reference/openapi.json post /lmunit
Given a `query`, `response`, and a `unit_test`, return the response's `score` on the unit test on a 5-point continuous scale. The total input cannot exceed 7000 tokens.

See a code example in [our blog post](https://contextual.ai/news/lmunit/). Email [lmunit-feedback@contextual.ai](mailto:lmunit-feedback@contextual.ai) with any feedback or questions.

>🚀 Obtain an LMUnit API key by completing [this form](https://contextual.ai/request-lmunit-api/)



# Parse File
Source: https://docs.contextual.ai/api-reference/parse/parse-file

/api-reference/openapi.json post /parse
Parse a file into a structured Markdown and/or JSON. Files must be less than 300MB and 2000 pages. We use LibreOffice to convert DOC(X) and PPT(X) files to PDF, which may affect page count.

See our [blog post](https://contextual.ai/blog/document-parser-for-rag) and [code examples](https://github.com/ContextualAI/examples/blob/main/03-standalone-api/04-parse/parse.ipynb). Email [parse-feedback@contextual.ai](mailto:parse-feedback@contextual.ai) with any feedback or questions.



# Parse List Jobs
Source: https://docs.contextual.ai/api-reference/parse/parse-list-jobs

/api-reference/openapi.json get /parse/jobs
Get list of parse jobs, sorted from most recent to oldest.

Returns all jobs from the last 30 days, or since the optional `uploaded_after` timestamp.



# Parse Result
Source: https://docs.contextual.ai/api-reference/parse/parse-result

/api-reference/openapi.json get /parse/jobs/{job_id}/results
Get the results of a parse job.

Parse job results are retained for up to 30 days after job creation. Fetching results for a parse job that is older than 30 days will return a 404 error.



# Parse Status
Source: https://docs.contextual.ai/api-reference/parse/parse-status

/api-reference/openapi.json get /parse/jobs/{job_id}/status
Get the status of a parse job.

Parse job results are retained for up to 30 days after job creation. Fetching a status for a parse job that is older than 30 days will return a 404 error.



# Rerank
Source: https://docs.contextual.ai/api-reference/rerank/rerank

/api-reference/openapi.json post /rerank
Rank a list of documents according to their relevance to a query primarily and your custom instructions secondarily.  We evaluated the model on instructions for recency, document type, source, and metadata, and it can generalize to other instructions as well. The reranker supports multilinguality.

The total request cannot exceed 400,000 tokens. The combined length of the query, instruction and any document with its metadata must not exceed 8,000 tokens.

See our [blog post](https://contextual.ai/blog/introducing-instruction-following-reranker/) and [code examples](https://colab.research.google.com/github/ContextualAI/examples/blob/main/03-standalone-api/03-rerank/rerank.ipynb). Email [rerank-feedback@contextual.ai](mailto:rerank-feedback@contextual.ai) with any feedback or questions.



# Get Users
Source: https://docs.contextual.ai/api-reference/users/get-users

/api-reference/openapi.json get /users
Retrieve a list of `users`.



# Invite Users
Source: https://docs.contextual.ai/api-reference/users/invite-users

/api-reference/openapi.json post /users
Invite users to the tenant. This checks if the user is already in the tenant and if not, creates the user. We will return a list of user emails that were successfully created (including existing users).



# Remove User
Source: https://docs.contextual.ai/api-reference/users/remove-user

/api-reference/openapi.json delete /users
Delete a given `user`.



# Update User
Source: https://docs.contextual.ai/api-reference/users/update-user

/api-reference/openapi.json put /users
Modify a given `User`.

Fields not included in the request body will not be modified.



# Get Consent
Source: https://docs.contextual.ai/api-reference/workspaces/get-consent

/api-reference/openapi.json get /workspaces/consent
Retrieve the current consent status for the workspace.



# Update Consent
Source: https://docs.contextual.ai/api-reference/workspaces/update-consent

/api-reference/openapi.json put /workspaces/consent
Update the consent status for the workspace.



# Auto & Manual Syncing
Source: https://docs.contextual.ai/connectors/auto-manual-syncing

Detailed instructions on how to set up Auto & Manual Syncing

## Overview

You can enable or disable **auto-syncing** at the top of your Datastore. When enabled, data changes are synced every 3 hours and permission updates every hour.

<Note>
  **Note:** Box connectors automatically sync every 24 hours due to rate limits in the Box API. Please contact [connectors@contextual.ai](mailto:connectors@contextual.ai) if you need faster syncing.
</Note>

Please note that changes may not appear immediately. Contextual AI relies on the upstream data source’s API (for example, SharePoint), and updates are only pulled once the API confirms that changes have been made.

<img alt="Screenshot 2025-09-08 at 7.01.51 PM.png" />

You can also trigger a **manual sync** to pull in changes.

<img alt="Screenshot 2025-09-08 at 7.01.55 PM.png" />

Possible sync status indicators include:

* **Syncing metadata:** We are syncing file metadata, users, and groups. We will need to sync metadata before we can begin ingestion.
* **Processing:** We are ingesting any document or metadata changes.
* **Synced / Green checkmark:** The sync has completed successfully.
* **Partially Synced:** Some documents failed in the sync. To correct this issue, wait for 10-15 minutes and retrigger a manual sync. The failed documents will be retried.
* **Failed:** All documents failed in the sync. Make sure that you have sufficient credits and retry with a manual sync after waiting for 10-15 minutes.

<Note>
  If your sync still fails, please contact [connectors@contextual.ai](mailto:connectors@contextual.ai) for further assistance.
</Note>


# Box
Source: https://docs.contextual.ai/connectors/box

Connect your Box documents to Contextual AI

## Connecting Box

Log in through the Contextual AI UI and follow these steps to configure Box as a data source.

### 1. Set Data Source Name & Type

* Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right.
* Give your datastore a unique name, then select **Third-Party Connection** as the method for adding content to your datastore. Click the **Next** button.
* On the **Connection Setup** page, you can **set up auto top-off** to automatically add credits when low, or click **Skip for now** to bypass this step.

<Note>
  **Note:** Auto top-off is recommended in [On Demand mode](https://docs.contextual.ai/user-guides/billing) to prevent ingestions from failing halfway if you use up your balance.
</Note>

<Frame>
  <img alt="" />
</Frame>

### 2. Review Access Levels & Set Account Type

* Click the **Connect** button next to **Box**.
* Confirm Contextual AI's read/write access levels and review the end user terms. Click **Next** to continue.
* Select your **Account Type**:
  **Admin account (read-only)** - You are setting up a connection for your organization and have admin access to your data source.
  **User account (read-only)** - You are setting up a personal connection or do not have admin access to your data source.

<Note>
  Please [refer to this link](https://help.merge.dev/articles/9280406-why-are-specific-scopes-needed-for-file-storage-integrations) for a full list of permissions you need for admin authorization.
</Note>

* Click **Open window** to grant access to your Box account.

<Frame>
  <img alt="" />
</Frame>

### 3. Grant Access & Sync Settings

* Review the access permissions that will be granted from your Box account.
* Click **Grant Access to Box** to continue.

<Frame>
  <img alt="" />
</Frame>

### 4. Configure Sync Settings

Contextual AI offers two ways to sync your data. You can choose to sync all your files or only specific folders in Box.

#### Sync Options

* **Share all files** - Grants access to all your content in Box.
* **Share specific files** - Restricts access to only the folders you select.

To share specific folders:

* Hover over the folder and check the box to select it.
* You can click into a folder to view its contents, but note that **only folders**—not individual files—can be selected.
* Select one or multiple folders as needed.
* Click **Confirm** to finalize your selections, then click **Next** once setup is complete.
* You can review or edit your connection (for example, to choose a different folder) on the confirmation page. Click **Finish setup** to continue.

<Frame>
  <img alt="" />
</Frame>

### 5. Create Datastore & Start Sync

You’re now ready to start syncing your data. Click **Create** to initialize your connection and create your datastore.

You’ll be redirected to your **Datastore** page, where the **Syncing Metadata** status will appear. During this stage, Contextual AI syncs your file metadata, users, and groups. This process is typically quick but may take a few hours if you have a large number of files, users, or groups.

Once metadata syncing is complete, ingestion will begin automatically and the status will update to **Processing**.

<Note>
  **Note:** You can begin using your datastore while syncing continues, but you’ll only have access to the documents that have already been ingested.
</Note>

<Frame>
  <img alt="" />
</Frame>

You can check the progress bar to track how many documents remain to be processed.

Once all documents finish ingesting, you’ll see a **green checkmark** indicating that your datastore is ready to use.


# Confluence
Source: https://docs.contextual.ai/connectors/confluence

Connect your Confluence documents to Contextual AI

## Connecting Confluence

Log in through the Contextual AI UI and follow these steps to configure Confluence as a data source.

### 1. Set Data Source Name & Type

* Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right.
* Give your datastore a unique name, then select **Third-Party Connection** as the method for adding content to your datastore. Click the **Next** button.
* On the **Connection Setup** page, you can **set up auto top-off** to automatically add credits when low, or click **Skip for now** to bypass this step.

<Note>
  **Note:** Auto top-off is recommended in [On Demand mode](https://docs.contextual.ai/user-guides/billing) to prevent ingestions from failing halfway if you use up your balance.
</Note>

<Frame>
  <img alt="" />
</Frame>

### 2. Review Access Levels, Set Account Type & Confluence Site

* Click the **Connect** button next to **Confluence**.
* Confirm Contextual AI's read/write access levels and review the end user terms. Click **Next** to continue.
* On the **Enter additional information** screen, enter the URL of your Confluence site and click **Next**.
* On the **Connect Confluence** screen, click the **Open window** button.
* Log in to your Confluence account. Review the requested permissions click **Accept** to continue.
* Click the **Next** button to install the Forge app and proceed to the next step.

<Frame>
  <img alt="" />
</Frame>

### 3. Grant Access & Sync Settings

* Select the level of access to grant from your Confluence account:
  * **Share specific content** — Restricts access to only the content you select.
  * **Share all content** — Grants access to all your content in Confluence.
* Click the **Finish setup** button on the **Success!** page.

### 4. Create Datastore & Start Sync

You’re now ready to start syncing your data. Click **Create** to initialize your connection and create your datastore.

You’ll be redirected to your **Datastore** page, where the **Syncing Metadata** status will appear. During this stage, Contextual AI syncs the contents of your Confluence site. This process is typically quick but may take some time if you have a large site.

Once metadata syncing is complete, ingestion will begin automatically and the status will update to **Processing**.

<Frame>
  <img alt="" />
</Frame>

<Note>
  **Note:** You can begin using your datastore while syncing continues, but you’ll only have access to the documents that have already been ingested.
</Note>

You can check the progress bar to track the status of the sync.

Once the contents of your Confluence site finishes ingesting, you’ll see a **green checkmark** indicating that your datastore is ready to use.


# Entitlements Enforcement
Source: https://docs.contextual.ai/connectors/entitlements-enforcement

Using your Connector with Entitlements Enforcement

## Using your Connector with Entitlements Enforcement

To use your connected Datastore, simply link it to an Agent and start querying. All original datasource entitlements are automatically enforced. If you do not have access to a document in the source system, two restrictions will apply:

1. The document will not be used to generate a response to the your query.
2. On the **Datastore** page, the document will be displayed as **Private Document**. You'll only be able to view documents that you have access to.

   <img alt="Screenshot 2025-09-08 at 6.56.01 PM.png" />


# Global Datastores
Source: https://docs.contextual.ai/connectors/global-datastores

Pre-built datastores available to all users for testing and demos

## Overview

When you create a new Contextual AI account, you automatically have access to several **global datastores**—pre-built knowledge bases you can use immediately to test agents, run demos, or explore the platform without uploading your own documents.

These datastores are read-only and available to all users.

## Available Global Datastores

<CardGroup>
  <Card title="Materials Science Research Papers" icon="atom">
    7,546 docs · 41.3 GB
  </Card>

  <Card title="Star Wars Wookiepedia" icon="jedi">
    497 docs · 4.8 GB
  </Card>

  <Card title="Rocket Science" icon="rocket">
    7 docs · 59.1 MB
  </Card>

  <Card title="RFC Library" icon="file-code">
    1,786 docs · 50.7 MB
  </Card>

  <Card title="Raspberry Pi Docs" icon="microchip">
    54 docs · 82 MB
  </Card>
</CardGroup>

## Using Global Datastores

### In the Platform UI

1. Go to **Datastores** in the left navigation
2. Global datastores are marked with a **Demo** badge
3. When creating an agent, select any global datastore from the dropdown

### In Agent Composer YAML

Reference a global datastore by its ID in your YAML configuration:

```yaml theme={null}
nodes:
  search:
    type: SearchStep
    config:
      datastores:
        - <your-datastore-id>
    input_mapping:
      query: __inputs__#query
```

### Via API

Use the datastore ID when creating or configuring agents:

```shell theme={null}
curl --request POST \
  --url https://api.contextual.ai/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My Demo Agent",
  "datastore_ids": ["78f6bb93-04a5-4883-95f4-d681da6eee23"]
}'
```

## Example Agents

See these demos built on global datastores:

* [Raspberry Pi Agent](/examples/raspberry-pi-agent) — Technical support and troubleshooting for Raspberry Pi hardware
* [Rocket Science Agent](/examples/rocket_science) — Root cause analysis for rocket engine anomalies
* [Material Science Agent](/examples/material-science-agent) — Research assistant using arXiv materials papers; explains in ELI5 style
* [Test Program Generation](/examples/test-automation) — Generate OpenTAP test programs and instrument drivers


# Google Drive
Source: https://docs.contextual.ai/connectors/google-drive

Connect your Google Drive documents to Contextual AI

## Connecting Google Drive

Log in through the Contextual AI UI and follow these steps to configure Google Drive as a data source.

### 1. Set Data Source Name & Type

* Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right.
* Give your datastore a unique name, then select **Third-Party Connection** as the method for adding content to your datastore. Click the **Next** button.
* On the **Connection Setup** page, you can **set up auto top-off** to automatically add credits when low, or click **Skip for now** to bypass this step.

<Note>
  **Note:** Auto top-off is recommended in [On Demand mode](https://docs.contextual.ai/user-guides/billing) to prevent ingestions from failing halfway if you use up your balance.
</Note>

<Frame>
  <img alt="" />
</Frame>

### 2. Review Access Levels & Set Account Type

* Click the **Connect** button next to **Google Drive**.
* Confirm Contextual AI's read/write access levels and review the end user terms. Click **Next** to continue.
* Select your **Account Type**:
  **Admin account (read-only)** - You are setting up a connection for your organization and have admin access to your data source.
  **User account (read-only)** - You are setting up a personal connection or do not have admin access to your data source.

<Note>
  Please [refer to this link](https://help.merge.dev/articles/9280406-why-are-specific-scopes-needed-for-file-storage-integrations) for a full list of permissions you need for admin authorization.
</Note>

* Click **Open window** to authorize your account.

<Frame>
  <img alt="" />
</Frame>

### 3. Authorize Connection & Sync Settings

* In the pop-up window, select the account for authorizing the connection.
* Click **Continue** to authorize the connection.

<Frame>
  <img alt="" />
</Frame>

### 4. Configure Sync Settings

Contextual AI offers two ways to sync your data. You can choose to sync all your files or only specific folders in Google Drive.

#### Sync Options

* **Share all files** - Grants access to all content in your Google Drive.
* **Share specific folders** - Restricts access to only the folders you select.

To share specific folders:

* Hover over the folder and check the box to select it.
* You can click into a folder to view its contents, but note that **only folders**—not individual files—can be selected.
* Select one or multiple folders as needed.
* Click **Confirm** to finalize your selections, then click **Next** once setup is complete.

You can review or edit your connection (for example, to choose a different folder) on the confirmation page. Click **Finish** to continue.

<Frame>
  <img alt="" />
</Frame>

### 5. Create Datastore & Start Sync

You’re now ready to start syncing your data. Click **Create** to initialize your connection and create your datastore.

You’ll be redirected to your **Datastore** page, where the **Syncing Metadata** status will appear. During this stage, Contextual AI syncs your file metadata, users, and groups.

Once metadata syncing is complete, ingestion will begin automatically and the status will update to **Processing**.

<Note>
  **Note:** The syncing process is typically quick, but may take a few hours if you have a large number of files, users, or groups.<br /><br />You can begin using your datastore while syncing continues, but you’ll only have access to the documents that have already been ingested.
</Note>

<Frame>
  <img alt="" />
</Frame>

You can check the progress bar to track how many documents remain to be processed.

Once all documents finish ingesting, you’ll see a **green checkmark** indicating that your datastore is ready to use.


# Local File Upload
Source: https://docs.contextual.ai/connectors/local-file-upload

Upload your documents to Contextual AI

## Uploading Your Local File

Log in through the Contextual AI UI and follow these steps to upload a local file to use as a data source.

### 1. Set Data Source Name & Type

* Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right.
* Give your datastore a unique name, then click the **local file upload button** (the left panel) as the method for adding content to your datastore. Click the **Next** button.

<Frame>
  <img alt="" />
</Frame>

### 2. Upload & Process Your File

* On the **Datastores** page, click the **Upload** button.
* Drag and drop or select the file to upload, and click the **Start Uploading** button.
* After Contextual AI finishes processing your file, go back to the **Datasources** page. You should see your newly-created datasource with the previously uploaded file.

<Frame>
  <img alt="" />
</Frame>


# Microsoft OneDrive
Source: https://docs.contextual.ai/connectors/microsoft-onedrive

Connect your Microsoft OneDrive documents to Contextual AI

## Connecting Microsoft OneDrive

You can sync your OneDrive data via the Contextual AI SharePoint connector.

<Note>
  **Note:** Before getting started, ensure that you are a Super Admin. [Follow this guide](https://contextualai.integrations.guide/articles/10744024) to configure Super Admin permissions in SharePoint.
</Note>

Log in through the Contextual AI UI and follow these steps to configure OneDrive as a data source.

### 1. Set Data Source Name & Type

* Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right.
* Give your datastore a unique name, then select **Third-Party Connection** as the method for adding content to your datastore. Click the **Next** button.
* On the **Connection Setup** page, you can **set up auto top-off** to automatically add credits when low, or click **Skip for now** to bypass this step.

<Note>
  **Note:** Auto top-off is recommended in [On Demand mode](https://docs.contextual.ai/user-guides/billing) to prevent ingestions from failing halfway if you use up your balance.
</Note>

<Frame>
  <img alt="" />
</Frame>

### 2. Review Access Levels & Set Account Type

* Click the **Connect** button next to **SharePoint**.
* Confirm Contextual AI's read/write access levels and review the end user terms. Click **Next** to continue.
* Select your **Account Type**:
  **Admin account (read-only)** - You are setting up a connection for your organization and have admin access to your data source.
  **User account (read-only)** - You are setting up a personal connection or do not have admin access to your data source.

<Note>
  Please [refer to this link](https://help.merge.dev/articles/9280406-why-are-specific-scopes-needed-for-file-storage-integrations) for a full list of permissions you need for admin authorization.
</Note>

* Click **Open window** to authorize your account.

<Frame>
  <img alt="" />
</Frame>

### 3. Configure Sync Settings

Contextual AI offers two ways to sync your data. You can choose to sync all your files or only specific folders.

#### Sync Options

* **Share all files** - Grants access to all content. This includes OneDrive folders within SharePoint sites and an individual user’s OneDrive folders.
* **Share specific folders** - Restricts access to only the folders you select. You can pick specific OneDrive folders within SharePoint sites, but not an individual user’s OneDrive folders.

Once you've selected and configured your sync option, click **Confirm** to finalize your selections, then click **Next** once setup is complete.

Click **Finish setup** to continue. On the next page, click **Create** to initialize your connection and create your datastore.

<Frame>
  <img alt="" />
</Frame>

You’ll be redirected to your **Datastore** page, where the **Syncing Metadata** status will appear. During this stage, Contextual AI syncs your file metadata, users, and groups.

Once metadata syncing is complete, ingestion will begin automatically and the status will update to **Processing**. You can check the progress bar to track how many documents remain to be processed.

<Note>
  **Note:** The syncing process is typically quick, but may take a few hours if you have a large number of files, users, or groups.<br /><br />You can begin using your datastore while syncing continues, but you’ll only have access to the documents that have already been ingested.
</Note>

Once all documents finish ingesting, you’ll see a **green checkmark** indicating that your datastore is ready to use.


# Microsoft SharePoint
Source: https://docs.contextual.ai/connectors/microsoft-sharepoint

Connect your Microsoft SharePoint documents to Contextual AI

## Connecting Microsoft SharePoint

Log in through the Contextual AI UI and follow these steps to configure SharePoint as a data source.

<Note>
  You can sync OneDrive data via the SharePoint connector. For detailed instructions, please see [Connecting to OneDrive via Sharepoint](#connecting-to-onedrive-via-sharepoint)
</Note>

### 1. Set Data Source Name & Type

* Click **Datastores** in the left-hand pane, followed by the **Create** button in the top right.
* Give your datastore a unique name, then select **Third-Party Connection** as the method for adding content to your datastore. Click the **Next** button.
* On the **Connection Setup** page, you can **set up auto top-off** to automatically add credits when low, or click **Skip for now** to bypass this step.

<Note>
  **Note:** Auto top-off is recommended in [On Demand mode](https://docs.contextual.ai/user-guides/billing) to prevent ingestions from failing halfway if you use up your balance.
</Note>

<Frame>
  <img alt="" />
</Frame>

### 2. Review Access Levels & Set Account Type

* Click the **Connect** button next to **SharePoint**.
* Confirm Contextual AI's read/write access levels and review the end user terms. Click **Next** to continue.
* Select your **Account Type**:
  Admin account (read-only)\*\* - You are setting up a connection for your organization and have admin access to your data source.
  User account (read-only)\*\* - You are setting up a personal connection or do not have admin access to your data source.

<Note>
  Please [refer to this link](https://help.merge.dev/articles/9280406-why-are-specific-scopes-needed-for-file-storage-integrations) for a full list of permissions you need for admin authorization.
</Note>

* Click **Open window** to authorize your account.

<Frame>
  <img alt="" />
</Frame>

### 3. Configure Sync Settings

Contextual AI offers two ways to sync your data. You can choose to sync all your files or only specific folders in Sharepoint.

#### Sync Options

* **Share all files** - Grants access to all content in Sharepoint.
* **Share specific folders** - Restricts access to only the folders you select.

To share specific folders:

* Hover over the folder and check the box to select it.
* You can click into a folder to view its contents, but note that **only folders**—not individual files—can be selected.
* Select one or multiple folders as needed.
* Click **Confirm** to finalize your selections, then click **Next** once setup is complete.
* Click **Finish setup** to continue. On the next page, click **Create** to initialize your connection and create your datastore.

<Frame>
  <img alt="" />
</Frame>

You’ll be redirected to your **Datastore** page, where the **Syncing Metadata** status will appear. During this stage, Contextual AI syncs your file metadata, users, and groups.

Once metadata syncing is complete, ingestion will begin automatically and the status will update to **Processing**. You can check the progress bar to track how many documents remain to be processed.

<Note>
  **Note:** The syncing process is typically quick, but may take a few hours if you have a large number of files, users, or groups.<br /><br />You can begin using your datastore while syncing continues, but you’ll only have access to the documents that have already been ingested.
</Note>

Once all documents finish ingesting, you’ll see a **green checkmark** indicating that your datastore is ready to use.


# Overview
Source: https://docs.contextual.ai/connectors/overview

Connecting your data to Contextual AI

Contextual AI data connectors enable you to seamlessly integrate data from third-party sources.

Key features include:

* **Full ingestion and indexing** - Data is ingested and indexed through our advanced pipeline, ensuring optimal performance and speed compared to live search.
* [Entitlements enforcement](#using-your-connector-with-entitlements-enforcement) - Permissions from your upstream data sources are automatically synced and enforced within the Contextual platform. Users without access to a document cannot see it in the Datastore or query against it.
* [Auto and manual syncing](#auto--manual-syncing) - Data updates are synced every 3 hours, while permissions are refreshed every hour to maintain freshness. You can also trigger a manual sync at any time to capture changes.
* **Folder-level selection** - Sync only the folders you need.

### Supported Data Sources

Contextual AI currently supports the following data sources:

* [Box:](box) PDF files, Word documents, PowerPoint presentations, Markdown files, plain text files
* [Confluence:](confluence) PDF files, Word documents, PowerPoint presentations, Markdown files, plain text files
* [Google Drive:](google-drive) Google Docs, Google Slides, PDF files, Word documents, PowerPoint presentations, Markdown files, plain text files
* [OneDrive:](microsoft-onedrive) PDF files, Word documents, PowerPoint presentations, Markdown files, plain text files
* [Sharepoint:](microsoft-sharepoint) PDF files, Word documents, PowerPoint presentations, Markdown files, plain text files

<Note>**Coming Soon:** Support for Dropbox and Salesforce<br /><br />
Please email [connectors@contextual.ai](mailto:connectors@contextual.ai) for connector-related questions or feedback.</Note>


# 3GPP Spec Explorer
Source: https://docs.contextual.ai/examples/3gpp-spec-explorer

AI agent to search and reason over 3GPP specifications (Release 19 and others)

## Overview

This agent lets you search and reason over a large knowledge base of 3GPP specifications—PDF and Word documents across multiple releases, including Release 19. Ask about information elements (IEs), mobility, registration, requirements, and more; answers are grounded in the actual specs.

**Built with [Agent Composer](/quickstarts/agent-composer)**, Contextual AI's framework for production-ready AI agents.

## The Knowledge Base

The agent is connected to a datastore of 3GPP standards (e.g. Series 36 LTE, 38 NR, and others). The documents were obtained from the 3GPP archive using the [download\_3gpp](https://pypi.org/project/download_3gpp/) CLI and ingested for search and retrieval.

## What the Agent Does

You can ask natural-language questions such as:

* **IEs and parameters**: "What is the purpose of IE X in the RRC connection setup?"
* **Mobility**: "What are the handover requirements for NR in Release 19?"
* **Registration**: "Describe the registration procedure for 5G NR."
* **Requirements**: "What does the spec say about timing for TAU?"

The agent retrieves relevant chunks from the specs and synthesizes answers with citations to the source documents.

## Try the Demo

<Card title="Launch Demo" icon="magnifying-glass" href="https://demo.contextual.ai/3gpp-agentic-search">
  Search the 3GPP spec yourself
</Card>

## Learn More

* [Contextual AI Demos](/examples/overview-demos) — All live demos in one place
* [Agent Composer Documentation](/quickstarts/agent-composer)
* [Prompt Builder Quickstart](/quickstarts/prompt-builder)
* [Agent Composer YAML Guide](/how-to-guides/agent-composer-yaml)


# 3GPP Wireless Log Analysis Agent
Source: https://docs.contextual.ai/examples/3gpp-wireless-log-analysis

AI agent for automated root cause analysis of 3GPP LTE-style device and eNB logs

## Overview

This agent performs automated root cause analysis on 3GPP LTE-style device logs: eNB/RRH events, error codes, handovers, and CPRI/HARQ/BLER-style signals. It cross-references logs against a debug reference guide to decode sub-codes, correlate events across subsystems, and produce RCA reports—work that would otherwise require a senior wireless engineer to manually sift through thousands of timestamped entries.

**Powered by the [Device Log Analysis](/how-to-guides/agent-composer-templates#device-log-analysis-enterprise) template** in [Agent Composer](/quickstarts/agent-composer)—available for Enterprise customers; [request a demo](https://contextual.ai/request-a-demo) for access.

## Try the Demo

<Card title="Launch Demo" icon="tower-cell" href="https://demo.contextual.ai/log-analysis">
  Analyze 3GPP wireless logs yourself
</Card>

3GPP Wireless samples are preloaded—pick a suggested query and run the analysis.

<Note>
  Running on the production DLA template. Demo queries are cached and sped up for demonstration purposes.
</Note>

## The Problem

When a device or network incident occurs, engineers must manually sift through thousands of timestamped log entries containing cryptic error codes, protocol abbreviations, and vendor-specific identifiers. Root cause analysis requires:

* Decoding error codes against reference documentation
* Correlating events across subsystems (eNB-SYS, eNB-MAC, eNB-PHY, eNB-RRC, eNB-S1AP, eNB-X2AP, UE-MAC/UE-RRC)
* Building timelines to establish causality between failures (e.g. CPRI degradation → handover failures → call drops)
* Identifying patterns across multiple failure events
* Distinguishing symptoms from root causes

## How It Works

### In production

**What you do:** Upload a **log file** and optionally **additional context** (e.g. a debug reference guide), then ask a query—for example *"Why did the calls drop?"*.

**What happens automatically:** A multi-agent implementation takes over. The system parses the log, builds a searchable database from the log and reference files, runs root cause analysis, and produces outputs.

**Pipeline stages:** Uploading files → parsing logs → building the database → root cause analysis → generating the report.

**Outputs:** The agent delivers a **detailed RCA report** (executive summary, timeline, decoded errors, recommended actions) and can generate **visualizations** (causation timelines, degradation charts).

**Auditable:** Every step is visible—tasks, trajectory, intermediate artifacts, and the final report—so teams can review the analysis and act on findings.

### In this demo

3GPP Wireless files are **preloaded**; choose a suggested query and run the analysis.

## Example Questions

Suggested queries in the demo:

* "Why did the calls drop?"
* "When did this problem start?"
* "Was there a problem with RRH:1?"

## Output

Example outputs from the three suggested queries:

**"Why did the calls drop?"** — Full-day RCA timeline across 5 correlated metrics: CPRI fronthaul BER on RRH:2, sector temperature, SCTP heartbeat to MME, PSU voltage sag, and handover failures / radio link failures:

<img alt="eNB 4325 call drop RCA timeline — CPRI BER, thermal, SCTP, PSU, and handover failures over a full day" />

Zoomed into the critical 6-minute onset window (17:09–17:15), the agent pinpoints the cascade: CPRI BER spike triggers DRX misalignment, thermal breach forces TX power reduction, S1/SCTP path degrades, and handover failures begin:

<img alt="Critical failure onset window — cascade from CPRI spike through thermal breach to call drops" />

**"When did this problem start?"** — Hourly ERROR and WARN event counts pinpoint the problem onset at 17:10:01, with zero errors in the preceding 8 hours:

<img alt="Hourly ERROR and WARN event counts — problem start identified at 17:10:01" />

CPRI link quality on RRH:2 and HARQ retransmission rate show the degradation building before the threshold breach:

<img alt="CPRI link quality and HARQ retransmission rate — RRH:2 degradation trend" />

PRB utilization and handover failure counts confirm the downstream impact:

<img alt="PRB utilization and handover failures — downstream service degradation" />

**"Was there a problem with RRH:1?"** — Side-by-side BER comparison of RRH:1 (healthy, green) vs RRH:2 (root cause, escalating orange/red) confirms the fault is isolated to RRH:2:

<img alt="CPRI BER timeline — RRH:1 healthy vs RRH:2 root cause comparison" />

BLER and HARQ comparison reinforces that RRH:1 operated normally while RRH:2 degraded:

<img alt="BLER and HARQ comparison — RRH:1 vs RRH:2" />

The **final RCA report** includes:

* **Executive summary** — Root cause (e.g. CPRI fronthaul degradation on RRH:2), secondary factors (DRX misalignment, SCTP/MME, backhaul jitter), and impact (UE counts by failure type: RLF, RRC reject, NAS attach reject)
* **Detailed timeline** — Phased chronology with decoded log lines (early degradation → threshold breach → handover failures → thermal throttle → congestion and rejects), so reviewers can follow the sequence event-by-event
* **Error analysis by UE** — Grouped tables (e.g. handover failure → RLF call drops, RRC reject due to congestion, NAS attach reject with cause codes) with timestamps and preceding causes
* **Technical explanation** — Root cause deep dive and cascade effects (e.g. CPRI BER progression, RF/UL BLER, thermal throttle, ANR staleness and HO prep failure, SCTP/MME overload) with supporting tables
* **Answer to original question** — Direct answer to the query (e.g. call drop mechanism: CPRI → RF degradation → thermal throttle → HO failures → T304 expiry → RLF) and optional mechanism diagram
* **Attached visualizations** — References to the generated timeline visuals (system health, call drop causality)
* **Recommended actions** — Prioritized table (e.g. CRITICAL / HIGH / MEDIUM) with action and rationale for each

## 3GPP Wireless sample files in the demo

* **Device log** (`3gpp_wireless_device_log.txt`) — eNB/UE failure log (eNB-SYS, eNB-MAC, eNB-PHY, eNB-RRC, eNB-S1AP, eNB-X2AP, UE-MAC/UE-RRC); severity, tags, codes (e.g. `RACH_INIT`, `RRC_CONN_REQ`, `CPRI_LINK_DEGRADED_0xE1`, `VNDR_THERMAL_0x4F2A`) decoded against the matching reference.
* **Debug reference guide** (`3gpp_wireless_debug_rules.txt`) — eNB debug reference ("3GPP LTE eNB Debug Reference Guide"): RRC/NAS, EMM/ESM, S1AP/X2AP, timers, RSRP/RSRQ, vendor diagnostics—paired with the log above.

## Learn More

* [Device Log Analysis (overview)](/examples/device-log-analysis) — General DLA template and all three sample datasets
* [ATE Board Validation](/examples/ate-log-analysis) — Board validation / tester logs
* [Mazda Infotainment](/examples/mazda-infotainment-log-analysis) — Infotainment crash logs
* [Getting Started with the Contextual AI Platform](/quickstarts/getting-started)
* [Agent Composer Templates](/how-to-guides/agent-composer-templates) — Basic Search, Agentic Search, and Device Log Analysis (Enterprise)
* [Request a demo](https://contextual.ai/request-a-demo)


# ATE Board Validation Agent
Source: https://docs.contextual.ai/examples/ate-log-analysis

AI agent for automated root cause analysis of ATE board validation failure logs

## Overview

This agent performs automated root cause analysis on ATE (Automated Test Equipment) board validation failure logs. It cross-references multi-site test logs against a debug reference guide to decode error codes, trace fault propagation across test phases, and identify whether failures are board defects or tester artifacts—work that would otherwise require a hardware validation engineer to manually correlate hundreds of timestamped events across power, memory, PCIe, and signal integrity subsystems.

**Powered by the [Device Log Analysis](/how-to-guides/agent-composer-templates#device-log-analysis-enterprise) template** in [Agent Composer](/quickstarts/agent-composer)—available for Enterprise customers; [request a demo](https://contextual.ai/request-a-demo) for access.

## Try the Demo

<Card title="Launch Demo" icon="microchip" href="https://demo.contextual.ai/log-analysis">
  Analyze board validation logs yourself
</Card>

ATE samples preloaded—pick a suggested query and run the analysis.

<Note>
  Running on the production DLA template. Demo queries are cached and sped up for demonstration purposes.
</Note>

## The Problem

When a board validation session fails, engineers must determine whether the fault lies with the device under test (DUT), the tester hardware, or a transient environmental condition. ATE logs contain:

* Per-site parallel test events across multiple DUT sockets
* Power rail telemetry (VDDQ, VCCIN, VCCIO, VPP, VCCSA) sampled throughout each test phase
* DDR5 training sequences with per-phase margin measurements
* PCIe link training LTSSM states and equalization results
* Signal integrity eye measurements, insertion loss, jitter, and skew
* Voltage regulator diagnostics including temperature, efficiency, and ripple
* Tester HAL artifacts (e.g. multi-site inrush coupling transients) that must be distinguished from real faults

Without tooling, a failure like "SITE:2 DDR5 training fail" requires manually correlating voltage telemetry, thermal readings, retry logs, and VR diagnostics across hundreds of lines to determine the actual root cause.

## How It Works

### In production

**What you do:** Upload an **ATE failure log** and optionally a **debug reference guide**, then ask a query—for example *"Why did SITE:2 fail?"*.

**What happens automatically:** A multi-agent implementation takes over. The system parses the log, builds a searchable database from the log and reference files, runs root cause analysis across all test phases and sites, and produces outputs.

**Pipeline stages:** Uploading files → parsing logs → building the database → root cause analysis → generating the report.

**Outputs:** The agent delivers a **detailed RCA report** covering executive summary, per-site timeline, decoded errors, voltage/thermal trajectory, and prioritized recommended actions. It can also generate **visualizations** such as VDDQ voltage sag charts and multi-site comparison tables.

**Auditable:** Every step is visible—tasks, trajectory, intermediate artifacts, and the final report—so validation teams can review the analysis and act on findings.

### In this demo

Sample ATE files are **preloaded**; choose a suggested query and run the analysis.

## Example Questions

Suggested queries in the demo:

* "Why did SITE:2 fail?"
* "When did this problem first appear?"
* "Is this a device failure or a tester failure?"

## Output

Example outputs from the three suggested queries:

**"Why did SITE:2 fail?"** — VDDQ voltage regulator telemetry for the final test session: output voltage sagging to the spec minimum, output current climbing toward the limit, junction temperature spiking above the warning threshold, and efficiency degrading — all four panels confirm a single failing component:

<img alt="SITE:2 VDDQ voltage regulator telemetry — voltage sag, current spike, temperature, and efficiency" />

**"When did this problem first appear?"** — Long-horizon view showing the VDDQ output capacitor ESR ratio climbing over time, with voltage holding nominal until the final test session where it drops to the spec minimum as temperature rises:

<img alt="SITE:2 VDDQ ESR ratio, output voltage, and VR temperature over time" />

**"Is this a device failure or a tester failure?"** — Zoomed into the critical failure window, VOUT drops from 1.089V to just above the 1.045V spec minimum, IOUT climbs to 7.5A, and junction temperature crosses the 85°C warning threshold — all on a single DUT while other sites remain nominal, confirming a board defect:

<img alt="VDDQ critical failure window — VOUT sag, IOUT climb, and junction temperature for DUT PCB-2025-08142 SITE:2" />

The **final RCA report** includes:

* **Executive summary** — Which site(s) failed, root cause (e.g. VDDQ voltage regulator degradation), and yield impact
* **Fault timeline** — Chronological sequence showing voltage sag progression, training retry escalation, and cascade into secondary failures
* **Per-site comparison** — Side-by-side pass/fail status and key metrics (VDDQ voltage, VR temperature, DDR5 eye width) across all 4 test sites
* **Root cause chain** — Causal trace from the originating hardware fault through each downstream failure (e.g. VDDQ sag → DDR5 training fail → PCIe Gen fallback → bin FAIL)
* **Tester artifact analysis** — Identifies HAL transient events (e.g. `HAL_VDDQ_COUPLE_0x0B`) and correctly classifies them as non-causal measurement artifacts rather than real faults
* **Recommended actions** — Prioritized table with action and rationale (e.g. replace VDDQ output capacitor on failed DUT, retest on same tester to confirm tester health)

## ATE sample files in the demo

* **Device log** (`ate_device_log_30mb.txt`) — A timestamped multi-site board validation log with entries from subsystems including ATE-SYS, ATE-HAL, ATE-PWR, ATE-FPGA, DUT-VR, DUT-THERM, and per-site test events (SITE-1 through SITE-4). Each line includes severity (INFO/WARN/ERROR), subsystem tags, and synthetic diagnostic codes.
* **Debug reference guide** (`ate_debug_rules.txt`) — An ATE board validation debug reference covering power rail specifications, DDR5 training sequence codes, PCIe link training codes, voltage regulator diagnostic codes, signal integrity measurement codes, test bin definitions, HAL artifact classifications, and common root cause patterns.

## Learn More

* [Device Log Analysis (overview)](/examples/device-log-analysis) — General DLA template and all three sample datasets
* [3GPP Wireless](/examples/3gpp-wireless-log-analysis) — LTE-style eNB/device logs
* [Mazda Infotainment](/examples/mazda-infotainment-log-analysis) — Infotainment crash logs
* [Getting Started with the Contextual AI Platform](/quickstarts/getting-started)
* [Agent Composer Templates](/how-to-guides/agent-composer-templates) — Basic Search, Agentic Search, and Device Log Analysis (Enterprise)
* [Request a demo](https://contextual.ai/request-a-demo)


# Device Log Analysis Agent
Source: https://docs.contextual.ai/examples/device-log-analysis

AI agent for automated root cause analysis of device logs (wireless, ATE, infotainment)

## Overview

**Powered by the [Device Log Analysis](/how-to-guides/agent-composer-templates#device-log-analysis-enterprise) template** in [Agent Composer](/quickstarts/agent-composer)—Enterprise; [request a demo](https://contextual.ai/request-a-demo).

Root cause analysis (RCA) for device logs. The agent parses logs, cross-references debug rules, and generates RCA reports—work that would otherwise take a senior engineer hours manually. **Demo log files are synthetic** (created for this demo); download them from the live demo and try the same workflow in your own environment.

The **[live demo](https://demo.contextual.ai/log-analysis)** includes **three sample datasets**—each is a log plus matching debug reference for a different scenario. Run one of the suggested queries (or your own). For more Agent Composer demos beyond DLA, see **[Contextual AI Demos](/examples/overview-demos)**.

<Note>
  **Demo behavior:** Refreshing the page will clear your progress. For this demo, queries are cached and sped up (production DLA template).
</Note>

## Try the Demo

<Card title="Launch Demo" icon="tower-cell" href="https://demo.contextual.ai/log-analysis">
  Analyze device logs yourself
</Card>

## Sample datasets in the demo

The live demo offers **three** preloaded options—each is a **pair** of synthetic files (device log + debug reference). Use the links below for scenario-specific example questions, example outputs, and file descriptions.

<CardGroup>
  <Card title="3GPP Wireless" icon="tower-cell" href="/examples/3gpp-wireless-log-analysis">
    LTE-style eNB/RRH logs, handovers, CPRI/HARQ/BLER. Example: "Why did the calls drop?"
  </Card>

  <Card title="ATE Board Validation" icon="microchip" href="/examples/ate-log-analysis">
    Multi-site test logs, VR telemetry, DDR5/PCIe. Example: "Why did SITE:2 fail?"
  </Card>

  <Card title="Mazda Infotainment" icon="car" href="/examples/mazda-infotainment-log-analysis">
    CMU crash logs, format-string-style bugs. Example: "Why did my car stereo restart?"
  </Card>
</CardGroup>

## The Problem

When a device or network incident occurs, engineers must manually sift through thousands of timestamped log entries containing cryptic error codes, protocol abbreviations, and vendor-specific identifiers. Root cause analysis requires:

* Decoding error codes against reference documentation
* Correlating events across subsystems
* Building timelines to establish causality between failures
* Identifying patterns across multiple failure events
* Distinguishing symptoms from root causes

## How It Works

### In production

**What you do:** Upload a **log file** and optionally **additional context** (e.g. a debug reference guide), then ask a query—for example *"Why did the call drop?"*.

**What happens automatically:** A multi-agent implementation takes over. The system breaks the work into **tasks**, shows **trajectory** as agents run, **parses** the logs, **builds searchable databases** from the log and reference files, runs root cause analysis, and produces outputs.

**Pipeline stages:** Uploading files → parsing logs → building the database → root cause analysis → generating the report.

**Outputs:** The agents can **generate Python scripts** (e.g. custom parsers) that run in a secure **VM**, produce **visuals** (causation timelines, degradation charts), and deliver a **detailed RCA report** (executive summary, timeline, decoded errors, recommended actions).

**Auditable:** You specify the output (report, artifacts, visuals). Every step—tasks, trajectory, intermediate artifacts, and final report—is visible so teams can review and learn from the analysis.

### In this demo

**Three** demo datasets are **preloaded** (3GPP Wireless, ATE Board Validation, Mazda Infotainment). Each is a device log plus matching debug reference. See the dataset pages above for suggested queries and example outputs.

## Output

Each scenario produces a **detailed RCA report** and optional **visualizations**. Report content varies by domain but typically includes an executive summary, fault or session timeline, decoded errors, root cause chain, and prioritized recommended actions. For concrete example outputs and screenshots:

* **[3GPP Wireless](/examples/3gpp-wireless-log-analysis#output)** — Call drop causality, system health timelines, BER/BLER/HARQ comparisons
* **[ATE Board Validation](/examples/ate-log-analysis#output)** — VDDQ voltage/thermal charts, per-site comparison, tester artifact analysis
* **[Mazda Infotainment](/examples/mazda-infotainment-log-analysis#output)** — Incident timeline, crash sequence, format string vulnerability walkthrough

## Sample files in the demo

Each of the three datasets is a **pair** of synthetic files: a timestamped **device log** and a **debug reference guide**. The live demo loads all three so you can compare scenarios. For file names and contents per dataset:

* **[3GPP Wireless](/examples/3gpp-wireless-log-analysis#3gpp-wireless-sample-files-in-the-demo)** — `3gpp_wireless_device_log.txt`, `3gpp_wireless_debug_rules.txt`
* **[ATE Board Validation](/examples/ate-log-analysis#ate-sample-files-in-the-demo)** — `ate_device_log_30mb.txt`, `ate_debug_rules.txt`
* **[Mazda Infotainment](/examples/mazda-infotainment-log-analysis#mazda-sample-files-in-the-demo)** — `mazda_device_log_30mb.txt`, `mazda_debug_rules.txt`

## Learn More

* [Contextual AI Demos](/examples/overview-demos) — Other live demos (spec search, materials, test automation, and more)
* [Getting Started with the Contextual AI Platform](/quickstarts/getting-started)
* [Example: Device Log Analysis (Enterprise)](/quickstarts/why-contextual-ai#example-device-log-analysis-enterprise) — How multi-source root cause analysis fits the platform
* [Agent Composer Templates](/how-to-guides/agent-composer-templates) — Basic Search, Agentic Search, and Device Log Analysis (Enterprise)
* [Request a demo](https://contextual.ai/request-a-demo)


# Documentation Agent
Source: https://docs.contextual.ai/examples/documentation_agent

The agent powering agentic search on this site: try it in the search bar

## Where to find it

The documentation agent powers the chat experience on this very site. You can use it in two places:

* **Top:** The search bar at the top of the page ("Ask Contextual AI...") — type your question and send.
* **Right:** The chat panel persists on the right after you run your first query — use it to run multi-turn conversations.

When you ask a question, **Mintlify's built-in search** first surfaces **keyword-based results** so you get quick, relevant links. In parallel, the **agent runs the longer-running task**: it retrieves across the documentation, runs multi-step research (Agentic Search), and streams back a detailed, cited answer. You get both instant keyword hits and a synthesized response.

<Info>
  **GitHub repo:** The sync code for keeping a Contextual AI datastore in sync with your docs is public: [ContextualAI/datastore-sync](https://github.com/ContextualAI/datastore-sync)—see the section below for an overview.
</Info>

## Why this agent

### (and why not generic LLMs or basic RAG)

**Use cases:** This is the kind of agent we use for **customer engineering** and **self-serve users**. We believe that **all docs need agents**, and **all websites need agents**, because people would rather prompt than search for info.

If you ask a **generic LLM** and point it at the docs page, you tend to get **more general, less relevant** responses (based on qualitative review). Our agent gives **very specific, detailed** answers; the docs provided to it **more precisely constrain** the information it can use. In short: it's a **better docs agent**, and you can set one up for yourself in **hours**.

Compared with web search, **basic RAG** or no citations:

* **Citations are key** — People often want to **read the source doc** after the initial response: to verify, go deeper, or share the link. This agent cites every factual claim and adds a References section with doc URLs.
* **Multi-step retrieval** — Single-shot RAG can miss context or mix in irrelevant chunks; Agentic Search does breadth-then-depth over the docs and produces more precise answers.
* **Grounded generation** — Responses are generated only from retrieved content, reducing hallucination.

We've already seen users rely on it for **troubleshooting** and support-style questions—before we had even written about it—because they can trust the references and follow them into the docs.

## Challenges we solved with this agent

Running a docs agent well comes with a few realities we've designed for:

* **Multimodal content** — Documentation often has important information in **images** (diagrams, screenshots, UI). Our pipeline handles multimodal content state-of-the-art: we parse and index both text and images so the agent can retrieve and use information from figures, screenshots, and diagrams, not just body text.
* **Keeping the agent up to date** — Docs change **many times a day**. The agent must stay in sync with the latest content. You can do that with [Contextual AI connectors](/connectors/overview) (e.g. Confluence, SharePoint, Google Drive), or—for GitHub-backed docs—with the **code we wrote and share**: [**datastore-sync**](https://github.com/ContextualAI/datastore-sync). It syncs your repo (and optionally your website) into a Contextual AI datastore via webhooks and incremental updates so the agent always has fresh content.
* **Citations** — As above: citations aren't just for trust; they let users **open the source** and read the full doc after the initial response.
* **Repo vs. web:** Unlike searching docs via the web, our documentation lives in our **GitHub repo** and we sync only what's published (e.g. pages in nav, `docs.json`). We may have **outdated or unlisted pages** in the repo that still exist but aren't findable on the site—our agent **won't surface those**, because they're not in the synced datastore. LLMs that use web search can sometimes surface those older or hidden pages; our agent deliberately reflects only the docs we publish, so answers stay aligned with what we actually ship.

## How it works

1. **Your documentation as data:** These docs are ingested into a Contextual AI datastore, chunked and indexed. They're kept in sync so when content is updated, the agent has the latest info (here, via sync code we share; see below).

2. **Keyword search + agent:** Mintlify's built-in search returns keyword-based results immediately. The agent then runs the [Agentic Search](/how-to-guides/agent-composer-templates#agentic-search) template—multi-turn research over the datastore—and streams a response with citations and a References section.

3. **Grounded generation:** Answers are generated only from the research step, with citations in `[n]()` format and links to the documentation URLs.

## Try it

Use the search bar at the top and ask a question about Contextual AI.

## Build your own: sync + agent

We share the building blocks so you can run a documentation agent on your own content.

### datastore-sync

Open-source repo that keeps a Contextual AI datastore in sync with your docs (and optionally your website). We use it for this site: [**ContextualAI/datastore-sync**](https://github.com/ContextualAI/datastore-sync).

* **GitHub docs sync:** Automatically syncs MDX/MD and OpenAPI specs from a GitHub repo (e.g. Mintlify docs). Incremental sync (commit SHAs, tree diffs), published-content filtering via `docs.json`, and OpenAPI parsing into per-endpoint markdown with human-readable URLs. Compiles MDX to clean PDFs before ingestion for better RAG quality.
* **Website sync (optional):** Firecrawl-based sync for other website content, with sitemap crawling and diffing (agent using this section coming soon)
* **State:** Redis-backed state (or local JSON in dev); Vercel-ready with webhook endpoints (e.g. `POST /sync/github` for GitHub push events).

Use it to feed an agent with your published documentation so it stays up to date as you push changes.

## Next steps

* [Agent Composer Documentation](/quickstarts/agent-composer) — Create and configure agents in the UI.
* [Agentic Search](/how-to-guides/agent-composer-templates#agentic-search) — Template used by this documentation agent.
* [Connectors](/connectors/overview) — Keep datastores in sync with Confluence, SharePoint, Drive, and more.
* [Template Catalog](/examples/templates-catalog) — Other templates (Basic Search, Enterprise, etc.).


# Material Science Agent
Source: https://docs.contextual.ai/examples/material-science-agent

AI agent for materials research, properties analysis, and material selection—explains like you're 5 (ELI5)

## Overview

This agent assists with material science research—answering questions about thermal properties, strength characteristics, synthesis methods, and application recommendations by drawing on thousands of arXiv research papers. It explains concepts in **ELI5** (“explain like I’m 5”) style: simple, clear, and accessible.

**Built with [Agent Composer](/quickstarts/agent-composer)** using the Agentic Search template.

## The Problem

Materials researchers spend hours searching through academic papers to find relevant property data, synthesis methods, or application guidance. Common challenges:

* Finding specific material properties across thousands of papers
* Understanding synthesis conditions and experimental parameters
* Comparing materials for specific applications
* Staying current with the latest research

## What the Agent Does

Ask the agent about material properties, and it uses multi-step reasoning to:

1. Search across 7,500+ arXiv materials science papers
2. Identify relevant research and experimental data
3. Synthesize findings from multiple sources
4. Return verified answers with citations to source papers

## Example Questions

* **ELI5**: "Explain quantum magnets like I'm 5"
* **Property lookup**: "What are the thermal conductivity properties of graphene oxide composites?"
* **Synthesis guidance**: "How do I synthesize high-purity titanium dioxide nanoparticles?"
* **Material comparison**: "Compare the mechanical properties of carbon fiber vs glass fiber reinforced polymers"
* **Application research**: "What materials are best suited for high-temperature battery electrodes?"

## Try the Demo

<Card title="Launch Demo" icon="atom" href="https://demo.contextual.ai/material-science">
  Try the Material Science agent
</Card>

## Learn More

* [Agent Composer Documentation](/quickstarts/agent-composer)
* [Global Datastores](/connectors/global-datastores) — This demo uses the arXiv Materials Science datastore


# Mazda Infotainment Log Analysis Agent
Source: https://docs.contextual.ai/examples/mazda-infotainment-log-analysis

AI agent for automated root cause analysis of Mazda Connect infotainment system crash logs

## Overview

This agent performs automated root cause analysis on Mazda Connect infotainment system logs. It cross-references CMU (Car Media Unit) event logs against a debug reference guide to decode crash sequences, identify software faults, and trace the root cause of system restarts—including subtle failure modes like format string vulnerabilities triggered by podcast metadata.

**Powered by the [Device Log Analysis](/how-to-guides/agent-composer-templates#device-log-analysis-enterprise) template** in [Agent Composer](/quickstarts/agent-composer)—available for Enterprise customers; [request a demo](https://contextual.ai/request-a-demo) for access.

## Try the Demo

<Card title="Launch Demo" icon="car" href="https://demo.contextual.ai/log-analysis">
  Analyze infotainment logs yourself
</Card>

Mazda samples preloaded—pick a suggested query and run the analysis.

<Note>
  Running on the production DLA template. Demo queries are cached and sped up for demonstration purposes.
</Note>

## The Problem

When an embedded vehicle system crashes repeatedly, engineers must determine whether the root cause is a hardware fault, a software bug, corrupted storage, or an external data input triggering unexpected behavior. Mazda Connect CMU logs contain:

* Boot diagnostics (ROM CRC, RAM test, NAND mount, crash log presence)
* Podcast feed sync events including RSS fetch, metadata parse, and format string scanning
* Watchdog timer heartbeats and timeout sequences
* Per-subsystem events across CMU-SYS, CMU-POD, CMU-META, CMU-RSS, CMU-AUDIO, CMU-BT, CMU-NAV, CMU-DISP
* Crash dumps, reboot reason codes, and NAND storage error logs
* Recovery and workaround sequences

Without tooling, a repeating crash on podcast sync—where the failure mechanism is a C printf format string specifier buried in a show title—requires deep familiarity with both the CMU firmware architecture and the specific `%n` conversion specifier behavior to diagnose correctly.

## The Real Story

In 2014–2016, thousands of Mazda owners discovered their car stereos were stuck in a reboot loop. The culprit turned out to be a podcast: "99% Invisible," hosted by Roman Mars.

The infotainment system's podcast player was written in C and used `printf()` to display show titles on screen. The title "99% Invisible" contains a percent sign. In C, `printf()` treats `%` as the start of a special formatting instruction. When the software tried to display the title, it didn't just show the text — it tried to interpret `% In...` as a format code.

Specifically, the sequence `%In` means:

* `%` — start of a format specifier
* ` ` — space flag (valid modifier)
* `I` — length modifier (valid)
* `n` — write the number of bytes printed so far to a memory address

The `%n` specifier is dangerous because it writes data to a pointer. The software didn't supply a pointer — it was null (0x00000000). Writing to a null pointer causes an immediate crash: a segmentation fault (SIGSEGV). The system's watchdog timer detected the crash, rebooted... and immediately crashed again trying to sync the same feed. This happened every time the car started, producing an infinite reboot loop.

The fix: a developer created an alternate podcast feed with the title "99 Percent Invisible" — spelling out the percent sign to avoid triggering the bug.

This story was covered on Reply All Episode #140 and [99% Invisible Episode #350](https://99percentinvisible.org/episode/the-roman-mars-mazda-virus/).

## How It Works

### In production

**What you do:** Upload a **CMU event log** and optionally a **debug reference guide**, then ask a query—for example *"Why did my car stereo restart?"*.

**What happens automatically:** A multi-agent implementation takes over. The system parses the log, builds a searchable database from the log and reference files, runs root cause analysis, and produces outputs.

**Pipeline stages:** Uploading files → parsing logs → building the database → root cause analysis → generating the report.

**Outputs:** The agent delivers a **detailed RCA report** covering executive summary, session-by-session timeline, crash sequence decoded step-by-step, root cause identification, and recommended actions. It correctly distinguishes between NAND storage warnings (a red herring) and the actual crash trigger.

**Auditable:** Every step is visible—tasks, trajectory, intermediate artifacts, and the final report—so teams can follow the reasoning and verify the diagnosis.

### In this demo

Sample Mazda CMU files are **preloaded**; choose a suggested query and run the analysis.

## Example Questions

Suggested queries in the demo:

* "Why did my car stereo restart?"
* "Was the NAND storage error related to the crash?"
* "What exactly is the format string vulnerability and how does it work?"

## Output

Example outputs from the three suggested queries:

**"Why did my car stereo restart?"** — Full incident timeline showing the CMU's progression from normal operation through degraded mode, five recovery attempts, and final recovery. The event flow traces PANIC/WDT, fault handler, format engine, feed/parse layer, and user/system events — pinpointing the `%n` null pointer SIGSEGV triggered by the "99% Invisible" podcast title as the root cause:

<img alt="Mazda CMU stereo restart RCA — incident timeline from normal operation through crash and recovery" />

**"Was the NAND storage error related to the crash?"** — Crash timeline showing the sequence of events, confirming the NAND storage warning is a coincidental pre-existing condition and not causally related to the podcast-triggered crash:

<img alt="Crash timeline — NAND error vs podcast crash sequence" />

**"What exactly is the format string vulnerability and how does it work?"** — Detailed timeline of the format string exploitation path: RSS fetch → metadata parse → SHOW\_TITLE\_PARSE → FMTSTR\_SCAN miss → printf call → `%n` writes bytes-written count to a null pointer → SIGSEGV:

<img alt="Format string vulnerability timeline — from RSS fetch to null pointer write and crash" />

The **final RCA report** includes:

* **Executive summary** — Root cause (podcast feed sync triggering a printf format string vulnerability via `% In` in the show title "99% Invisible"), crash mechanism, and impact (boot loop until workaround applied)
* **Session comparison** — Session 1 (healthy baseline, subscription added) vs. Session 2 (crash, boot loop, recovery) with key differences highlighted
* **Crash sequence decoded** — Step-by-step walkthrough of the failure: RSS fetch → metadata parse → SHOW\_TITLE\_PARSE → FMTSTR\_SCAN miss → printf call → null pointer write (SIGSEGV) → watchdog timeout → reboot
* **Red herring analysis** — Explains why the NAND storage warning is coincidental and not causally related to the crash
* **Technical explanation** — How `% In` is parsed: `%` triggers format spec scan, space is a flag, `I` is a length modifier, `n` is the conversion specifier that writes bytes-written count to a null pointer, causing the segfault
* **Recommended actions** — Subscribe to the alternative feed "99 Percent Invisible" (no `%` character) as an immediate workaround; firmware fix is to sanitize show titles before passing to printf

## Mazda sample files in the demo

* **Device log** (`mazda_device_log_30mb.txt`) — A two-session CMU event log spanning a healthy baseline session (podcast subscription, normal playback) and a failure session (feed sync crash, five-cycle boot loop, and workaround recovery). Log entries include severity (INFO/WARN/ERROR), subsystem tags, and event codes.
* **Debug reference guide** (`mazda_debug_rules.txt`) — A CMU debug reference covering subsystem tag definitions, event code catalog, format string vulnerability explanation (including the exact byte sequence `[0x25, 0x20, 0x49, 0x6E]` = `"% In"`), watchdog behavior, NAND error classification, and recovery procedures.

## Learn More

* [Device Log Analysis (overview)](/examples/device-log-analysis) — General DLA template and all three sample datasets
* [3GPP Wireless](/examples/3gpp-wireless-log-analysis) — LTE-style eNB/device logs
* [ATE Board Validation](/examples/ate-log-analysis) — Board validation / tester logs
* [Getting Started with the Contextual AI Platform](/quickstarts/getting-started)
* [Agent Composer Templates](/how-to-guides/agent-composer-templates) — Basic Search, Agentic Search, and Device Log Analysis (Enterprise)
* [Request a demo](https://contextual.ai/request-a-demo)


# Contextual AI Demos
Source: https://docs.contextual.ai/examples/overview-demos

Explore real-world use cases and live demos

Contextual AI's demos showcase how our platform and API components power intelligent, grounded, and secure AI experiences across industries. All of these demos are built with [Agent Composer](/quickstarts/agent-composer)—our framework for building customized agent workflows. To learn how to create and configure agents, see the [Agent Composer documentation](/quickstarts/agent-composer) and the [Introducing Agent Composer blog post](https://contextual.ai/blog/introducing-agent-composer).

<img alt="Alt text" />

## Overview

Each demo highlights a real-world scenario—from customer support copilots that draw on private knowledge bases to research assistants that understand context across documents and data sources. You'll see how Contextual AI unifies retrieval, reasoning, and generation to deliver answers that are accurate, explainable, and compliant.

## Live Demos

<CardGroup>
  <Card title="Rocket Science" icon="rocket" href="https://demo.contextual.ai/propulsion-agent">
    Root cause analysis for rocket engine anomalies
  </Card>

  <Card title="Raspberry Pi Agent" icon="microchip" href="https://demo.contextual.ai/customer-engineering">
    Technical support for Raspberry Pi hardware
  </Card>

  <Card title="Material Science" icon="atom" href="https://demo.contextual.ai/material-science">
    Research assistant for materials properties and synthesis
  </Card>

  <Card title="Test Program Generation" icon="code" href="https://demo.contextual.ai/test-code-generation">
    Generate OpenTAP test programs and instrument drivers
  </Card>

  <Card title="Device Log Analysis" icon="tower-cell" href="/examples/device-log-analysis">
    Root cause analysis for device logs — overview and demos
  </Card>

  <Card title="3GPP Wireless" icon="tower-cell" href="/examples/3gpp-wireless-log-analysis">
    Root cause analysis for 3GPP LTE device logs
  </Card>

  <Card title="ATE Board Validation" icon="microchip" href="/examples/ate-log-analysis">
    Root cause analysis for ATE board validation failures
  </Card>

  <Card title="Mazda Infotainment" icon="car" href="/examples/mazda-infotainment-log-analysis">
    Root cause analysis for Mazda Connect infotainment crash logs
  </Card>

  <Card title="3GPP Spec Explorer" icon="magnifying-glass" href="https://demo.contextual.ai/3gpp-agentic-search">
    Search and reason over 3GPP specifications (Release 19 and others)
  </Card>
</CardGroup>

## Experiment with Contextual AI in Action

Some of these demos are fully interactive, while others are full-realized notebooks that allow you to explore the platform's capabilities hands-on, at the code level. Learn how developers use Contextual AI's APIs, connectors, and structured output features to build reliable AI agents that adapt to enterprise workflows.

## More Resources

For more demos and sample code, please visit the following:

* [All Demos](https://demo.contextual.ai)
* [GitHub Repos](https://github.com/ContextualAI)
* [Hugging Face](https://huggingface.co/ContextualAI)


# Raspberry Pi Documentation Agent
Source: https://docs.contextual.ai/examples/raspberry-pi-agent

AI agent for technical support and troubleshooting of Raspberry Pi hardware

## Overview

This agent answers complex technical questions about Raspberry Pi hardware—synthesizing information across datasheets, SDK documentation, and troubleshooting guides to deliver accurate answers in seconds instead of hours.

**Built with [Agent Composer](/quickstarts/agent-composer)** using the Agentic Search template, available in self-serve.

## The Problem

Engineers and hobbyists spend hours piecing together information from datasheets, SDK docs, and community forums to answer a single Raspberry Pi question. Common challenges:

* GPIO pinout confusion between physical pins and BCM numbers
* Troubleshooting boot issues from LED blink codes
* Understanding differences between Pi models (Pi 5 vs Pico)
* Wiring multiple components together correctly

## What the Agent Does

Ask the agent: *"Why isn't my Raspberry Pi able to get power?"*

The agent uses multi-step reasoning to:

1. Identify possible power issues from documentation
2. Cross-reference hardware specifications
3. Synthesize troubleshooting steps from multiple sources
4. Return verified answers with source citations

## Example Questions

* **Vague troubleshooting**: "My camera was working yesterday but now I get 'No cameras available'. The green LED blinks 4 times when I boot. Are these related?"
* **Hardware guidance**: "Which GPIO pins should I use for my DHT22 temperature sensor?"
* **Platform clarification**: "Can I use MicroPython on a Raspberry Pi 5 like I would on a Pico?"
* **Project builds**: "How do I wire a DHT22, OLED screen, and Camera Module 3 together for a weather station?"

## Try the Demo

<Card title="Launch Demo" icon="microchip" href="https://demo.contextual.ai/customer-engineering">
  Try the Raspberry Pi agent
</Card>

<Note>
  The demo has **web search** enabled for broader coverage, but the YAML configuration below does not include it since web search is an enterprise feature. The YAML works out-of-the-box for self-serve users with the Agentic Search template.
</Note>

## Agent YAML

This agent uses the Agentic Search template, available in self-serve. You can create your own agent using the YAML below—just replace the datastore ID with your own Raspberry Pi documentation datastore.

<Accordion title="View full YAML configuration">
  ```yaml theme={null}
  version: "0.1"
  inputs:
    query: str
  outputs:
    response: str
  ui_output: response
  nodes:
    __outputs__:
      type: output
      input_mapping:
        response: generate_from_research_step#response
    agentic_research_step:
      type: AgenticResearchStep
      input_mapping:
        message_history: create_message_history_step#message_history
      ui_stream_types:
        retrievals: true
      config:
        tools_config:
          - name: search_docs
            description: |
              Search the datastore containing user-uploaded documents. This datastore is a vector database of text chunks which uses hybrid semantic and lexical search to find the most relevant chunks.
              Use this tool to find information within the uploaded documents.
            step_config:
              type: SearchUnstructuredDataStep
              ui_stream_types:
                query_reformulation: true
              config:
                datastores:
                  - <your-raspberry-pi-datastore-id>
                enable_query_decomposition: false
                enable_query_expansion: false
                filter_retrievals: false
                lexical_alpha: 0.1
                rerank_retrievals: true
                rerank_top_k: 12
                reranker: ctxl-rerank-v2-instruct-multilingual-FP8
                reranker_score_filter_threshold: 0.2
                semantic_alpha: 0.9
                should_check_retrieval_need: true
                top_k: 50
                untrusted_filter_prompt: |-
                  You are a precision filter for domain-specific documentation. Your task is to determine if a text chunk is directly relevant to a given query. Output only Yes or No.

                  Evaluate relevance based on these criteria:

                  * Contains specific details that directly answer or address the query
                  * Provides factual information central to the query topic
                  * Offers concrete examples or applications related to the query
                  * Explains key concepts or definitions needed to understand the query
                  * Contains relevant supporting evidence or documentation

                  Consider a chunk relevant if it:

                  * Directly addresses the queried topic/concept
                  * Provides essential context required to understand the query
                  * Contains prerequisite information needed for comprehension
                  * Documents related exceptions or special cases
                  * Describes important relationships with the queried topic

                  Reject chunks that:

                  * Contain only general introductions or section headers
                  * Have tangential references without substantial detail
                  * Describe unrelated topics or concepts
                  * Contain promotional or non-substantive content
                  * Only provide navigational/structural information

                  Example:
                  Query: "How to configure user authentication settings"
                  Text: "Chapter 3: Security Features. This section covers various security mechanisms including authentication, encryption, and access control."
                  Response: No

                  YOU MUST:
                  * Output only Yes or No
                  * Stop immediately after your response
                  * Be strict about relevance
                  * Reject vague or general content
                  * Reject all chunks if the query is conversational, generic, or non-technical (e.g., "how are you", "tell me a joke")
                  * Reject all chunks if the query combines technical topics with any suggestive or inappropriate language, particularly references to unethical, racist or offensive behavior.
        agent_config:
          agent_loop:
            identity_guidelines_prompt: |
              You are a retrieval-augmented assistant created by Contextual AI. You provide factual, grounded answers to user's questions by retrieving information via tools and then synthesizing a response based only on what you retrieved.
            model_name_or_path: vertex_ai/claude-sonnet-4-5@20250929
            num_turns: 10
            parallel_tool_calls: false
            research_guidelines_prompt: |
              You have access to the following tool:
              - `search_docs` — Search the document datastore. Returns SEARCH_RESULTS with CITE_ID for citation.

              You have access to the following data source:
              1. Document Datastore (Unstructured):
                  - Contains user-uploaded documents that have been parsed, extracted, and chunked for efficient retrieval.
                  - Use the `search_docs` tool to query this datastore for relevant content, details, and information from the available documents.

              ## Research Strategy
              You MUST always explore unstructured datastore before answering. Do not skip the source.
              - Breadth, then depth strategy:
                  1.  CLARIFICATION NEEDED? If the user question is vague (e.g. my device isn't working), go back to the user and ask a clarifying question about the exact symptoms they are seeing. 
                  2. INITIAL RETRIEVAL - FIRST (Mandatory):
                    - Documents: Use `search_docs` with your initial search terms.
                  3. ANALYZE & PLAN: Review initial results and create a query plan:
                    - What information is still missing to fully answer the question?
                    - Create a specific plan: which queries to run next and in what order
                    - Identify dependencies: what do you need to find first before searching for related info?
                  4. DEEP DIVE (Execute & Adapt): Execute your plan and adapt based on retrieved content:
                    - Run planned queries systematically
                    - Continue until you have a COMPLETE answer - don't stop early
              - EFFICIENCY: You have 10 turns. Be strategic:
                  - Avoid redundant searches; prefer high-quality retrievals.
                  - Batch related searches when possible
                  - Don't repeat similar queries
                  - Prioritize high-value retrievals first
                  - But DO NOT sacrifice comprehensiveness for speed - gather ALL relevant information
    create_message_history_step:
      type: CreateMessageHistoryStep
      input_mapping:
        query: __inputs__#query
      ui_stream_types:
        retrievals: false
      config:
        should_check_retrieval_need: true
        untrusted_no_retrieval_system_prompt: |
          You are an AI RAG agent created by Contextual to help answer questions and complete tasks posed by users. Your capabilities include accurately retrieving/reranking information from linked datastores and using these retrievals to generate factual, grounded responses. You are powered by leading document parsing, retrieval, reranking, and grounded generation models. Users can impact the information you have access to by uploading files into your linked datastores. Full documentation, API specs, and guides on how to use Contextual, including agents like yourself, can you found at docs.contextual.ai. 

          In this case, there are no relevant retrievals that can be used to answer the user's query. This is either because there is no information in the sources to answer the question or because the user is engaging in general chit chat. Respond according to the following guidelines:

          - If the user is engaging in general pleasantries ("hi", "how goes it", etc.), you can respond in kind. But limit this to only a brief greeting or general acknowledgement
          - Your response should center on describing your capabilities and encouraging the user to ask a question that is relevant to the sources you have access to.  You can also encourage them to upload relevant documents and files to your linked datastore(s). 
          - DO NOT answer, muse about, or follow-up on any general questions or asks. DO NOT assume that you have knowledge about any particular topic. DO NOT assume access to any particular source of information. 
          - DO NOT engage in character play. You must maintain a friendly, professional, and neutral tone at all times
        untrusted_system_prompt: |-
          You are a helpful AI assistant created by Contextual AI to answer questions about relevant documentation provided to you. Your responses should be precise, accurate, and sourced exclusively from the provided information. Please follow these guidelines:
          * Only use information from the provided documentation. Avoid opinions, speculation, or assumptions.
          * Use the exact terminology and descriptions found in the provided content.
          * Keep answers concise and relevant to the user's question.
          * Use acronyms and abbreviations exactly as they appear in the documentation or query.
          * Apply markdown if your response includes lists, tables, or code. Do not include backticks around markdown tables.
          * Directly answer the question, then STOP. Avoid additional explanations unless specifically relevant.
          * If the knowledge provided is totally irrelevant and not related to the question at all, only in this case respond that you don't have relevant documentation and do not provide additional comments or suggestions. Ignore anything that cannot be used to directly answer this query.

          VERY IMPORTANT:
          - Attributions MUST be in the format of [n]() instead of only [n]
          - Attributions MUST always be in the format [n]()[n+1]()[n+2]() not in [n,n+1,n+2]. For example attributions should not be [3,4,5] but [3]()[4]()[5](). Do not repeat the same number if it is attributed multiple times.
          - Never add extra () in attributions. Only use [n]() and not [n]()()
    generate_from_research_step:
      type: GenerateFromResearchStep
      input_mapping:
        message_history: create_message_history_step#message_history
        research: agentic_research_step#research
      ui_stream_types:
        generation: true
      config:
        identity_guidelines_prompt: |
          You are a retrieval-augmented assistant created by Contextual AI. Your purpose is to provide factual, grounded answers by retrieving information via tools and then synthesizing a response based only on what you retrieved. Always start immediately with the answer, don't begin with a preamble or thoughts.
        model_name_or_path: vertex_ai/claude-sonnet-4-5@20250929
        response_guidelines_prompt: |
          ## Output
          - if the research steps asks for clarification, please generate a clear question for the user to provide more details.
          - Write a concise, direct, well-structured answer in **Markdown** (use short headings, bullets, and brief paragraphs).
          - **START IMMEDIATELY WITH THE ANSWER.** Never begin with preamble like:
            - "Perfect!", "Great!", "Based on my research...", "I now have comprehensive information..."
            - "Let me provide...", "I can now provide...", "Here's what I found..."
            - Any meta-commentary about your search process or confidence level
          - Your first words should be the actual content (a heading, the direct answer, or the key fact).
          - If the required fact is missing from the latest **SEARCH_RESULTS**:
            - Partial or Related Information: Provide whatever relevant details you found, while clearly stating the limitations or gaps.
            - No Relevant Information: If nothing related was found, reply with: "I don't have specific information about [topic] in the available documents."
            - Maintain Engagement: Suggest related topics or alternative ways you can assist to keep the interaction productive.
          - DO NOT engage in character play. You must maintain a friendly, professional, and neutral tone at all times.
  ```
</Accordion>

## Learn More

* [Agent Composer Documentation](/quickstarts/agent-composer)
* [Agent Composer YAML Guide](/how-to-guides/agent-composer-yaml)


# Propulsion Anomaly Investigation Agent
Source: https://docs.contextual.ai/examples/rocket_science

AI agent for root cause analysis of rocket engine test anomalies

## Overview

This agent investigates anomalies in rocket engine hot fire tests. It synthesizes data across telemetry, hardware logs, inspection reports, and manufacturing records to identify root causes—work that would normally take engineers hours of cross-referencing disparate systems.

**Built with [Agent Composer](/quickstarts/agent-composer)**, Contextual AI's new framework for production-ready AI agents.

## Watch the Demo

<iframe title="Vimeo video player" />

## The Scenario

**Test 142: ME-1 Engine Static Fire**

A 15-second hot fire test of a methane/LOX engine just completed. The results:

* Chamber pressure 4.2% below prediction
* Thrust 3.8% low
* No redline violations, no abort—just underperformance

The engine ran fine on Test 141 two weeks ago. What changed?

## What the Agent Does

Ask the agent: *"We just completed TEST-142 on ME-1-002. Chamber pressure came in about 4% below prediction. What's going on?"*

The agent connects the dots across:

1. **Telemetry** showing low fuel flow and high mixture ratio
2. **Hardware change logs** showing an injector was replaced between tests
3. **Inspection reports** explaining why the original injector was swapped
4. **Manufacturing records** revealing the replacement injector's orifice diameter is at the low end of tolerance
5. **Historical data** showing this manufacturing lot has had similar issues

The agent surfaces the root cause: a fuel injector flow restriction caused by a replacement part from a different manufacturing lot.

## Output

The agent generates a root cause assessment with:

* Primary root cause identification
* Supporting evidence from each data source
* Citations to source documents
* Recommended next steps

## Try the Demo

<Card title="Launch Demo" icon="rocket" href="https://demo.contextual.ai/propulsion-agent">
  Investigate the anomaly yourself
</Card>

## Learn More

* [Agent Composer Documentation](/quickstarts/agent-composer)
* [Prompt Builder Quickstart](/quickstarts/prompt-builder) — Create agents using natural language
* [Agent Composer YAML Guide](/how-to-guides/agent-composer-yaml)


# Agent Composer Template Catalog
Source: https://docs.contextual.ai/examples/templates-catalog

Explore specialized AI agent templates for various domain-specific applications

## Overview

This page contains specialized AI agent templates for various domain-specific applications. Each template is configured with custom prompts, tools, and workflows to provide expert-level assistance in its respective field.

<Note>
  Templates here that are **not** based on [Basic Search](/how-to-guides/agent-composer-templates#basic-search) or [Agentic Search](/how-to-guides/agent-composer-templates#agentic-search) are available only for Enterprise. [Request a demo](https://contextual.ai/request-a-demo) to use them. See [Agent Composer Templates](/how-to-guides/agent-composer-templates) for availability by template type.
</Note>

<CardGroup>
  <Card title="Engineering/Heavy Industry" icon="oil-well" href="#engineering-/-heavy-industry" />

  <Card title="Enterprise & Legal" icon="gavel" href="#enterprise-&-legal" />

  <Card title="Aerospace" icon="rocket" href="#aerospace" />

  <Card title="Semiconductor" icon="microchip" href="#semiconductor" />

  <Card title="Materials Science" icon="atom" href="#materials-science" />
</CardGroup>

***

## Engineering / Heavy Industry

[Drilling Operations Advisor (drilling\_operations\_advisor.yml)](https://github.com/ContextualAI/agent-composer/blob/main/templates/drilling_operations_advisor.yml)

A decision support specialist for oil and gas drilling operations that analyzes real-time drilling data and offset well performance:

* **Risk Identification:** Stuck pipe, kicks, lost circulation, wellbore instability
* **Data Analysis:** MWD/LWD data, geological prognosis, alarm sequences, drilling parameters
* **Performance Optimization:** ROP benchmarking, parameter recommendations, NPT reduction
* **Regulatory Context:** SPE papers, IADC guidelines, industry best practices

Use Cases: Real-time drilling optimization, risk assessment, NPT prevention, offset well analysis

[Equipment Failure Predictive Maintenance (equipment\_failure\_predictive\_maintenance.yml)](https://github.com/ContextualAI/agent-composer/blob/main/templates/equipment_failure_predictive_maintenance.yml)

A reliability engineering advisor for industrial facilities that predicts equipment failures before they occur:

* **Condition Monitoring:** Vibration analysis, oil analysis, thermal imaging, ultrasonic testing
* **Failure Mode Analysis:** FMEA documents, OEM manuals, historical failure patterns
* **Maintenance Planning:** Intervention timing, parts availability, cost-benefit analysis
* **Risk Assessment:** Criticality evaluation, failure probability, production impact

Use Cases: Predictive maintenance, equipment reliability analysis, maintenance scheduling, failure investigation

[Process Safety Incident Investigator (process\_safety\_incident\_investigator.yml)](https://github.com/ContextualAI/agent-composer/blob/main/templates/process_safety_incident_investigator.yml)

A systematic incident investigation specialist for chemical and petrochemical facilities:

* **Investigation Protocol:** Timeline reconstruction, barrier analysis (Swiss Cheese model), root cause identification
* **Data Sources:** Alarm historian, DCS parameters, P\&IDs, HAZOP reports, SOPs, MOC records
* **Regulatory Compliance:** OSHA PSM, EPA RMP, CSB database searches
* **Output:** Comprehensive investigation reports with CAPA recommendations

Use Cases: Process safety investigations, near-miss analysis, NPT root cause analysis, safety audits

***

## Enterprise & Legal

[Fast Search (fast\_search.yaml)](https://github.com/ContextualAI/agent-composer/blob/main/templates/fast_search.yaml)

A streamlined, lightweight search template for quick document retrieval and response generation:

* **Simple Architecture:** Direct search-to-response pipeline without multi-turn research
* **Fast Performance:** Minimal configuration for rapid queries
* **Basic RAG:** Standard retrieval with citation and groundedness tracking

Use Cases: Quick lookups, simple Q\&A, straightforward document search

[Patent Reasoning (patent\_reasoning.yaml)](https://github.com/ContextualAI/agent-composer/blob/main/templates/patent_reasoning.yaml)

A specialized patent analysis agent that conducts rigorous legal-technical investigations:

* **Analysis Types:** Prior art search, claim interpretation, infringement analysis, freedom to operate
* **Claim Decomposition:** Element-by-element parsing, means-plus-function identification
* **Search Strategy:** Patent classification search, citation chains, non-patent prior art
* **Legal Framework:** Anticipation, obviousness, doctrine of equivalents

Use Cases: Patent validity analysis, infringement assessment, prior art searches, claim construction

[Deep Research (deep\_research.yml)](https://github.com/ContextualAI/agent-composer/blob/main/templates/deep_research.yml)

A comprehensive retrieval-augmented research assistant that conducts thorough, multi-step investigations across document repositories. Follows a structured five-phase protocol:

* **Query Analysis & Planning:** Decomposes questions into sub-questions and creates search strategies
* **Broad Discovery:** Maps the information landscape with diverse searches
* **Deep Exploration:** Drills into promising areas with targeted queries
* **Gap Analysis:** Identifies and fills blind spots in retrieved information
* **Synthesis:** Integrates findings with precise citations

Use Cases: Academic research, technical documentation analysis, comprehensive fact-finding

[Demand Forecasting (demand\_forecasting.yml)](https://github.com/ContextualAI/agent-composer/blob/main/templates/demand_forecasting.yml)

An intelligent supply chain planning assistant designed for demand planners, inventory managers, and business analysts. Provides end-to-end forecasting capabilities:

* **Data Sources:** Sales history, inventory levels, supplier information, market reports, forecast accuracy metrics
* **Analysis Tools:** Statistical forecasting, code execution for calculations, trend visualization
* **Output Options:** Forecast reports, charts, executive presentations (PowerPoint generation)
* **External Intelligence:** Web search for market trends and economic indicators

Use Cases: Demand planning, inventory optimization, sales trend analysis, safety stock calculations

***

## Aerospace

[Rocket Anomaly Detection (rocket\_anomaly\_detection.yml)](https://github.com/ContextualAI/agent-composer/blob/main/templates/rocket_anomaly_detection.yml)

A propulsion anomaly investigation agent for rocket engine test engineers:

* **Anomaly Characterization:** Identifies performance deviations from expected parameters
* **Data Integration:** Test telemetry, hardware change logs, manufacturing records, historical anomaly databases
* **Pattern Matching:** Correlates symptoms with known failure mode signatures
* **Root Cause Analysis:** Systematically narrows down potential causes using evidence

Use Cases: Post-test anomaly investigation, engine performance diagnosis, failure mode identification

[Rocket Test Readiness Compliance Agent (rocket\_test\_readiness\_compliance\_agent.yml)](https://github.com/ContextualAI/agent-composer/blob/main/templates/rocket_test_readiness_compliance_agent.yml)

A Test Readiness Review (TRR) assistant for rocket propulsion testing compliance:

* **Standards Compliance:** NASA-STD-8719.24, NPR 8715.3, NASA-STD-8719.12, NASA-STD-5012, NASA-STD-8739.8
* **Verification Checks:** Instrumentation calibration, propellant qualification, safety reviews, personnel certifications
* **Data Cross-Reference:** Matches regulatory requirements against actual test data
* **Output:** TRR verification matrices with go/no-go recommendations

Use Cases: Pre-test readiness verification, regulatory compliance checks, safety certification

***

## Semiconductor

[Semiconductor Test Program Generation (semiconductor\_test\_program\_generation.yml)](https://github.com/ContextualAI/agent-composer/blob/main/templates/semiconductor_test_program_generation.yml)

A specialized assistant for generating test programs for semiconductor devices:

* **Documentation Analysis:** Datasheets, test specifications, application notes, pin configurations
* **Test Program Elements:** Device configuration, test sequences, parametric tests, pass/fail criteria
* **Technical Parameters:** Electrical characteristics, timing parameters, voltage levels, current ratings
* **Output:** Complete test programs with proper citations to source documentation

Use Cases: Semiconductor test development, ATE programming, device validation, quality assurance

[Semiconductor Tech Customer Support (semis\_tech\_customer\_support.yml)](https://github.com/ContextualAI/agent-composer/blob/main/templates/semis_tech_customer_support.yml)

A technical support assistant specializing in semiconductor product troubleshooting:

* **Knowledge Sources:** Product manuals, datasheets, application notes, support case history database
* **Issue Resolution:** Functional failures, performance degradation, integration challenges, design limitations
* **Interface Support:** SPI, I2C, UART, USB, Ethernet, PCIe
* **Presentation Generation:** Creates PowerPoint presentations for technical findings

Use Cases: Customer support, technical troubleshooting, product integration assistance, design advisory

***

## Materials Science

**Material Science Agent**

A research assistant for materials science that answers questions about thermal properties, strength characteristics, synthesis methods, and material selection by searching thousands of arXiv research papers. Explains in **ELI5** (“explain like I’m 5”) style—simple, clear, and accessible:

* **Property Analysis:** Thermal conductivity, mechanical strength, electrical properties, chemical stability
* **Synthesis Guidance:** Methods, conditions, experimental parameters, process optimization
* **Material Comparison:** Side-by-side property comparisons across material classes
* **Application Research:** Material recommendations for specific use cases and environments

Use Cases: Materials research, property lookup, synthesis guidance, material selection, literature review

```yaml theme={null}
version: "0.1"
inputs:
  query: str
outputs:
  response: str
ui_output: response
nodes:
  __outputs__:
    type: output
    input_mapping: {}
```


# Agent Composer Templates
Source: https://docs.contextual.ai/examples/templates-overview

Explore specialized AI agent templates for various domain-specific applications

## Getting Started

* Select the template that best matches your use case
* Navigate to the [Contextual AI app](https://app.contextual.ai), go to **Agents** → **New agent**
* Configure via blank canvas
* Configure datastore connections
* Import template
* Drag & Drop your template of choice
* Customize prompts and parameters as needed

## Template Structure

Each template follows a consistent YAML structure:

```yaml theme={null}
version: "0.1"
inputs:
  query: str
outputs:
  response: str
nodes:
  # Node definitions with types, mappings, and configurations
```

## Common Node Types

* **`CreateMessageHistoryStep`:** Initializes conversation context
* **`AgenticResearchStep`:** Multi-turn research with tool access
* **`ResponseGenFromResearchStep`:** Generates responses from research findings
* **`SearchUnstructuredDataStep`:** Retrieves relevant documents
* **`SearchStructuredDataStep`:** Queries structured databases
* **`DynamicAgentStep`:** Flexible agent with dynamic tool selection

## Citation Standards

All templates enforce strict citation requirements:

* Citation format: number, where number is a `CITE_ID` from search results
* Every factual statement must be cited immediately before final punctuation
* No invented citations; only valid `CITE_IDs` from current search results

## Template Customization

Key areas to customize:

* **Identity Guidelines:** Define the agent's role and capabilities
* **Research/Tool Use Guidelines:** Specify domain-specific workflows
* **Response Formatting:** Customize output structure for your needs
* **Tool Configuration:** Connect to your data sources and APIs
* **Model Selection:** Choose appropriate LLMs for your use case


# Test Program Generation
Source: https://docs.contextual.ai/examples/test-automation

AI agent for generating OpenTAP test automation code

## Overview

This agent generates production-ready test programs for the [OpenTAP](https://opentap.io/) test automation framework—synthesizing documentation, API references, and code examples to help engineers write test steps, instrument drivers, and complete test plans in seconds instead of hours.

**Built with [Agent Composer](/quickstarts/agent-composer)** using the Agentic Search template, available in self-serve.

## The Problem

Test engineers spend hours reading documentation and copying patterns to develop test programs for semiconductor and electronics manufacturing. Common challenges:

* Learning the TestStep base class patterns and lifecycle methods
* Understanding SCPI command patterns for instrument drivers
* Implementing proper verdict handling and result publishing
* Coordinating multi-step test sequences with timing and polling logic

## What the Agent Does

Ask the agent: *"I need to test a power supply"*

The agent uses multi-step reasoning to:

1. Query documentation for TestStep base class patterns
2. Find relevant examples from the OpenTAP SDK and plugins
3. Identify proper verdict handling and lifecycle methods
4. Generate complete, production-ready code with explanations

## Example Questions

* **Simple & vague**: "I need to test a power supply"
* **Test step generation**: "Create an OpenTAP test step that measures the output voltage of a power supply and fails if it's outside 4.8V to 5.2V"
* **Instrument driver**: "Create an OpenTAP SCPI instrument driver for a Keysight 34465A digital multimeter that can measure DC voltage and current"
* **Conceptual**: "What's the difference between PrePlanRun and Run in a test step? When should I use each?"

## Try the Demo

<Card title="Launch Demo" icon="code" href="https://demo.contextual.ai/test-code-generation">
  Try the Test Program Generation agent
</Card>

## Agent YAML

This agent uses the Agentic Search template, available in self-serve. You can create your own agent using the YAML below—just replace the datastore ID with your own OpenTAP documentation datastore.

<Accordion title="View full YAML configuration">
  ```yaml theme={null}
  version: "0.1"
  inputs:
    query: str
  outputs:
    response: str
  ui_output: response
  nodes:
    __outputs__:
      type: output
      input_mapping:
        response: generate_from_research_step#response
    agentic_research_step:
      type: AgenticResearchStep
      input_mapping:
        message_history: create_message_history_step#message_history
      ui_stream_types:
        retrievals: true
      config:
        tools_config:
          - name: search_docs
            description: |
              Search the datastore containing user-uploaded documents. This datastore is a vector database of text chunks which uses hybrid semantic and lexical search to find the most relevant chunks.
              Use this tool to find information within the uploaded documents.
            step_config:
              type: SearchUnstructuredDataStep
              ui_stream_types:
                query_reformulation: true
              config:
                datastores:
                  - <your-opentap-datastore-id>
                enable_query_decomposition: false
                enable_query_expansion: false
                filter_retrievals: false
                lexical_alpha: 0.1
                rerank_retrievals: true
                rerank_top_k: 12
                reranker: ctxl-rerank-v2-instruct-multilingual-FP8
                reranker_score_filter_threshold: 0.2
                semantic_alpha: 0.9
                should_check_retrieval_need: true
                top_k: 50
                untrusted_filter_prompt: |-
                  You are a precision filter for domain-specific documentation. Your task is to determine if a text chunk is directly relevant to a given query. Output only Yes or No.

                  Evaluate relevance based on these criteria:

                  * Contains specific details that directly answer or address the query
                  * Provides factual information central to the query topic
                  * Offers concrete examples or applications related to the query
                  * Explains key concepts or definitions needed to understand the query
                  * Contains relevant supporting evidence or documentation

                  Consider a chunk relevant if it:

                  * Directly addresses the queried topic/concept
                  * Provides essential context required to understand the query
                  * Contains prerequisite information needed for comprehension
                  * Documents related exceptions or special cases
                  * Describes important relationships with the queried topic

                  Reject chunks that:

                  * Contain only general introductions or section headers
                  * Have tangential references without substantial detail
                  * Describe unrelated topics or concepts
                  * Contain promotional or non-substantive content
                  * Only provide navigational/structural information

                  Example:
                  Query: "How to configure user authentication settings"
                  Text: "Chapter 3: Security Features. This section covers various security mechanisms including authentication, encryption, and access control."
                  Response: No

                  YOU MUST:
                  * Output only Yes or No
                  * Stop immediately after your response
                  * Be strict about relevance
                  * Reject vague or general content
                  * Reject all chunks if the query is conversational, generic, or non-technical (e.g., "how are you", "tell me a joke")
                  * Reject all chunks if the query combines technical topics with any suggestive or inappropriate language, particularly references to unethical, racist or offensive behavior.
        agent_config:
          agent_loop:
            identity_guidelines_prompt: |
              You are an expert Test Automation Engineer specializing in OpenTAP, the open-source test sequencing framework developed by Keysight Technologies. Your role is to help engineers design, develop, and troubleshoot test programs for semiconductor and electronics manufacturing.

              ## Your Expertise

              You have deep knowledge of:
              - **OpenTAP Architecture**: Test plans, test steps, instruments, DUTs, result listeners, and the plugin ecosystem
              - **Test Step Development**: Creating custom test steps in C# and Python, including proper use of attributes ([Display], [Unit], [ExternalParameter]), verdict handling, and result publishing
              - **Instrument Drivers**: Building SCPI-based and custom instrument plugins that follow the Open/Close resource lifecycle
              - **Test Sequencing**: Flow control, parallel execution, parent/child step relationships, and PrePlanRun/PostPlanRun patterns
              - **Best Practices**: Code organization, validation rules, error handling, logging, and production deployment

              ## How You Help

              When users ask you to generate test code, you:
              1. Ask clarifying questions if requirements are ambiguous
              2. Generate complete, production-ready code following OpenTAP conventions
              3. Include appropriate attributes, validation, logging, and result publishing
              4. Explain your design decisions and reference relevant documentation

              When users ask conceptual questions, you:
              1. Provide clear explanations with code examples
              2. Reference the official OpenTAP documentation when applicable
              3. Distinguish between OpenTAP core features and Keysight PathWave Test Automation extensions

              ## Code Style

              Always follow these conventions:
              - Use `[Display]` attributes with descriptive names and groups
              - Add `[Unit]` attributes to numeric properties where applicable
              - Implement validation rules in constructors for related settings
              - Use `Log.Info/Warning/Error` for status messages
              - Call `UpgradeVerdict()` to set Pass/Fail/Inconclusive outcomes
              - Publish results using `Results.Publish()` for data logging
              - Follow the resource lifecycle: Open → PrePlanRun → Run → PostPlanRun → Close

              ## Constraints

              - Generate code compatible with OpenTAP 9.x and .NET 6+
              - Default to C# unless the user specifically requests Python
              - Do not assume specific instruments are available unless specified
              - Always remind users to test generated code before production use
            model_name_or_path: vertex_ai/claude-sonnet-4-5@20250929
            num_turns: 15
            parallel_tool_calls: false
            research_guidelines_prompt: |
              You have access to the following tool:
              - `search_docs` — Search the document datastore. Returns SEARCH_RESULTS with CITE_ID for citation.

              You have access to the following data source:
              1. Document Datastore (Unstructured):
                  - Contains user-uploaded documents that have been parsed, extracted, and chunked for efficient retrieval.
                  - Use the `search_docs` tool to query this datastore for relevant content, details, and information from the available documents.

              ## Research Strategy
              You MUST always explore unstructured datastore before answering. Do not skip the source.
              - Breadth, then depth strategy:
                  1. INITIAL RETRIEVAL - FIRST (Mandatory):
                    - Documents: Use `search_docs` with your initial search terms.
                  2. ANALYZE & PLAN: Review initial results and create a query plan:
                    - What information is still missing to fully answer the question?
                    - Create a specific plan: which queries to run next and in what order
                    - Identify dependencies: what do you need to find first before searching for related info?
                  3. DEEP DIVE (Execute & Adapt): Execute your plan and adapt based on retrieved content:
                    - Run planned queries systematically
                    - Continue until you have a COMPLETE answer - don't stop early
              - EFFICIENCY: You have 15 turns. Be strategic:
                  - Avoid redundant searches; prefer high-quality retrievals.
                  - Batch related searches when possible
                  - Don't repeat similar queries
                  - Prioritize high-value retrievals first
                  - But DO NOT sacrifice comprehensiveness for speed - gather ALL relevant information
    create_message_history_step:
      type: CreateMessageHistoryStep
      input_mapping:
        query: __inputs__#query
      ui_stream_types:
        retrievals: false
      config:
        should_check_retrieval_need: true
        untrusted_no_retrieval_system_prompt: |
          You are an AI RAG agent created by Contextual to help answer questions and complete tasks posed by users. Your capabilities include accurately retrieving/reranking information from linked datastores and using these retrievals to generate factual, grounded responses. You are powered by leading document parsing, retrieval, reranking, and grounded generation models. Users can impact the information you have access to by uploading files into your linked datastores. Full documentation, API specs, and guides on how to use Contextual, including agents like yourself, can you found at docs.contextual.ai. 

          In this case, there are no relevant retrievals that can be used to answer the user's query. This is either because there is no information in the sources to answer the question or because the user is engaging in general chit chat. Respond according to the following guidelines:

          - If the user is engaging in general pleasantries ("hi", "how goes it", etc.), you can respond in kind. But limit this to only a brief greeting or general acknowledgement
          - Your response should center on describing your capabilities and encouraging the user to ask a question that is relevant to the sources you have access to.  You can also encourage them to upload relevant documents and files to your linked datastore(s). 
          - DO NOT answer, muse about, or follow-up on any general questions or asks. DO NOT assume that you have knowledge about any particular topic. DO NOT assume access to any particular source of information. 
          - DO NOT engage in character play. You must maintain a friendly, professional, and neutral tone at all times
        untrusted_system_prompt: |-
          You are a helpful AI assistant created by Contextual AI to answer questions about relevant documentation provided to you. Your responses should be precise, accurate, and sourced exclusively from the provided information. Please follow these guidelines:
          * Only use information from the provided documentation. Avoid opinions, speculation, or assumptions.
          * Use the exact terminology and descriptions found in the provided content.
          * Keep answers concise and relevant to the user's question.
          * Use acronyms and abbreviations exactly as they appear in the documentation or query.
          * Apply markdown if your response includes lists, tables, or code. Do not include backticks around markdown tables.
          * Directly answer the question, then STOP. Avoid additional explanations unless specifically relevant.
          * If the knowledge provided is totally irrelevant and not related to the question at all, only in this case respond that you don't have relevant documentation and do not provide additional comments or suggestions. Ignore anything that cannot be used to directly answer this query.

          VERY IMPORTANT:
          - Attributions MUST be in the format of [n]() instead of only [n]
          - Attributions MUST always be in the format [n]()[n+1]()[n+2]() not in [n,n+1,n+2]. For example attributions should not be [3,4,5] but [3]()[4]()[5](). Do not repeat the same number if it is attributed multiple times.
          - Never add extra () in attributions. Only use [n]() and not [n]()()
    generate_from_research_step:
      type: GenerateFromResearchStep
      input_mapping:
        message_history: create_message_history_step#message_history
        research: agentic_research_step#research
      ui_stream_types:
        generation: true
      config:
        identity_guidelines_prompt: |
          You are a retrieval-augmented assistant created by Contextual AI. Your purpose is to provide factual, grounded answers by retrieving information via tools and then synthesizing a response based only on what you retrieved. Always start immediately with the answer, don't begin with a preamble or thoughts.
        model_name_or_path: vertex_ai/claude-sonnet-4-5@20250929
        response_guidelines_prompt: |
          ## Output
          - Write a concise, direct, well-structured answer in **Markdown** (use short headings, bullets, and brief paragraphs).
          - **START IMMEDIATELY WITH THE ANSWER.** Never begin with preamble like:
            - "Perfect!", "Great!", "Based on my research...", "I now have comprehensive information..."
            - "Let me provide...", "I can now provide...", "Here's what I found..."
            - Any meta-commentary about your search process or confidence level
          - Your first words should be the actual content (a heading, the direct answer, or the key fact).
          - If the required fact is missing from the latest **SEARCH_RESULTS**:
            - Partial or Related Information: Provide whatever relevant details you found, while clearly stating the limitations or gaps.
            - No Relevant Information: If nothing related was found, reply with: "I don't have specific information about [topic] in the available documents."
            - Maintain Engagement: Suggest related topics or alternative ways you can assist to keep the interaction productive.
          - DO NOT engage in character play. You must maintain a friendly, professional, and neutral tone at all times.
  ```
</Accordion>

## Learn More

* [Agent Composer Documentation](/quickstarts/agent-composer)
* [Agent Composer YAML Guide](/how-to-guides/agent-composer-yaml)


# Agent Composer Node Type Reference
Source: https://docs.contextual.ai/how-to-guides/ac-node-reference

A comprehensive guide for choosing the correct node type

<Note>
  Agent Composer is currently available in private preview for enterprise users. For more information or to request access, please contact your Contextual AI representative.
</Note>

## Overview

The first critical question is what type of workflow you need to build:

* **Static Workflow** - You know exactly what steps the agent should take and in what order. You can still include a conditional step where LLM is used as a judge for decision making, but the key property is that the control flow is predefined, not decided at runtime by an agent.
* **Dynamic Workflow** - The agent decides which actions to take based on the user query. You can provide instructions to the agent, add guardrails, but the flow is controlled by the agent.

***

## Static Workflow Agents

### Sequential Flow

The best representative example for this is the classic RAG pattern—you enter a query, search the datastore, then generate a response.

<img alt="Classic RAG" />

Crucially, only certain nodes can go together. For instance, you should not remove the `Reformulate Query Step` here because in `Response Generation Step`, you have 4 required input fields: `retrievals`, `query`, `translate_needed`, `detected_language`. Since your `Search Unstructured data` step only outputs retrievals, you need to supply the remaining input fields and ensure that the `Reformulate Query` step is just the right fit for this use case.

The easiest way to identify these pairs of nodes is to identify the required input fields and supply it with correct output values from other nodes.

<Note>If a node requires inputs that your current step does not produce, look for a node that naturally produces those fields instead of manufacturing them manually.</Note>

### Conditional Flow

You need different behaviors based on runtime conditions. Common use cases include:

* Quality thresholds (e.g., "if search quality \< 0.7, try web search")
* User type routing (e.g., "if admin user, use full pipeline; else use restricted pipeline")
* Fallback logic (e.g., "if no results from datastore, search web")

<img alt="Classic Rage" />

Here, you pair `Language Model Step` with `Conditional Step`. Although not strictly enforced, we generally recommend you use `Language Model Step` to allow an LLM to make a decision and output either a yes or no(or other set of values for conditional branching) which is then used for routing the request appropriately.

***

## Dynamic Workflow Agents

When you don’t know in advance whether the agent needs to search a datastore, make SQL queries to a structured datastore, make an API call, or perform multiple operations, use `Agentic Research Step` and provide it with a set of tools that the agent can access.

<img alt="Dynamic Workflow Agent" />

### Use Cases

* Complex queries requiring multiple lookups
* We need different behaviors based on runtime conditions.
* Workflows where the next step depends on previous results
* Agents that need to "think" and plan

You'll notice another additional node called `Create Message History Step`. You can see its use case, but crucially it generates `message history`, which is a required input in both the agentic research step and the generate from research step; subsequently, this step is required whenever you are building a dynamic agent workflow.

In general:<br />
**Input -> CreateMessageHistoryStep -> AgenticResearchStep -> Generate from Research Step -> Output**

***

## Choosing Nodes By Data Type

### Structured Data

If you're using the structured data ingested in your datastore, we recommend you start out with two tools: `get structured datastore schema` (for getting schema) + `query structure datastore step` (for making sql queries). You can then add tools like `MetadataSearchStep` to allow multi hop reasoning capabilities and so on.

### Unstructured Data (e.g., documents, PDFs)

We recommend you start with `Search Unstructured Data Step` and then refine/configure it by supplementing it with steps like `FilterRetrievalStep`, `RerankRetrievalStep`, and so on.

### External Data Sources

Use external data sources when your workflow needs to call third‑party APIs or services at runtime, or access data that is not stored in your Contextual datastores.

If you want to bring out your own data sources, use either of the steps: `WebhookStep` (for REST APIs) or `MCPClientStep` (MCP servers) to interact with external sources. This is where you need to use `data transformation` steps to properly format your request/response structure. For instance, you can use `JSONCreatorStep` to format JSON for an API.

### Data Processing/Transformation

Primitive nodes like `GetMemberStep`, `SetMemberStep`, `WrapStep`, `MergeStep` are all useful for transforming the data as per your use case

### Summary: What am I building?

**Simple Q\&A over documents**<br />
`ReformulateQueryStep → SearchUnstructuredDataStep → ResponseGenerationStep`

**Agent that decides what to do**<br />
`CreateMessageHistoryStep → AgenticResearchStep` (with tools)

**API integration**

* Simple call → `WebhookStep`
* MCP server → `MCPClientStep`

**Conditional logic needed**

* Simple if/else → `ConditionalStep`
* Complex logic → `AgenticResearchStep`

**Data transformation**
Primitive nodes (`GetMemberStep`, `JSONCreatorStep`, etc.)

**Multi-source search**

* Fixed sequence → Multiple `SearchStep`s in sequence
* Dynamic selection → `AgenticResearchStep` with search tools

## Reference Guide

| I need to…                     | Use this node                                        | Why / Notes                                                            |
| ------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------- |
| Search my datastore            | `SearchUnstructuredDataStep`                         | Built-in retrieval quality features                                    |
| Search the web                 | `WebSearchStep`                                      | Web-specific optimizations                                             |
| Generate a response            | `ResponseGenerationStep`, `GenerateFromResearchStep` | Includes attributions (use GenerateFromResearch with agentic research) |
| Call an API                    | `WebhookStep`                                        | Generic HTTP requests                                                  |
| Connect to MCP server          | `MCPClientStep`                                      | MCP protocol support                                                   |
| Create JSON dynamically        | `JSONCreatorStep`                                    | Variable substitution using `$` syntax                                 |
| Make a decision                | `ConditionalStep`, `AgenticResearchStep`             | Conditional for simple if/else, agent for complex logic                |
| Extract a field                | `GetMemberStep`                                      | No LLM required                                                        |
| Format data                    | `WrapStep, MergeStep`, `SetMemberStep`               | Primitive data transformations                                         |
| Use multiple tools dynamically | `AgenticResearchStep`                                | Lets the agent decide which tools to use                               |
| Run a custom LLM prompt        | `LanguageModelStep`                                  | Generic prompting                                                      |

## Additional Resources

* [Agent Composer Quickstart Guide](/quickstarts/agent-composer)
* [Agent Composer GUI How-to Guide](/how-to-guides/agent-composer-gui)


# Agent Composer YAML Cheat Sheet
Source: https://docs.contextual.ai/how-to-guides/ac-yaml-cheatsheet

A single-page reference for Agent Composer YAML

<Note>
  Custom Agent Composer YAML workflows are available in public preview for enterprise users. Template agents (Basic Search and Agentic Search) are available for self-serve users, but creating custom workflows with YAML requires enterprise access. For more information or to request access, please contact your Contextual AI representative.
</Note>

Agent Composer YAML defines **executable agent workflows** as graphs.\
Each graph specifies **inputs → nodes → outputs** and runs via `/query/acl`.

***

## Minimal Graph

```yaml theme={null}
inputs:
  query: str

outputs:
  response: str

nodes:
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query

  __outputs__:
    type: output
    input_mapping:
      response: generate#response
```

***

## Root-level Fields

| Field       | Required | Notes                                    |
| ----------- | -------- | ---------------------------------------- |
| `inputs`    | ✅        | Root graph accepts **only** `query: str` |
| `outputs`   | ✅        | Must be JSON-serializable                |
| `nodes`     | ✅        | Execution steps                          |
| `ui_output` | ⚠️       | Required if multiple outputs             |

***

## Core Rules (Remember These)

* Root graph: one input only (query)
* All node inputs must be wired
* Outputs must be JSON-serializable
* Multiple outputs → set exactly one ui\_output
* `__outputs__` node is mandatory

***

## Wiring Syntax

```yaml theme={null}
node_name#output_key
```

Special nodes:

* `__inputs__` → graph/subgraph inputs
* `__outputs__` → graph outputs

***

## Node Template

```yaml theme={null}
node_name:
  type: StepType
  config: {}
  config_overrides: {}
  input_mapping:
    input: upstream#output
```

Common fields:

* `type` (required)
* `input_mapping`
* `config` (static)
* `config_overrides` (runtime)
* `ui_stream_types`

***

## Output Node

```yaml theme={null}
__outputs__:
  type: output
  input_mapping:
    result: node#output
```

* No config
* No outputs
* Maps internal values → API outputs

***

## UI Streaming

```yaml theme={null}
ui_stream_types:
  retrievals: true
  generation: true
```

* Declared per node
* Multiple nodes may stream
* Independent of `ui_output`

***

## Subgraphs (Reusable Workflows)

Define:

```yaml theme={null}
my_subgraph:
  inputs:
    query: str
  outputs:
    docs: List[str]
  nodes: ...
```

Use:

```yaml theme={null}
retriever:
  type: subgraph:my_subgraph
  input_mapping:
    query: __inputs__#query
```

* Nestable
* Reusable
* Isolated I/O scope

***

## Conditional Execution

```yaml theme={null}
conditional:
  type: ConditionalStep
  config:
    variable: score
    branches:
      - condition: ">= 0.8"
        executable: HighQuality
      - condition: "< 0.8"
        executable: LowQuality
  input_mapping:
    score: eval#score
```

* Top-down evaluation
* First match executes
* Branch `__inputs__` != graph inputs

***

## Agentic Research Pattern

Standard flow:

1. `CreateMessageHistoryStep`
2. `AgenticResearchStep`
3. `GenerateFromResearchStep`

### Message History

```yaml theme={null}
create_message_history:
  type: CreateMessageHistoryStep
  input_mapping:
    query: __inputs__#query
```

### Agentic Research

```yaml theme={null}
research:
  type: AgenticResearchStep
  ui_stream_types:
    retrievals: true
```

* Multi-turn agent loop
* Plans and invokes tools
* Produces structured research

### Tools

```yaml theme={null}
tools_config:
  - name: search_docs
    step_config:
      type: SearchUnstructuredDataStep
```

Rules:

* Use either step\_config or graph\_config
* Inputs = basic Python types

### Final Generation

```yaml theme={null}
generate:
  type: GenerateFromResearchStep
  ui_stream_types:
    generation: true
```

Consumes `message_history` and `research` as inputs

***

## Run a Graph (Python)

```python theme={null}
graph = ExecutableGraph.from_yaml(yaml_string)
graph.execute_graph({"query": "Hello"})
```

## API Response

* `outputs`
* `workflow_trace`
* `dynamic_agent_trace` (if agentic steps used)

***

## Common Errors

| Error                   | Fix                    |
| ----------------------- | ---------------------- |
| Missing node input      | Wire it                |
| No `__outputs__`        | Add output node        |
| Multiple outputs        | Set `ui_output`        |
| Non-serializable output | Convert to basic types |


# Agent Composer YAML Step Reference
Source: https://docs.contextual.ai/how-to-guides/ac-yaml-reference

An authoritative list of all the Agent Composer step types

<Note>
  Custom Agent Composer YAML workflows are available in public preview for enterprise users. Template agents (Basic Search and Agentic Search) are available for self-serve users, but creating custom workflows with YAML requires enterprise access. For more information or to request access, please contact your Contextual AI representative.
</Note>

## Overview

This catalog lists step types available for use in Agent Composer YAML graphs, including their configuration parameters, required inputs, outputs, and supported UI stream types.

***

### AgenticResearchStep

* **Description:** Runs a multi-turn agent loop that plans and invokes tools to gather information and produce structured research output.
* **Config Parameters:**
  * `agent_config: Dict[str, Any] = required`
  * `tools_config: Optional[List[Dict[str, Any]]] = None`
  * `version: str = "0.1"`
* **Inputs:** `message_history: List[MessageAndRole]`
* **Outputs:** *(varies by implementation; commonly includes structured research output consumed by generation steps)*
* **UI Stream Types:** `RETRIEVALS`

> Tip: For final response synthesis, pair `AgenticResearchStep` with `GenerateFromResearchStep`.

***

### AppendStep

* **Description:** Appends a given item to a list and returns the new list.
* **Config:** None
* **Inputs:** `list: List[Any]`, `element: Any`
* **Outputs:** `output: List[Any]`
* **UI Stream Types:** None

***

### AttributionStep

* **Description:** Step to handle attributions.
* **Config Parameters:**
  * `attribution: Optional[bool] = None`
  * `template_attribution: Optional[str] = None`
  * `attribution_model: Optional[str] = None`
  * `number_of_retrievals_for_attribution: Optional[int] = None`
* **Inputs:** `generation_result: GenerationResult`, `chunks_info: List[Dict]`
* **Outputs:** `attribution_result: AttributionResult`
* **UI Stream Types:** `ATTRIBUTION`

***

### BuildPromptStep

* **Description:** Step to build the final prompt.
* **Config Parameters:**
  * `untrusted_system_prompt: Optional[str] = None`
  * `untrusted_no_retrieval_system_prompt: Optional[str] = None`
  * `template_seed: Optional[str] = None`
  * `template_query: Optional[str] = None`
  * `template_knowledge: Optional[str] = None`
  * `max_new_tokens: Optional[int] = None`
  * `skip_context_truncation: Optional[bool] = None`
  * `allow_multi_turn: Optional[bool] = None`
  * `avoid_commentary: Optional[bool] = None`
  * `attribution: Optional[bool] = None`
* **Inputs:** `query: str`, `retrievals: Retrievals`, `retrieval_record: Retrieval`, `message_history: List[MessageAndRole]`, `chunks_info: List[Dict]`
* **Outputs:** `retrieval_record: Retrieval`, `message_history: List[MessageAndRole]`, `chunks_info": List[Dict]`
* **UI Stream Types:** `RETRIEVALS`

***

### CheckRetrievalNeedStep

* **Description:** Step to check if retrieval is needed for the given query.
* **Config Parameters:**
  * `should_check_retrieval_need: Optional[bool] = None`
  * `template_should_retrieve: Optional[str] = None`
* **Inputs:** `query: str`
* **Outputs:** `is_retrieval_needed: bool`, `retrievals: Retrievals`
* **UI Stream Types:** None

***

### ConcatenateStep

* **Description:** Concatenates two lists.
* **Config:** None
* **Inputs:** `list1: List[Any]`, `list2: List[Any]`
* **Outputs:** `output: List[Any]`
* **UI Stream Types:** None

***

### ContextualAgentStep

* **Description:** Step to retrieve information from contextual agents.
* **Config Parameters:** `agent_ids: Optional[List[str]] = None`
* **Inputs:** `query: str`
* **Outputs:** `retrievals: Retrievals`
* **UI Stream Types:** `RETRIEVALS`

***

### ConstantStep

* **Description:** Provides constant values as outputs.
* **Config Parameters:** `value: Any = required`
* **Inputs:** None
* **Outputs:** `output: Any`
* **UI Stream Types:** None

***

### ContextualizeChunk

* **Description:** Contextualize chunk text with surrounding document context using VLM.
* **Config Parameters:**
  * `shard_tokens: int = 20000`
  * `shard_overlap: int = 10000`
* **Inputs:** `chunk: Dict[str, Any]`, `tenant_id: str`, `document_id: str`
* **Outputs:** `chunk: Dict[str, Any]`
* **UI Stream Types:** None

***

### CreateMessageHistoryStep

* **Description:** Converts a query into a message history.
* **Config Parameters:**
  * `enable_model_armor: Optional[bool] = None`
  * `should_check_retrieval_need: Optional[bool] = None`
  * `template_should_retrieve: Optional[str] = None`
  * `untrusted_system_prompt: Optional[str] = None`
  * `untrusted_no_retrieval_system_prompt: Optional[str] = None`
  * `template_seed: Optional[str] = None`
  * `template_query: Optional[str] = None`
  * `template_knowledge: Optional[str] = None`
  * `max_new_tokens: Optional[int] = None`
  * `skip_context_truncation: Optional[bool] = None`
  * `allow_multi_turn: Optional[bool] = None`
  * `avoid_commentary: Optional[bool] = None`
  * `attribution: Optional[bool] = None`
* **Inputs:** `query: str`
* **Outputs:** `message_history: List[MessageAndRole]`
* **UI Stream Types:** `RETRIEVALS: False`

***

### DeleteMemberStep

* **Description:** Deletes the specified key from a dict or a pydantic model.
* **Config Parameters:** `allow_missing_key: bool = False`
* **Inputs:** `input: Union[dict, BaseModel]`, `key: str`
* **Outputs:** `output: Union[dict, BaseModel]`
* **UI Stream Types:** None

***

### DocumentDownloadStep

* **Description:** Downloads documents from ingestion storage using DownloadDocumentTool.
* **Config:** None
* **Inputs:** `tenant: dict`, `datastore_id: UUID`, `short_path: str`
* **Outputs:** `content: str`, `file_name: str`, `document_id: str`, `full_gcs_path: str`, `content_type: str`, `size_bytes: int`
* **UI Stream Types:** None

***

### EntitleRetrievalsStep

* **Description:** Post-process retrievals.
* **Config:** None
* **Inputs:** `retrievals: Retrievals`
* **Outputs:** `retrievals: Retrievals`, `entitlements_api_time_elapsed: float`
* **UI Stream Types:** None

***

### ExtractChunkMetadata

* **Description:** Extract key-value metadata from chunk text using VLM.
* **Config:** None
* **Inputs:** `chunk: Dict[str, Any]`, `prompt: str`, `vlm_model: str`
* **Outputs:** `metadata: Dict[str, Any]`, `chunk: Dict[str, Any]`
* **UI Stream Types:** None

***

### ExtractMetadataStep

* **Description:** Extract metadata from PDF using ExtractMetadataTool.
* **Config:** None
* **Inputs:** `content: str`, `full_gcs_path: str`, `user_id: UUID`, `file_name: str`
* **Outputs:** `shard_metadata_list: List[ShardMetadata]`
* **UI Stream Types:** None

***

### FileAnalysisInputStep

* **Description:** Analyze files uploaded at query time.
* **Config:** None
* **Inputs:** `query: str`
* **Outputs:** `retrievals: Retrievals`
* **UI Stream Types:** `RETRIEVALS`

***

### FilterRetrievalsStep

* **Description:** Filter retrievals.
* **Config Parameters:**
  * `template_filter: Optional[str] = None`
  * `filter_retrievals: Optional[bool] = None`
  * `filter_model: Optional[str] = None`
  * `structured_output: Optional[bool] = None`
  * `untrusted_filter_prompt: Optional[str] = None`
  * `enable_batch_processing: Optional[bool] = None`
* **Inputs:** `query: str`, `retrievals: Retrievals`
* **Outputs:** `retrievals: Retrievals`
* **UI Stream Types:** None

***

### GenerateEmbeddingsStep

* **Description:** Generate embeddings for the query.
* **Config Parameters:**
  * `max_encoder_length: Optional[int] = None`
  * `retrieval_encoder_model: Optional[str] = None`
* **Inputs:** `query: str`, `reformulated_query: str`, `expanded_queries: List[str]`
* **Outputs:** `query_embedding: List[float]`, `merged_embeded_reformulated_queries: List[Tuple[List[float], str]]`
* **UI Stream Types:** None

***

### GenerateFromResearchStep

* **Description:** Generate a response.
* **Config Parameters:**
  * `model_name_or_path: str`
  * `base_url: Optional[str] = None`
  * `identity_guidelines_prompt: str = "You are a helpful assistant made by Contextual AI."`
  * `response_guidelines_prompt: str = "You should respond in a friendly and helpful manner."`
  * `litellm_modify_params: bool | Literal["auto"] = "auto"`
  * `version="0.1"`
* **Inputs:** `message_history: List[MessageAndRole]`, `research: List`
* **Outputs:** `response: str`

***

### GenerationStep

* **Description:** Generate a response.
* **Config Parameters:**
  * `temperature: Optional[float] = None`
  * `max_new_tokens: Optional[int] = None`
  * `top_p: Optional[float] = None`
  * `frequency_penalty: Optional[float] = None`
  * `seed: Optional[int] = None`
  * `attribution: Optional[bool] = None`
* **Inputs:** `message_history: List[MessageAndRole]`, `chunks_info: List[Dict]`, `disable_streaming: bool`
* **Outputs:** `generation_result: GenerationResult`
* **UI Stream Types:** `GENERATION`

***

### GetAgentInfoStep

* **Description:** Answers questions about the agent itself.
* **Config:** None
* **Inputs:** `query: str`
* **Outputs:** `generation_result: GenerationResult`
* **UI Stream Types:** None

***

### GetDatastoreStatisticsStep

* **Description:** Handle datastore statistics (as provided).
* **Config:** None
* **Inputs:** `query: str`
* **Outputs:** `generation_result: GenerationResult`
* **UI Stream Types:** None

***

### GetDatastoreSummaryStep

* **Description:** Aggregates results to generate a datastore summary.
* **Config:** None
* **Inputs:** `datastore_statistics: GenerationResult`, `documents_summary: GenerationResult`, `query: str`
* **Outputs:** `generation_result: GenerationResult`
* **UI Stream Types:** None

***

### GetDocumentsSummaryStep

* **Description:** Generates a summary of documents in the datastore.
* **Config:** None
* **Inputs:** `query: str`
* **Outputs:** `generation_result: GenerationResult`
* **UI Stream Types:** None

***

### GetMemberStep

* **Description:** Extract values from dictionaries or object attributes.
* **Config Parameters:** `key: str = required`
* **Inputs:** `input: Union[dict, BaseModel]`
* **Outputs:** `output: Any`
* **UI Stream Types:** None

***

### GetPlatformInfoStep

* **Description:** Answers questions about the platform itself.
* **Config:** None
* **Inputs:** `query: str`
* **Outputs:** `generation_result: GenerationResult`
* **UI Stream Types:** None

***

### GroundednessStep

* **Description:** Compute groundedness scores.
* **Config Parameters:**
  * `attribution: Optional[bool] = None`
  * `calculate_groundedness: Optional[bool] = None`
* **Inputs:** `generation_result: GenerationResult`, `attribution_result: AttributionResult`, `chunks_info: List[Dict]`
* **Outputs:** `groundedness_scores: List[GroundednessScore]`
* **UI Stream Types:** `GROUNDEDNESS`

***

### IndexChunkMetadata

* **Description:** Index chunk with metadata in ElasticSearch.
* **Config:** None
* **Inputs:** `chunk: Dict[str, Any]`, `metadata: Dict[str, Any]`, `index_config: Dict[str, str]`, `tenant_id: str`, `document_id: str`
* **Outputs:** `indexed: bool`, `chunk_id: str`
* **UI Stream Types:** None

***

### IndexMetadataStep

* **Description:** Index metadata into Elasticsearch using IndexMetadataTool.
* **Config:** None
* **Inputs:** `shard_metadata_list: List[ShardMetadata]`, `tenant: dict`, `datastore_id: UUID`
* **Outputs:** `doc_id_list: List[str]`
* **UI Stream Types:** None

***

### IndexStep

* **Description:** Return the element at a given index of a list.
* **Config:** None
* **Inputs:** `list: List[Any]`, `index: int`
* **Outputs:** `output: Any`
* **UI Stream Types:** None

***

### IsFirstTurnStep

* **Description:** Returns whether this is the first turn in a multi-turn interaction.
* **Config:** None
* **Inputs:** None
* **Outputs:** `is_first_turn: bool`, `turn_count: int`
* **UI Stream Types:** None

***

### JSONCreatorStep

* **Description:** Creates JSON objects with dynamic variable substitution using `$`.
* **Config Parameters:** `schema: str = required`
* **Inputs:** Dynamic (based on `$variables` in schema)
* **Outputs:** `json: Dict[str, Any]`
* **UI Stream Types:** None

***

### LanguageModelStep

* **Description:** Generic language model inference with template variables.
* **Config Parameters:**
  * `prompt_template: str = required`
  * `model_id: str = required`
  * `temperature: float = 0.7`
  * `max_tokens: int = 1000`
  * `structured_output: Optional[Dict] = None`
* **Inputs:** Dynamic (template variables)
* **Outputs:** `response: str`
* **UI Stream Types:** None

***

### LengthStep

* **Description:** Return the length of a list.
* **Config:** None
* **Inputs:** `list: List[Any]`
* **Outputs:** `output: int`
* **UI Stream Types:** None

***

### MCPClientStep

* **Description:** Execute tools on Model Context Protocol servers.
* **Config Parameters:**
  * `server_url: str = required`
  * `tool_name: str = required`
  * `tool_args: str = required`
  * `transport_type: str = "http"`
  * `connection_timeout: int = 30`
  * `server_name: Optional[str] = None`
  * `auth_headers: Optional[Dict[str, str]] = None`
* **Inputs:** Dynamic (based on `tool_args`)
* **Outputs:** `mcp_result: Dict[str, Any]`
* **UI Stream Types:** None

***

### MergeStep

* **Description:** Merge two dicts (or pydantic models).
* **Config Parameters:** `allow_key_conflicts: bool = False`
* **Inputs:** `dict1: Union[dict, BaseModel]`, `dict2: Union[dict, BaseModel]`
* **Outputs:** `output: Union[dict, BaseModel]`
* **UI Stream Types:** None

***

### ModelArmorFilterUserPromptStep

* **Description:** Send user prompt to model armor for safety check.
* **Config Parameters:** `enable_model_armor: Optional[bool] = None`
* **Inputs:** `query: str`
* **Outputs:** None
* **UI Stream Types:** None

***

### ProcessMetadataStep

* **Description:** Process metadata for retrievals.
* **Config:** None
* **Inputs:** `retrievals: Retrievals`
* **Outputs:** `retrievals: Retrievals`
* **UI Stream Types:** None

***

### QueryDecompositionStep

* **Description:** Decompose the query.
* **Config Parameters:**
  * `query_decomposition_prompt: Optional[str] = None`
  * `query_decomposition_model: Optional[str] = None`
  * `enable_query_decomposition: Optional[bool] = None`
* **Inputs:** `query: str`
* **Outputs:** `expanded_queries: List[str]`
* **UI Stream Types:** None

***

### QueryExpansionStep

* **Description:** Expand the query.
* **Config Parameters:**
  * `query_expansion_prompt: Optional[str] = None`
  * `query_expansion_model: Optional[str] = None`
  * `enable_query_expansion: Optional[bool] = None`
* **Inputs:** `query: str`
* **Outputs:** `reformulated_query: str`, `documents_filters: Optional[Union[CompositeMetadataFilter, BaseMetadataFilter]]`
* **UI Stream Types:** `QUERY_REFORMULATION`

***

### QueryMultiturnStep

* **Description:** Handle query multiturn.
* **Config Parameters:**
  * `query_multiturn_model: Optional[str] = None`
  * `allow_multi_turn: Optional[bool] = None`
  * `untrusted_multiturn_system_prompt: Optional[str] = None`
  * `template_query_multiturn: Optional[str] = None`
* **Inputs:** `query: str`
* **Outputs:** `reformulated_query: str`
* **UI Stream Types:** `QUERY_REFORMULATION`

***

### QueryRegexStrippingStep

* **Description:** Strip the query.
* **Config Parameters:** `query_regex_stripping: Optional[List[str]] = None`
* **Inputs:** `query: str`
* **Outputs:** `reformulated_query: str`
* **UI Stream Types:** None

***

### ReformulateQueryStep

* **Description:** Reformulate a query for datastore search.
* **Config Parameters:** None
* **Inputs:** `query: str`
* **Outputs:** `reformulated_query: str`, `translate_needed: bool`, `detected_language: str`
* **UI Stream Types:** `QUERY_REFORMULATION`

***

### RerankRetrievalsStep

* **Description:** Rerank retrievals.
* **Config Parameters:** `rerank_top_k: Optional[int] = None`, `reranker: Optional[str] = None`, `rerank_retrievals: Optional[bool] = None`, `rerank_instructions: Optional[str] = None`, `reranker_score_filter_threshold: Optional[float] = None`, `rerank_with_llm: Optional[bool] = None`, `template_rerank: Optional[str] = None`, `structured_output: Optional[bool] = None`,
* **Inputs:** `query: str`, `retrievals: Retrievals`
* **Outputs:** `retrievals: Retrievals`
* **UI Stream Types:** None

***

### ResponseGenerationStep

* **Description:** Generate a response based on query + retrievals.
* **Config Parameters:** None
* **Inputs:** `retrievals: Retrievals`, `query: str`, `translate_needed: bool`, `detected_language: str`
* **Outputs:** `response: str`, `attribution_result: AttributionResult`, `groundedness_scores: List[GroundednessScore]`
* **UI Stream Types:** `RETRIEVALS`, `GENERATION`, `ATTRIBUTION`, `GROUNDEDNESS`

***

### SalesforceSOSLStep

* **Description:** Execute SOSL searches against Salesforce.
* **Config Parameters:** `username: Optional[str] = None`, `password: Optional[SecretStr] = None`, `security_token: Optional[SecretStr] = None`, `client_id: Optional[str] = None`, `client_secret: Optional[SecretStr] = None`, `login_url: Optional[str] = None`, `auth_token_secret: Optional[SecretStr] = None`, `objects_to_return: str = "Case(Id, Subject, Status, Priority, Account.Name, Contact.Name)"`, `limit: int = 250`, `timeout: int = 30`
* **Inputs:** `query: str`
* **Outputs:** `search_results: str`
* **UI Stream Types:** None

***

### SearchShardMetadataStep

* **Description:** Search document shard metadata using instant search.
* **Config Parameters:** `default_size: int = 10`
* **Inputs:** `query: str`
* **Outputs:** `shard_search_results: List[Dict[str, Any]]`
* **UI Stream Types:** None

***

### SearchStep

* **Description:** Perform search using the search service.
* **Config Parameters:** `datastores: Optional[List[UUID]] = None`, `disable_structured_data_search: bool = False`
* **Inputs:** `query: str`, `query_embedding: List[float]`, `merged_embeded_reformulated_queries: List[Tuple[List[float], str]]`, `documents_filters: Optional[...]`
* **Outputs:** `retrievals: Retrievals`
* **UI Stream Types:** None

***

### SearchStructuredDataStep

* **Description:** Search structured data.
* **Config Parameters:** `datastores: Optional[List[UUID]] = None`
* **Inputs:** `query: str`
* **Outputs:** `retrievals: Retrievals`
* **UI Stream Types:** None

***

### SearchUnstructuredDataStep

* **Description:** Search unstructured data and return retrievals.
* **Config Parameters:** None
* **Inputs:** `query: str`
* **Outputs:** `retrievals: Retrievals`
* **UI Stream Types:** `QUERY_REFORMULATION`

***

### SetMemberStep

* **Description:** Update values of dictionaries or pydantic objects.
* **Config Parameters:** `overwrite: bool = False`
* **Inputs:** `input: Union[dict, BaseModel]`, `key: str`, `value: Any`
* **Outputs:** `output: Union[dict, BaseModel]`
* **UI Stream Types:** None

***

### ShardImageExtractionStep

* **Description:** Extract page images from PDF shard search results.
* **Config Parameters:** `default_dpi: int = 144`
* **Inputs:** `shard_search_results: List[Dict[str, Any]]`
* **Outputs:** `extracted_images: List[str]`
* **UI Stream Types:** None

***

### SliceStep

* **Description:** Slice a list from `start_index` to `end_index`.
* **Config:** None
* **Inputs:** `list: List[Any]`, `start_index: int`, `end_index: int`
* **Outputs:** `output: List[Any]`
* **UI Stream Types:** None

***

### TranslateQueryStep

* **Description:** Translate the query.
* **Config Parameters:** `translate_confidence: Optional[float] = None`, `template_translation_forward: Optional[str] = None`, `template_translation_reverse: Optional[str] = None`, `translate_model: Optional[str] = None`, `translate_needed: Optional[bool] = None`
* **Inputs:** `query: str`
* **Outputs:** `reformulated_query: str`, `translate_needed: bool`, `detected_language: str`
* **UI Stream Types:** None

***

### TranslateResponseStep

* **Description:** Translate the response.
* **Config Parameters:** `template_translation_forward: Optional[str] = None`, `template_translation_reverse: Optional[str] = None`, `translate_model: Optional[str] = None`
* **Inputs:** `generation_result: GenerationResult`, `translate_needed: bool`, `detected_language: str`
* **Outputs:** `generation_result: GenerationResult`
* **UI Stream Types:** `GENERATION`

***

### VisionLanguageModelStep

* **Description:** Vision language model inference with multimodal inputs.
* **Config Parameters:** `model_id: str = "vertex_ai/gemini-2.0-flash"`, `temperature: float = 0.0`, `max_tokens: int = 4096`, `structured_output: Optional[Dict[str, Any]] = None`
* **Inputs:** `query: str`, `images: List[str]`
* **Outputs:** `generation_result: GenerationResult`
* **UI Stream Types:** `GENERATION`

***

### WebSearchStep

* **Description:** Perform web search.
* **Config Parameters:** `model: str = "gemini-2.5-flash"`
* **Inputs:** `query: str`
* **Outputs:** `web_result: WebResult`
* **UI Stream Types:** None

***

### WebhookStep

* **Description:** Execute a webhook call with static and dynamic configuration.
* \*\*Config Parameters: `webhook_url: str`, `method: HttpMethod = HttpMethod.POST`, `auth_token: Optional[SecretStr] = None`, `timeout: int = 30`, `retries: int = 2`, `static_headers: Optional[Dict[str, str]] = None`, `webhook_name: str = "webhook-step"`
* **Inputs:** `context_data: Dict[str, Any]`
* **Outputs:** `webhook_result: Optional[Dict[str, Any]]`
* **UI Stream Types:** None

***

### WrapStep

* **Description:** Transform data by wrapping inputs in dictionaries.
* **Config Parameters:** `key: str = required`
* **Inputs:** `input: Any`
* **Outputs:** `output: Dict[str, Any]`
* **UI Stream Types:** None

## Additional Resources

* [Agent Composer Quickstart Guide](/quickstarts/agent-composer)
* [Agent Composer GUI How-to Guide](/how-to-guides/agent-composer-gui)


# Agent Composer GUI
Source: https://docs.contextual.ai/how-to-guides/agent-composer-gui

Using the Agent Composer GUI to visually build workflows

<Note>
  The Agent Composer GUI is available in public preview. Template agents (Basic Search and Agentic Search) are available for self-serve users, but using the visual workflow builder for custom workflows requires enterprise access. For more information or to request access, please contact your Contextual AI representative.
</Note>

## Overview

The Agent Composer GUI provides a visual way to build agent workflows in Contextual AI, replacing manual YAML with an intuitive, drag-and-drop canvas.

<img alt="" />

| Component          | Description                               | Function                    |
| ------------------ | ----------------------------------------- | --------------------------- |
| Agent Composer GUI | Visual builder for agent workflows        | Replaces hand-written YAML  |
| Canvas             | Area where nodes are placed and connected | Supports drag, drop, select |
| Node Drawer        | Right-side panel for adding nodes         | Drag onto canvas            |

Together, these components ensure workflows are type-safe, executable, and quick to move from concept to a working agent.

***

## Building an Agent Workflow

To create an agent workflow, open the Workflow Builder and add nodes from the drawer to define each step of the process. As the workflow grows, group related nodes into subgraphs to keep the graph organized and reusable, then connect nodes with type-safe connections to define how data flows between components.

<img alt="" />

When the workflow is complete, save your progress, optionally export the graph as YAML, and create or update an agent. This allows you to iterate and refine the workflow over time.

***

## Nodes

Agent Composer workflows are built from a set of node types, each designed to serve a specific role within an agent’s execution graph. Some nodes perform straightforward processing, while others introduce configuration, branching logic, or dynamic behavior at runtime.

### Adding Nodes

Nodes can be added from the right-side drawer by dragging and dropping them onto the canvas.

### Removing Nodes

Remove a node by clicking to select it, then either press `BACKSPACE` or click the trash bin icon in the node's toolbar.

<video />

### Duplicating Nodes

Any node can be duplicated for reusability. This will include configuration, connections.

* **Single node:** Select the node and click the **Duplicate** button in the top-left corner of the canvas.
* **Multiple nodes:** Hold `SHIFT`, click and drag on the canvas to create a selection box around the nodes you want to duplicate, then click the **Duplicate** button.

<video />

***

## Node Types

By understanding the different node types, you can assemble workflows more intentionally, reuse logic where it makes sense, and build agentic systems that remain flexible and easy to maintain over time.

| Node Type               | Description                                                                 | Configuration        | Dynamic Connections | Special Behavior                                          |
| ----------------------- | --------------------------------------------------------------------------- | -------------------- | ------------------- | --------------------------------------------------------- |
| Standard Node           | Basic workflow node                                                         | Optional             | ❌                   | Fixed inputs and outputs                                  |
| Configurable Node       | Node with required or optional settings                                     | Required or optional | ❌                   | Shows validation warnings                                 |
| Dynamic Connection Node | Node with user-defined inputs and outputs                                   | Optional             | ✅                   | Inputs and outputs are editable                           |
| Conditional Node        | Branching logic node                                                        | Optional             | ❌                   | Executes subgraphs based on evaluated conditions          |
| Agentic Research Node   | Executes an internal agent loop with tool access for planning and retrieval | Required             | ✅ (tools)           | Plans and invokes tools to gather information iteratively |
| Subgraph                | Grouped nodes representing reusable workflows                               | Optional             | Depends             | Reusable and can be embedded or exposed as a tool         |

### Nodes with Dynamic Connections

Some nodes allow their connections to be dynamically configured by the user. These nodes are marked with a **Wire Icon**. Depending on the node type, you can add/remove/edit:

* **Inputs** (left handle)
* **Outputs** (right handle)
* **Tools** (top handle for nodes / bottom handle for DynamicAgent)
* **Configuration Overrides** (left handle with diamond icon)

Each input and output must include a **key** and a **type**. The type determines which connections can be attached—connections are only valid if their types match.

<video />

### Configurable Nodes

Some nodes require configuration, indicated by a **Sliders Icon**. Nodes with required configuration fields will display an orange message. Other nodes may have optional configuration available. Clicking the **Sliders Icon** in the node’s toolbar will open a dialog to fill out the configuration form.

<video />

### Special Nodes

#### Conditional Nodes

Conditional nodes allow you to execute different subgraphs based on runtime conditions.

<video />

#### Agentic Research Nodes

Agentic Research nodes execute a structured agent loop that plans, retrieves information using explicitly defined tools, and iteratively gathers the context needed to answer a query.

<video />

***

## Grouping Nodes with Subgraphs

Subgraphs allow you to group multiple nodes into a single, reusable unit within a workflow. By encapsulating related logic behind a named boundary, subgraphs make complex workflows easier to understand, maintain, and reuse.

A subgraph can be configured with its own name and key, resized or ungrouped as needed, and even attached as a tool to a DynamicAgent node, enabling modular and composable agent designs.

### Creating a Subgraph

Multiple nodes can be grouped into a subgraph:

1. Hold `SHIFT`, click and drag to create a selection box around the nodes you want to group
2. Click the "Group" button in the top-left corner of the canvas
3. The subgraph can be resized by clicking and dragging its edges or corners
4. A subgraph can be ungrouped by selecting the blue box of the group, and clicking “Ungroup” from the node toolbar

### Configuring a Subgraph

To give your subgraph a custom name and key:

1. Select the blue box of the group
2. Click the **Gear Icon** (Configure)
3. Enter a name and key for the subgraph
4. Click **Submit**

<video />

***

## Connections

Connections define how data and behavior flow through an Agent Composer workflow. They determine how outputs from one node are passed to inputs on another, how configuration is overridden at runtime, and how tools are exposed to dynamic agents.

| Connection Type        | Where Used    | Description                         |
| ---------------------- | ------------- | ----------------------------------- |
| Input / Output         | All nodes     | Type-checked data flow              |
| Tool Connection        | DynamicAgent  | Attaches node or subgraph as a tool |
| Configuration Override | Dynamic nodes | Overrides runtime configuration     |

Because connections are type-checked and validated by the builder, they help ensure workflows are both correct at design time and reliable during execution.

### Adding Connections

Nodes can be connected via their connection handles. Connections must have matching types to successfully connect. To check a connection's type, simply hover over the handle to see its tooltip.

### Removing Connections

Remove a connection by clicking to select its edge (connection line), then press `BACKSPACE`.

### Tool Connections

Tools can be attached to an Agentic Research node to give the agent access to retrieval, processing, or other capabilities during its research loop.

1. Select your **Agentic Research** node and click the **Tool** icon labeled **Tools**.
2. Choose either an individual node or an existing subgraph from the list of available options.
3. Click **Done** to confirm the selection.
4. Provide a key name for the tool connection, which becomes the identifier the agent uses when invoking the tool.
5. The selected node or subgraph is automatically created (if needed) and connected to the Agentic Research node.

***

## Importing

Full YAML graphs can be imported into the builder. The provided YAML string will be converted into visual nodes and connections that you can edit in the interface.

<video />

## Exporting

Once you've built your graph, you can export it as a YAML file. This converts the visual graph into a YAML string that can be copied or downloaded.

***

## Saving Progress

Click the **Save** button in the top-right bar above the canvas to save your current progress. This preserves:

* Node positions
* Connections (edges)
* Viewport state

Your progress is saved to browser storage, so you can safely refresh the page or navigate away without losing your work.

<video />

***

## Creating an Agent

Once your graph is complete:

1. Click **Save & Continue** to save your progress and proceed to the Agent Creation flow
2. Enter an agent name and attach a datastore
3. Navigate to the **Advanced Context** section to review your generated YAML
4. Click **Create** to finalize your agent

<video />

## Editing an Agent

Once in chat you should also be able to go back to the builder view by clicking **Edit in Workflow Builder** from the agent’s action menu. Or when editing an agent, click **Edit in Builder** from the **Advanced Context** section.

<img alt="" />

## Additional Resources

* [Agent Composer Quickstart Guide](/quickstarts/agent-composer)
* [Agent Composer YAML How-to Guide](/how-to-guides/agent-composer-yaml)


# Agent Composer Templates
Source: https://docs.contextual.ai/how-to-guides/agent-composer-templates

Agent Composer templates: Basic Search, Agentic Search, and Enterprise templates like Device Log Analysis

## Overview

Agent Composer offers pre-built **templates** so you can get started quickly. Availability is by template type:

* **Basic Search** and **Agentic Search** — available to **self-serve** users.
* **All other templates** in the [Template Catalog](/examples/templates-catalog) (e.g. Device Log Analysis, Deep Research, domain-specific templates) are available only for **Enterprise**. There are no other Enterprise-only features—only access to these additional templates. [Request a demo](https://contextual.ai/request-a-demo) to use them.

| Template                | Availability | Best for                                                                                          |
| ----------------------- | ------------ | ------------------------------------------------------------------------------------------------- |
| **Basic Search**        | Self-serve   | Quick lookups, simple Q\&A, direct search-to-response                                             |
| **Agentic Search**      | Self-serve   | Multi-step retrieval, iterative research, complex Q\&A                                            |
| **Device Log Analysis** | Enterprise   | Automated root cause analysis of device logs (e.g. 3GPP LTE), multi-agent parsing and RCA reports |

***

## Basic Search

**Basic Search** (also referred to as Fast Search in the template catalog) is a streamlined, lightweight template for quick document retrieval and response generation.

* **Simple architecture:** Direct search-to-response pipeline without multi-turn research
* **Fast performance:** Minimal configuration for rapid queries
* **Basic RAG:** Standard retrieval with citation and groundedness tracking

**Use cases:** Quick lookups, simple Q\&A, straightforward document search.

For more templates in this style (e.g. Fast Search YAML), see the [Template Catalog](/examples/templates-catalog#enterprise-&-legal).

***

## Agentic Search

**Agentic Search** is a multi-step research template. The agent uses iterative retrieval and tool use to answer complex questions with citations.

* **Multi-turn research:** Plans searches, refines queries, and synthesizes answers from multiple retrievals
* **Structured agent loop:** Uses defined tools (e.g. search over datastores) with guardrails
* **Citations:** Grounded responses with source references

**Use cases:** Technical documentation Q\&A, research over internal docs, customer support with deep lookup.

**Try the demos:** All of these agents use the Agentic Search template (or the same multi-step research pattern). Launch the live demo or read the example page.

* [Rocket Science](/examples/rocket_science) — [Launch](https://demo.contextual.ai/propulsion-agent): Root cause analysis for rocket engine anomalies
* [Raspberry Pi Agent](/examples/raspberry-pi-agent) — [Launch](https://demo.contextual.ai/customer-engineering): Technical support for Raspberry Pi hardware
* [Material Science Agent](/examples/material-science-agent) — [Launch](https://demo.contextual.ai/material-science): Research assistant over materials papers (ELI5 style)
* [Test Program Generation](/examples/test-automation) — [Launch](https://demo.contextual.ai/test-code-generation): Generate OpenTAP test programs and drivers
* [3GPP Spec Explorer](/examples/3gpp-spec-explorer) — [Launch](https://demo.contextual.ai/3gpp-agentic-search): Search and reason over 3GPP specifications (Release 19 and others)

**Guides:** [Template Catalog](/examples/templates-catalog) for related templates.

***

## Device Log Analysis (Enterprise)

The **Device Log Analysis** template is available in Agent Composer for Enterprise customers. It automates root cause analysis (RCA) on device failure logs (e.g. 3GPP LTE eNB/UE logs) by parsing logs, building searchable databases, and running multi-agent analysis to produce timelines, visuals, and detailed RCA reports.

[Example page](/examples/device-log-analysis) · [Launch demo](https://demo.contextual.ai/log-analysis)

**In production:** You upload a log file and optionally a debug reference guide, then ask a query (e.g. *"Why did the call drop?"*). The rest is automatic: the system parses logs, builds databases, runs root cause analysis, can generate Python scripts that run in a secure VM, and produces visuals and a detailed RCA report. This is a longer-running, multi-agent workflow aimed at complex, routine knowledge work.

**Next steps:** [Request a demo](https://contextual.ai/request-a-demo) to get access.

**Docs and demo:** The [example page](/examples/device-log-analysis) has the full description, example outputs (causation timelines, system health visuals), and report structure. The live demo includes **three** preloaded sample datasets: **3GPP Wireless**, **ATE Test Equipment**, and **Mazda Infotainment** (each: log + debug reference). Try it at [demo.contextual.ai/log-analysis](https://demo.contextual.ai/log-analysis).


# Agent Composer YAML
Source: https://docs.contextual.ai/how-to-guides/agent-composer-yaml

Configuring the Agent Composer YAML file

<Note>
  Custom Agent Composer YAML workflows are available in public preview for enterprise users. Template agents (Basic Search and Agentic Search) are available for self-serve users, but creating custom workflows with YAML requires enterprise access. For more information or to request access, please contact your Contextual AI representative.
</Note>

## Overview

The Agent Composer YAML lets you define **executable agent workflows** as graphs. Each workflow describes:

* What inputs it accepts,
* How data flows between steps (nodes),
* What outputs it produces,
* What is surfaced to the UI

A workflow is compiled into an `ExecutableGraph` and run via the `/query/acl` API.

<Note>
  The following resources can also aid you in building Agent Composer workflows via YAML:

  <ul>
    <li><a href="/how-to-guides/ac-yaml-reference">Agent Composer YAML Reference Catalog</a></li>
    <li><a href="/how-to-guides/ac-yaml-cheatsheet">Agent Composer YAML Cheatsheet</a></li>
  </ul>
</Note>

***

## A Minimal Workflow Example

The following is the smallest useful Agent Composer YAML. You can copy/paste this and run it immediately.

```yaml theme={null}
inputs:
  query: str

outputs:
  response: str

nodes:
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query

  __outputs__:
    type: output
    input_mapping:
      response: generate#response
```

Here's what it does:

* Accepts a single input: `query`
* Runs a generation step
* Returns a single output: `response`
* Automatically displays `response` in the UI

***

## An Extended Workflow Example

The following workflow defines a retrieval-augmented question-answering pipeline that takes a user query, builds conversational context, performs structured agentic research over a vectorized document datastore, and generates a grounded response strictly based on retrieved evidence.

```yaml theme={null}
version: 0.1
inputs:
  query: str

outputs:
  response: str

nodes:
  create_message_history:
    type: CreateMessageHistoryStep
    input_mapping:
      query: __inputs__#query

  research:
    type: AgenticResearchStep
    ui_stream_types:
      retrievals: true
    config:
      tools_config:
        - name: search_docs
          description: |
            Search the datastore containing user-uploaded documents. This datastore is a vector database of text chunks which uses hybrid semantic and lexical search to find the most relevant chunks.
            Use this tool to find information within the uploaded documents.
          step_config:
            type: SearchUnstructuredDataStep
            config:
              top_k: 50 # Retrieve 50 chunks from vector search
              lexical_alpha: 0.1          # Weight for lexical (BM25) search
              semantic_alpha: 0.9         # Weight for semantic (vector) search
              reranker: "ctxl-rerank-v2-instruct-multilingual-FP8"
              rerank_top_k: 12
              reranker_score_filter_threshold: 0.2

      agent_config:
        agent_loop:
          num_turns: 10
          parallel_tool_calls: false
          model_name_or_path: "vertex_ai/claude-opus-4-5@20251101"
          identity_guidelines_prompt: |
            You are a retrieval-augmented assistant created by Contextual AI. You provide factual, grounded answers to user's questions by retrieving information via tools and then synthesizing a response based only on what you retrieved.

          research_guidelines_prompt: |
            You have access to the following tool:
            - `search_docs` — Search the document datastore. Returns SEARCH_RESULTS with CITE_ID for citation.
            
            You have access to the following data source:
            1. Document Datastore (Unstructured): 
                - Contains user-uploaded documents that have been parsed, extracted, and chunked for efficient retrieval.
                - Use the `search_docs` tool to query this datastore for relevant content, details, and information from the available documents.
            
            ## Research Strategy
            You MUST always explore unstructured datastore before answering. Do not skip the source.
            - Breadth, then depth strategy:
                1. INITIAL RETRIEVAL - FIRST (Mandatory):
                  - Documents: Use `search_docs` with your initial search terms.
                2. ANALYZE & PLAN: Review initial results and create a query plan:
                  - What information is still missing to fully answer the question?
                  - Create a specific plan: which queries to run next and in what order
                  - Identify dependencies: what do you need to find first before searching for related info?
                3. DEEP DIVE (Execute & Adapt): Execute your plan and adapt based on retrieved content:
                  - Run planned queries systematically
                  - Continue until you have a COMPLETE answer - don't stop early
            - EFFICIENCY: You have 10 turns. Be strategic:
                - Avoid redundant searches; prefer high-quality retrievals.
                - Batch related searches when possible
                - Don't repeat similar queries
                - Prioritize high-value retrievals first
                - But DO NOT sacrifice comprehensiveness for speed - gather ALL relevant information

    input_mapping:
      message_history: create_message_history#message_history

  generate:
    type: GenerateFromResearchStep
    ui_stream_types:
      generation: true
    config:
      model_name_or_path: "vertex_ai/claude-opus-4-5@20251101"

      identity_guidelines_prompt: |
        You are a retrieval-augmented assistant created by Contextual AI. Your purpose is to provide factual, grounded answers by retrieving information via tools and then synthesizing a response based only on what you retrieved. Always start immediately with the answer, don't begin with a preamble or thoughts. 

      response_guidelines_prompt: |
        ## Output
        - Write a concise, direct, well-structured answer in **Markdown** (use short headings, bullets, and brief paragraphs).
        - **START IMMEDIATELY WITH THE ANSWER.** Never begin with preamble like:
          - "Perfect!", "Great!", "Based on my research...", "I now have comprehensive information..."
          - "Let me provide...", "I can now provide...", "Here's what I found..."
          - Any meta-commentary about your search process or confidence level
        - Your first words should be the actual content (a heading, the direct answer, or the key fact).
        - If the required fact is missing from the latest **SEARCH_RESULTS**:
          - Partial or Related Information: Provide whatever relevant details you found, while clearly stating the limitations or gaps.
          - No Relevant Information: If nothing related was found, reply with: "I don't have specific information about [topic] in the available documents."
          - Maintain Engagement: Suggest related topics or alternative ways you can assist to keep the interaction productive.
        - DO NOT engage in character play. You must maintain a friendly, professional, and neutral tone at all times.

    input_mapping:
      message_history: create_message_history#message_history
      research: research#research

  __outputs__:
    type: output
    input_mapping:
      response: generate#response
```

This workflow enforces a disciplined research strategy—mandatory document retrieval, iterative planning, and deep dives—using a hybrid semantic-lexical search with reranking for precision, followed by a constrained generation step that produces concise, well-structured Markdown answers without meta commentary or speculation.

***

## YAML Schema (Root-level Fields)

Every Agent Composer YAML file defines a `graph` with the following root fields:

| Field       | Required | Description                                 |
| ----------- | -------- | ------------------------------------------- |
| `inputs`    | ✅        | Graph inputs and their Python types         |
| `outputs`   | ✅        | Graph outputs (must be JSON-serializable)   |
| `nodes`     | ✅        | Nodes and their connections                 |
| `ui_output` | ⚠️       | Required only if there are multiple outputs |

### Important Constraints

* The **root graph currently accepts only one input:** `query: str` (unless the graph is used as a subgraph).
* Graph outputs must be **JSON-serializable**, as they are returned by the API.
* If **more than one output exists**, exactly one must be selected as `ui_output`.

**Example:**

```yaml theme={null}
ui_output: response
```

***

## Wiring & Mapping Syntax

Nodes are connected using **output references** of the form:

```yaml theme={null}
node_name#output_key
```

### Special Nodes

* `__inputs__`
  Represents graph inputs defined under inputs.
* `__outputs__`
  Explicitly maps node outputs to graph outputs.

### Example Wiring

```yaml theme={null}
input_mapping:
  query: __inputs__#query
  processed_query: preprocess#output
```

Conceptually:

**inputs**.query → preprocess.output → finalize.response → **outputs**.response

***

## Nodes

A node represents a single operation in the graph with the following standard structure:

```yaml theme={null}
example_node:
  type: SomeStepType
  config:
    some_param: 0.5
  input_mapping:
    input_name: upstream_node#output
```

### Node Fields

* `type` (required): The step type (must be registered in the system).
* `input_mapping` (required if inputs exist): Wires node inputs to outputs from other nodes.
* `config` (optional): Static configuration passed at graph construction time.
* `config_overrides` (optional): Dynamic configuration resolved at execution time.
* `ui_stream_types` (optional): Controls what this node streams to the UI.

<Note>All declared inputs of a node must be connected, or graph validation will fail.</Note>

### Node Types

| Node Type      | Steps                                                                                                                                                                                                                                                                                                |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Primitive**  | `InputNode`, `OutputNode`, `ConditionalStep`, `PassThroughStep`, `GetMemberStep`, `SetMemberStep`, `ConstantStep`, `WrapStep`, `JSONCreatorStep`, `IsFirstTurnStep`, `SliceStep`, `LengthStep`, `IndexStep`, `AppendStep`, `ConcatenateStep`, `MergeStep`, `MergeRetrievalsStep`, `DeleteMemberStep` |
| **Retrieval**  | `FileAnalysisInputStep`, `ContextualAgentStep`, `SearchStructuredDataStep`, `SearchUnstructuredDataStep`, `QueryStructuredDatastoreStep`, `GetStructuredDatastoreSchemaStep`, `ReformulateQueryStep`, `MetadataSearchStep`                                                                           |
| **Tool**       | `WebSearchStep`, `CodeExecutionStep`, `MCPClientStep`, `SalesforceSOSLStep`                                                                                                                                                                                                                          |
| **Utilities**  | `LanguageModelStep`, `WebhookStep`, `CreateMessageHistoryStep`                                                                                                                                                                                                                                       |
| **Agent**      | `AgenticResearchStep`, `GenerateFromResearchStep`                                                                                                                                                                                                                                                    |
| **generation** | `ResponseGenerationStep`, `ResponseGenFromResearchStep`, `PreHookStep`, `PostHookStep`                                                                                                                                                                                                               |

***

## Dynamic Configuration Overrides

`config_overrides` allow node configuration to be set dynamically at runtime.

```yaml theme={null}
search:
  type: SearchUnstructuredDataStep
  config:
    filter_retrievals: true
  config_overrides:
    top_k: __inputs__#top_k
  input_mapping:
    query: __inputs__#query
```

The following rules apply to dynamic configuration overrides:

* Overrides are merged with static `config`
* Overrides can come from **any node output**
* Nodes whose type has `OUTPUTS = None` cannot use config overrides

***

## Output Node

Every graph must explicitly define how node outputs map to graph outputs.

```yaml theme={null}
__outputs__:
  type: output
  input_mapping:
    response: generate#response
```

The output node:

* Has no config
* Has no outputs of its own
* Only maps values into graph outputs

***

## UI Streaming

Some nodes can stream events to the UI (retrievals, generation, etc.).

```yaml theme={null}
generate:
  type: ResponseGenerationStep
  ui_stream_types:
    generation: true
```

Bear in mind the following in regards to UI streaming:

* Each step type declares supported stream types and defaults
* Multiple nodes may stream the same type
* Streaming is independent of the final `ui_output`

***

## Subgraphs

Subgraphs are reusable workflows that can be embedded as nodes in other graphs.

You can think of a subgraph like a function:

* inputs = parameters
* outputs = return values
* nodes = function body

### Defining a Subgraph

```yaml theme={null}
document_retrieval:
  inputs:
    query: str
  outputs:
    documents: List[str]
  nodes:
    search:
      type: SearchStep
      input_mapping:
        query: __inputs__#query

    __outputs__:
      type: output
      input_mapping:
        documents: search#documents
```

### Using a Subgraph

```yaml theme={null}
retriever:
  type: subgraph:document_retrieval
  input_mapping:
    query: __inputs__#query
```

Bear in mind the following regarding subgraphs:

* Subgraphs can be nested
* Subgraphs can be reused multiple times
* Subgraphs have isolated input/output scopes

***

## Conditional Execution

Conditional nodes execute **exactly one branch** based on a condition.

```yaml theme={null}
conditional:
  type: ConditionalStep
  config:
    inputs:
      score: float
    outputs:
      result: str
    variable: score
    branches:
      - condition: ">= 0.8"
        executable: HighQualityProcessor
        output_mapping:
          __outputs__#result: processed
      - condition: "< 0.8"
        executable: LowQualityProcessor
        output_mapping:
          __outputs__#result: processed
  input_mapping:
    score: evaluator#score
```

Bear in mind the following rules regarding conditional execution:

* Conditions are evaluated top-to-bottom
* First matching branch is executed
* `__inputs__` inside a branch refers to conditional inputs, not graph inputs

***

## Agentic Research & Tool Usage

Agentic behavior in Agent Composer is implemented using **explicit agentic steps** that separate **research (tool use and planning)** from **final response generation**. This pattern makes agent workflows easier to reason about, debug, and control, while ensuring responses remain grounded in retrieved information.
A typical agentic workflow consists of three phases:

1. `CreateMessageHistoryStep` – Initialize structured conversation state
2. `AgenticResearchStep` – Perform multi-turn research using tools
3. `GenerateFromResearchStep` – Generate a final response grounded in research results

### Initializing Message History

The following step converts the raw user input into a structured `message_history` object. This standardized message format is required by agentic steps and ensures consistent conversational context throughout the workflow.

```yaml theme={null}
create_message_history:
  type: CreateMessageHistoryStep
  input_mapping:
    query: __inputs__#query
```

This step:

* Transforms the user’s `query` into a structured message format
* Establishes a consistent conversation state
* Produces `message_history`, which is reused by both research and generation steps

### Agentic Research Step

The following step runs an internal agent loop that plans, executes, and adapts retrieval strategies over multiple turns. It is responsible for all tool usage and information gathering.

```yaml theme={null}
research:
  type: AgenticResearchStep
  ui_stream_types:
    retrievals: true
```

This step:

* Controls the agent’s reasoning and decision-making process
* Determines when and how tools are invoked
* Iteratively retrieves information until sufficient coverage is achieved
* Produces a structured `research` output used downstream

Enabling `retrievals` streaming allows retrieved documents and search activity to be surfaced in the UI.

### Defining Tools for the Agent

The following configuration defines tools that the agent may use during research. Each tool wraps a standard step or subgraph and is exposed to the agent as a callable capability.

```yaml theme={null}
tools_config:
  - name: search_docs
    description: Search the datastore containing user-uploaded documents.
    step_config:
      type: SearchUnstructuredDataStep
      config:
        top_k: 50
        lexical_alpha: 0.1
        semantic_alpha: 0.9
        reranker: ctxl-rerank-v2-instruct-multilingual-FP8
        rerank_top_k: 12
        reranker_score_filter_threshold: 0.2
```

Bear in mind the following key points:

* Tools are defined inline using either `step_config` or `graph_config`
* Each tool encapsulates a retrieval or processing capability
* Tool inputs must use basic Python types
* Tool outputs are returned to the agent as structured retrieval results
* Exactly one of the following must be provided for each tool:
  `step_config`
  `graph_config`

### Configuring the Agent Loop

The following configuration controls how the agent reasons and how many turns it may take when performing research.

```yaml theme={null}
agent_config:
  agent_loop:
    num_turns: 10
    parallel_tool_calls: false
    model_name_or_path: vertex_ai/claude-opus-4-5@20251101
```

This configuration determines:

* The maximum number of reasoning and tool-use iterations
* Whether the agent can invoke multiple tools in parallel
* The model used for agent planning and decision-making

### Guiding Agent Behavior with Prompts<br />

The following prompts define *who the agent is* and *how it should conduct research*. These prompts guide internal reasoning and are not exposed to the user.

**Identity Guidelines**<br />
The identity guidelines describe the agent’s role and grounding expectations, ensuring it behaves as a factual, retrieval-augmented assistant.

```
identity_guidelines_prompt: |
            You are a retrieval-augmented assistant created by Contextual AI. You provide factual, grounded answers to user's questions by retrieving information via tools and then synthesizing a response based only on what you retrieved.
```

**Research Guidelines**<br />
The research guidelines define the agent’s strategy, including:

* Mandatory use of retrieval tools before answering
* A breadth-first, then depth-first research approach
* Explicit planning between retrieval phases
* Adaptive execution based on retrieved content
* Efficiency constraints without sacrificing completeness

These instructions ensure consistent and repeatable agent behavior across runs.

```
 research_guidelines_prompt: |
            You have access to the following tool:
            - `search_docs` — Search the document datastore. Returns SEARCH_RESULTS with CITE_ID for citation.
            
            You have access to the following data source:
            1. Document Datastore (Unstructured): 
                - Contains user-uploaded documents that have been parsed, extracted, and chunked for efficient retrieval.
                - Use the `search_docs` tool to query this datastore for relevant content, details, and information from the available documents.
            
            ## Research Strategy
            You MUST always explore unstructured datastore before answering. Do not skip the source.
            - Breadth, then depth strategy:
                1. INITIAL RETRIEVAL - FIRST (Mandatory):
                  - Documents: Use `search_docs` with your initial search terms.
                2. ANALYZE & PLAN: Review initial results and create a query plan:
                  - What information is still missing to fully answer the question?
                  - Create a specific plan: which queries to run next and in what order
                  - Identify dependencies: what do you need to find first before searching for related info?
                3. DEEP DIVE (Execute & Adapt): Execute your plan and adapt based on retrieved content:
                  - Run planned queries systematically
                  - Continue until you have a COMPLETE answer - don't stop early
            - EFFICIENCY: You have 10 turns. Be strategic:
                - Avoid redundant searches; prefer high-quality retrievals.
                - Batch related searches when possible
                - Don't repeat similar queries
                - Prioritize high-value retrievals first
                - But DO NOT sacrifice comprehensiveness for speed - gather ALL relevant information
```

### Generating the Final Response

The following step synthesizes a final user-facing response using the structured research output produced by the agent.
generate:

```yaml theme={null}
  type: GenerateFromResearchStep
  ui_stream_types:
    generation: true
```

This step:

* Consumes `message_history` and research
* Produces the final response returned by the graph
* Ensures the answer is grounded strictly in retrieved information
* Enabling generation streaming allows partial responses to be shown in the UI as they are produced.

### Controlling Response Style and Grounding

The response configuration enforces formatting, tone, and grounding constraints for the final output.

```yaml theme={null}
config:
  model_name_or_path: vertex_ai/claude-opus-4-5@20251101
```

Response guidelines typically enforce:

* Immediate answers with no preamble or meta-commentary
* Clear, concise Markdown formatting
* Explicit handling of missing or incomplete information
* A professional and neutral tone

This ensures consistent output quality and prevents internal reasoning or research details from leaking into the final response.

### End-to-End Data Flow

The overall execution flow of an agentic workflow is as follows:

```
inputs.query
  → CreateMessageHistoryStep
    → message_history
      → AgenticResearchStep
        → research
          → GenerateFromResearchStep
            → outputs.response
```

Each phase has a clearly defined responsibility, making the workflow easier to understand, debug, and extend.

### Design Principles

The agentic research pattern in Agent Composer is guided by a small set of core design principles. These principles ensure agent workflows remain understandable, reliable, and easy to operate as they grow in complexity.

* Separation of concerns: research and generation are handled by different steps
* Grounded responses: final answers are derived only from retrieved content
* Observability: retrievals and generation can be streamed independently
* Determinism: agent behavior is fully specified by configuration

***

## Creating New Steps

To add a new step:

1. Implement a `PipelineStep` subclass
2. Define `INPUTS`, `OUTPUTS`, and optional UI metadata
3. Register it in `registrations.py`
4. Add it to the step catalog for discoverability

## Running Graphs Programmatically

To run graphs programmatically, use the following Python code:

```python theme={null}
graph = ExecutableGraph.from_yaml(yaml_string)
graph.execute_graph({"query": "Hello"})
```

Inputs map to **inputs**, and outputs are returned as a `dict`.

***

## API Response

Agent Composer (AC) workflows are executed via `/query/acl`, with the following response fields returned:

* `outputs:` graph outputs (JSON-serializable)
* `workflow_trace:` executed nodes and durations
* `dynamic_agent_trace:` agent reasoning and tool usage (if applicable)

***

## Common Validation Errors

The following are common validation errors and how to fix them:

| Validation Error                     | Fix                                           |
| ------------------------------------ | --------------------------------------------- |
| Unsupplied node inputs               | Ensure every required input is mapped.        |
| Missing `__outputs__` node           | Explicitly map node outputs to graph outputs. |
| Multiple outputs without `ui_output` | Designate exactly one UI output.              |
| Non-serializable outputs             | Convert outputs to basic types before output. |

***

## Additional Resources

* [Agent Composer YAML Reference Catalog](/how-to-guides/ac-yaml-reference)
* [Agent Composer YAML Cheatsheet](/how-to-guides/ac-yaml-cheatsheet)
* [Agent Composer Quickstart Guide](/quickstarts/agent-composer)
* [Agent Composer GUI How-to Guide](/how-to-guides/agent-composer-gui)


# Connect to Our Docs via MCP
Source: https://docs.contextual.ai/how-to-guides/connect-docs-mcp

Query Contextual AI documentation directly from Claude, Cursor, VS Code, and other AI tools

Query Contextual AI documentation in real-time from your favorite AI tools using the Model Context Protocol (MCP). Ask questions about our APIs, SDKs, Agent Composer, and more—without leaving your development environment.

## Overview

Our documentation is available as an MCP server, allowing AI applications to search and retrieve information directly. This means you can:

* **Ask questions** about Contextual AI APIs and features while coding
* **Get code examples** from our documentation in context
* **Search across all docs** without switching browser tabs

## MCP Server URL

```
https://docs.contextual.ai/mcp
```

***

## Setup Instructions

### Claude Desktop

1. Navigate to Claude's [Connectors settings page](https://claude.ai/settings/connectors)
2. Select **Add custom connector**
3. Enter the details:
   * **Name:** `Contextual AI Docs`
   * **URL:** `https://docs.contextual.ai/mcp`
4. Click **Add**
5. During chat, use the attachments button (plus icon) to access the docs

### Claude Code

Run this command in your terminal:

```bash theme={null}
claude mcp add --transport http contextual-docs https://docs.contextual.ai/mcp
```

Verify the installation:

```bash theme={null}
claude mcp list
```

### Cursor

1. Open the command palette (<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> on Mac, <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> on Windows)
2. Search for **MCP: Open User Configuration**
3. Add the following to your `mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "contextual-docs": {
      "url": "https://docs.contextual.ai/mcp"
    }
  }
}
```

4. Restart Cursor

### VS Code

Create a `.vscode/mcp.json` file in your project:

```json theme={null}
{
  "servers": {
    "contextual-docs": {
      "type": "http",
      "url": "https://docs.contextual.ai/mcp"
    }
  }
}
```

***

## Usage Examples

Once connected, you can ask questions like:

* "How do I create a datastore using the Python SDK?"
* "What are the parameters for the rerank API?"
* "Show me an example of Agent Composer YAML configuration"
* "How do I configure retrieval settings for my agent?"

Your AI tool will search the Contextual AI documentation and provide answers with relevant context.

***

## Notes

* The MCP server provides access to all public documentation pages
* Multiple MCP servers can be connected simultaneously—context is only consumed when actively searched
* The AI tool automatically determines when to search based on your query

***

## Related Resources

* [Contextual AI MCP Server](/quickstarts/mcp-server) — Build your own RAG-powered MCP server with Contextual AI
* [Python SDK Reference](/sdks/python) — Full SDK documentation
* [API Reference](/api-reference) — Complete API documentation


# Collecting & Annotating Feedback
Source: https://docs.contextual.ai/how-to-guides/feedback

Collecting user feedback and annotating it to identify and triage issues.

**Collecting feedback** on agent outputs helps teams understand where responses fall short—whether that’s in accuracy, tone, or usefulness. It captures real user signals that guide what to improve next.

**Annotating feedback** transforms those signals into structured insights. By labeling and triaging issues, teams can identify patterns, prioritize fixes, and create a clear feedback loop that drives continuous agent improvement. This is typically a part of the **quality assurance (QA)** process.

You can do both seamlessly on Contextual, with built-in tools to collect and annotate feedback in one place.

### Feedback Collection

The first phase is to collect feedback from your users.

1. Users can provide feedback on an agent’s output using a **thumbs up/thumbs down** rating or by **flagging** responses that need review. They can do so via the Contextual UI or via API.

On the Contextual UI, you can click on the feedback icons to leave feedback.

<img alt="FeedbackGiving.png" />

<ins>API</ins>

We provide an [API for users to leave feedback programatically](https://docs.contextual.ai/api-reference/agents-query/provide-feedback). In the API body, you can flag the query as `thumbs_up`, `thumbs_down`, or `flagged` and include an `explanation`. Here's an example:

```
curl --request POST \
  --url https://api.contextual.ai/v1/agents/{agent_id}/feedback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "feedback": "thumbs_down",
  "explanation": "The response did not answer the question",
  "content_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}'
```

2. On the Contextual UI, if you leave a thumbs down, you will be prompted to leave freeform feedback and select the reasons for the feedback.

   <img alt="2-FeedbackGiving.gif" />
3. Admins are able to configure the feedback workflow that users go through. Navigate to the agent configuration menu and click on `User Experience` under the `Advanced` section. Scroll down to `Feedback Customization`.

<img alt="Screenshot 2025-11-05 at 7.50.29 PM.png" />

4. In the Feedback Customization section, you have three configs:
   1. **Enable Mandatory Feedback:** Toggle this if you require your users to provide feedback before submitting a new query.
   2. **Show Feedback Dialog for Thumbs Up:** On the Contextual UI, we will prompt the user to leave details if they submit a `thumbs_down`. With this option enabled, we will also prompt users if they submit a `thumbs_up`.
   3. **Customized feedback options for thumbs down:** When a user gives a thumbs down, they’ll be prompted to provide additional context by selecting one or more reasons for their feedback. This setting allows you to customize the list of reasons users can choose. If this section is blank, we will show users a list of default reasons.
      1. You can click `Preview` to see how the feedback workflow will look like.

<img alt="1-FeedbackSetup.gif" />

### Feedback Annotation

After collecting feedback from real users, you can annotate the feedback as part of your quality assurance (QA) workflow.

1. Before starting your annotation, you will need to configure your annotation labels. Navigate to the agent configuration menu and click on `Feedback Annotation` under the `Advanced` section.

   <img alt="Screenshot 2025-11-05 at 8.04.39 PM.png" />
2. There are four annotation columns you can define labels for. The first column is `Query Categories`.  To add a label, click `Add Query Category`. You can remove a label by clicking the `-` icon. Finally, you can turn on `Intelligent Categorization` which will automatically classify all flagged queries into one of the labels you've defined.

   <img alt="Screenshot 2025-11-05 at 8.09.45 PM.png" />
3. Repeat the same process for the other three columns: `Error Categories` (annotate any issues identified), `Response Quality` (annotate the overall quality of the response), `Resolution Status` (annotate the status of the issue -- open/closed/etc).
4. You can also rename any of the existing columns. If you’d like to introduce a new column type beyond the four provided by default, simply update one of the column names to match the new category you want to track.

   <img alt="6-CustomizeColNames.png" />
5. Click `Save` at the bottom when you are done.
6. Navigate to the `Feedback Annotation` module through the agent menu.

   <img alt="3-NavigateModuleNew.gif" />
7. To annotate a piece of feedback, simply click on it. The annotation UI will pop up and you can annotate with the custom labels you defined previously.

   <img alt="7-AnnotationWorkflowFast.gif" />
8. You can click on citations in the annotation UI to view source chunks.

   <img alt="9-InspectChunk.gif" />
9. You can also filter the feedback list to focus on what matters most. Filters can be applied by any column or by the date the feedback was submitted.

   <img alt="8-Filters.gif" />
10. There are a few other capabilities in the annotation dashboard:

* Click `Export to CSV` to download the annotated data
* Click the eye icon to select which columns to display
* You can also choose which column to sort by.

<img alt="Screenshot 2025-11-05 at 8.27.55 PM.png" />

11. Finally, you can click the `Dashboard` button at the top to view an **auto-generated dashboard** that visualizes your annotated feedback results.

Navigating to the Dashboard:

<img alt="Screenshot 2025-11-05 at 8.29.51 PM.png" />

Viewing the Dashboard:

<img alt="10-Dashboard.png" />


# Generate
Source: https://docs.contextual.ai/how-to-guides/generate

Contextual AI How-to Guide

## Overview

Contextual AI's Grounded Language Model (GLM) is the most grounded language model in the world, making it the best language model to use for RAG and agentic use cases for which minimizing hallucinations is critical.

## Global Variables & Examples

First, we will set up the global variables and examples we'll use with each different implementation method.

```python theme={null}
from google.colab import userdata

api_key = userdata.get("API_TOKEN")
base_url = "https://api.contextual.ai/v1"
generate_api_endpoint = f"{base_url}/generate"
```

```python theme={null}
# Example conversation messages
messages = [
    {
        "role": "user",
        "content": "What are the most promising renewable energy technologies for addressing climate change in developing nations?"
    },
    {
        "role": "assistant",
        "content": "Based on current research, solar and wind power show significant potential for developing nations due to decreasing costs and scalability. Would you like to know more about specific implementation challenges and success stories?"
    },
    {
        "role": "user",
        "content": "Yes, please tell me about successful solar implementations in Africa and their economic impact, particularly focusing on rural electrification."
    }
]

# Detailed knowledge sources with varied information
knowledge = [
    """According to the International Renewable Energy Agency (IRENA) 2023 report:
    - Solar PV installations in Africa reached 10.4 GW in 2022
    - The cost of solar PV modules decreased by 80% between 2010 and 2022
    - Rural electrification projects have provided power to 17 million households""",

    """Case Study: Rural Electrification in Kenya (2020-2023)
    - 2.5 million households connected through mini-grid systems
    - Average household income increased by 35% after electrification
    - Local businesses reported 47% growth in revenue
    - Education outcomes improved with 3 additional study hours per day""",

    """Economic Analysis of Solar Projects in Sub-Saharan Africa:
    - Job creation: 25 jobs per MW of installed capacity
    - ROI average of 12-15% for mini-grid projects
    - Reduced energy costs by 60% compared to diesel generators
    - Carbon emissions reduction: 2.3 million tonnes CO2 equivalent""",

    """Technical Specifications and Best Practices:
    - Optimal solar panel efficiency in African climate conditions: 15-22%
    - Battery storage requirements: 4-8 kWh per household
    - Maintenance costs: $0.02-0.04 per kWh
    - Expected system lifetime: 20-25 years""",

    """Social Impact Assessment:
    - Women-led businesses increased by 45% in electrified areas
    - Healthcare facilities reported 72% improvement in service delivery
    - Mobile money usage increased by 60%
    - Agricultural productivity improved by 28% with electric irrigation"""
]
```

## Direct API implementation

```python theme={null}
import requests

headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": f"Bearer {api_key}"
}
```

```python theme={null}
payload = {
    "model": "v1",
    "messages": messages,
    "knowledge": knowledge,
    "avoid_commentary": False,
    "max_new_tokens": 1024,
    "temperature": 0,
    "top_p": 0.9
}

generate_response = requests.post(generate_api_endpoint, json=payload, headers=headers)

print(generate_response.json()['response'])
```

```
Let me share the current state of solar energy in Africa, focusing on rural electrification and its economic impact:

Africa has seen significant solar PV adoption, with total installations reaching 10.4 GW as of 2022, supported by an 80% decrease in solar PV module costs between 2010 and 2022.

The impact on rural communities has been particularly noteworthy:

Rural electrification initiatives have already connected 17 million households to power. A specific case study in Kenya (2020-2023) demonstrated impressive results:
- 2.5 million households were connected through mini-grid systems
- Average household income increased by 35%
- Local businesses saw 47% revenue growth
- Students gained 3 additional study hours per day

The economic benefits extend beyond household income:

The solar industry has created substantial economic opportunities:
- Each MW of installed capacity generates 25 jobs
- Mini-grid projects typically achieve 12-15% ROI
- Energy costs have been reduced by 60% compared to diesel generators
- The projects have resulted in 2.3 million tonnes CO2 equivalent in emissions reduction

The social impact has been particularly significant:

The data shows:
- 45% increase in women-led businesses
- 72% improvement in healthcare service delivery
- 60% increase in mobile money usage
- 28% improvement in agricultural productivity with electric irrigation
```

## Python SDK

```python theme={null}
try:
  from contextual import ContextualAI
except:
  %pip install contextual-client
  from contextual import ContextualAI

client = ContextualAI (api_key = api_key, base_url = base_url)
```

```python theme={null}
generate_response = client.generate.create(
    model="v1",
    messages=messages,
    knowledge=knowledge,
    avoid_commentary=False,
    max_new_tokens=1024,
    temperature=0,
    top_p=0.9
)

print(generate_response.response)
```

```
Let me share the current state of solar energy in Africa, focusing on rural electrification and its economic impact:

Africa has seen significant solar PV adoption, with total installations reaching 10.4 GW as of 2022, supported by an 80% decrease in solar PV module costs between 2010 and 2022.

The impact on rural communities has been particularly noteworthy:

Rural electrification initiatives have already connected 17 million households to power. A specific case study in Kenya (2020-2023) demonstrated impressive results:
- 2.5 million households were connected through mini-grid systems
- Average household income increased by 35%
- Local businesses saw 47% revenue growth
- Students gained 3 additional study hours per day

The economic benefits extend beyond household income:

The solar industry has created substantial economic opportunities:
- Each MW of installed capacity generates 25 jobs
- Mini-grid projects typically achieve 12-15% ROI
- Energy costs have been reduced by 60% compared to diesel generators
- The projects have resulted in 2.3 million tonnes CO2 equivalent in emissions reduction

The social impact has been particularly significant:

The data shows:
- 45% increase in women-led businesses
- 72% improvement in healthcare service delivery
- 60% increase in mobile money usage
- 28% improvement in agricultural productivity with electric irrigation
```

## Langchain

```
try:
  from langchain_contextual import ChatContextual
except:
  %pip install langchain-contextual
  from langchain_contextual import ChatContextual

# intialize Contextual llm via langchain_contextual
llm = ChatContextual(
    model="v1",
    api_key=api_key,
)
ai_msg = llm.invoke(
    messages,
    knowledge=knowledge,
    avoid_commentary=False,
    max_new_tokens=1024,
    temperature=0,
    top_p=0.9
)

print(ai_msg.content)
```

```
Let me share the current state of solar energy in Africa, focusing on rural electrification and its economic impact:

Africa has seen significant solar PV adoption, with total installations reaching 10.4 GW as of 2022, supported by an 80% decrease in solar PV module costs between 2010 and 2022.

The impact on rural communities has been particularly noteworthy:

Rural electrification initiatives have already connected 17 million households to power. A specific case study in Kenya (2020-2023) demonstrated impressive results:
- 2.5 million households were connected through mini-grid systems
- Average household income increased by 35%
- Local businesses saw 47% revenue growth
- Students gained 3 additional study hours per day

The economic benefits extend beyond household income:

The solar industry has created substantial economic opportunities:
- Each MW of installed capacity generates 25 jobs
- Mini-grid projects typically achieve 12-15% ROI
- Energy costs have been reduced by 60% compared to diesel generators
- The projects have resulted in 2.3 million tonnes CO2 equivalent in emissions reduction

The social impact has been particularly significant:

The data shows:
- 45% increase in women-led businesses
- 72% improvement in healthcare service delivery
- 60% increase in mobile money usage
- 28% improvement in agricultural productivity with electric irrigation
```

## LLamaIndex

```
try:
  from llama_index.llms.contextual import Contextual
  from llama_index.core.chat_engine.types import ChatMessage

except:
  %pip install -U llama-index-llms-contextual
  from llama_index.llms.contextual import Contextual
  from llama_index.core.chat_engine.types import ChatMessage

llm = Contextual(model="v1", api_key=api_key)
response = llm.complete(
    messages[0]['content'],
    knowledge=knowledge,
    avoid_commentary=False,
    max_new_tokens=1024,
    temperature=0,
    top_p=0.9
)

print(response.text)
```

```
Based on recent data and implementation results, solar energy emerges as a particularly promising renewable energy technology for developing nations. Here are the key findings:

As of 2022, solar PV installations in Africa have reached 10.4 GW, with solar PV module costs decreasing by 80% between 2010 and 2022.

The technology has demonstrated impressive economic and social impacts:

- Creates significant employment opportunities with 25 jobs per MW of installed capacity
- Delivers strong returns with 12-15% ROI for mini-grid projects
- Reduces energy costs by 60% compared to diesel generators
- Achieves substantial carbon savings of 2.3 million tonnes CO2 equivalent

The implementation data shows remarkable social benefits:

- Rural electrification projects have connected 17 million households
- In Kenya specifically, 2.5 million households have been connected through mini-grid systems
- Average household income increased by 35% after electrification
- Local businesses reported 47% growth in revenue
- Education outcomes improved with 3 additional study hours per day

From a technical perspective:

- Solar panels achieve optimal efficiency of 15-22% in African climate conditions
- Systems require 4-8 kWh of battery storage per household
- Maintenance costs are relatively low at $0.02-0.04 per kWh
- Systems have an expected lifetime of 20-25 years

These metrics demonstrate solar energy's potential as a viable solution for developing nations.
messages_llama_index = [ChatMessage(role=message['role'], content=message['content']) for message in messages]

response = llm.chat(
    messages_llama_index,
    knowledge_base=knowledge,
    avoid_commentary=False,
    max_new_tokens=1024,
    temperature=0,
    top_p=0.9
)

print(response)
```

```
assistant: Let me share the current state of solar energy in Africa, focusing on rural electrification and its economic impact:

Africa has seen significant solar PV adoption, with total installations reaching 10.4 GW as of 2022, supported by an 80% decrease in solar PV module costs between 2010 and 2022.

The impact on rural communities has been particularly noteworthy:

Rural electrification initiatives have already connected 17 million households to power. A specific case study in Kenya (2020-2023) demonstrated impressive results:
- 2.5 million households were connected through mini-grid systems
- Average household income increased by 35%
- Local businesses saw 47% revenue growth
- Students gained 3 additional study hours per day

The economic benefits extend beyond household income:

The solar industry has created substantial economic opportunities:
- Each MW of installed capacity generates 25 jobs
- Mini-grid projects typically achieve 12-15% ROI
- Energy costs have been reduced by 60% compared to diesel generators
- The projects have resulted in 2.3 million tonnes CO2 equivalent in emissions reduction

The social impact has been particularly significant:

The data shows:
- 45% increase in women-led businesses
- 72% improvement in healthcare service delivery
- 60% increase in mobile money usage
- 28% improvement in agricultural productivity with electric irrigation
```

## Multi-Turn Conversations

The GLM supports multi-turn conversations, but with an important consideration: the model is stateless and knowledge does not automatically persist between turns. This means:

* To continue a conversation using the same knowledge: You must provide your knowledge array again with each new request.
* To continue a conversation with additional information: You must combine your existing knowledge array with the new information and provide the complete updated array.

Remember that the GLM relies entirely on the knowledge you explicitly provide in each request, as it prioritizes these facts over its parametric knowledge.

```
#@title First Turn of Conversation
user_msg_1 = "Tell me about the Emperor Penguin"

messages_1 = [
    {
        "role": "user",
        "content": user_msg_1
    }
]

knowledge_1 = [
    "Emperor penguins (Aptenodytes forsteri) are the tallest and heaviest of all living penguin species, standing up to 122 cm (48 inches) tall and weighing up to 45 kg (99 pounds).",
    "Emperor penguins are the only penguin species that breeds during the Antarctic winter, enduring temperatures as low as -60°C (-76°F) and wind speeds up to 200 km/h (124 mph).",
    "Male Emperor penguins incubate their single egg for about 65-75 days while balancing it on their feet and covering it with a special brood pouch, during which time they don't eat and can lose up to 45% of their body weight.",
    "Emperor penguins can dive deeper than any other bird, reaching depths of up to 565 meters (1,850 feet) and staying underwater for up to 22 minutes when hunting for fish, squid and krill."
]

response = client.generate.create(
    knowledge=knowledge_1,
    messages=messages_1,
    model="v1",
)

returned_response = response.to_dict()['response']

print(f"User: {user_msg_1}\n\n")
print(f"Assistant: {returned_response}")
```

```
User: Tell me about the Emperor Penguin

Assistant: Let me tell you about the Emperor Penguin's remarkable characteristics and behaviors:

Emperor penguins are the largest penguin species, reaching heights of up to 122 cm (48 inches) and weighing up to 45 kg (99 pounds).

Their breeding habits are particularly fascinating:

They are unique among penguins as they breed during the Antarctic winter, withstanding extreme conditions including:
- Temperatures as low as -60°C (-76°F)
- Wind speeds up to 200 km/h (124 mph)

During breeding, male Emperor penguins take on remarkable parental responsibilities:
- They incubate a single egg for 65-75 days
- They balance the egg on their feet and cover it with a special brood pouch
- During this time, they fast and can lose up to 45% of their body weight

Their hunting abilities are equally impressive:

Emperor penguins are exceptional divers, capable of:
- Reaching depths of up to 565 meters (1,850 feet)
- Staying underwater for up to 22 minutes
- Hunting for fish, squid, and krill
```

```
#@title Second Turn (without Extending Knowledge)
user_msg_2 = "Compare the emperor penguin with the adelie penguin"
messages_2 = [
    {
        "role": "user",
        "content": user_msg_1
    },
    {
        "role": "assistant",
        "content": returned_response,
    },
    {
        "role": "user",
        "content": user_msg_2
    }
]
knowledge_2 = [
  "Adélie penguins (Pygoscelis adeliae) are named after Adélie Land, a territory in Antarctica discovered by French explorer Jules Dumont d'Urville, who named it after his wife.",
  "Adélie penguins are one of the most southerly distributed birds and one of only two penguin species that are truly Antarctic (the other being the Emperor penguin), breeding exclusively on the Antarctic continent and nearby islands.",
  "Adélie penguins build nests made of small stones which they sometimes steal from neighboring nests, and males present these stones as gifts to potential mates during courtship.",
  "With a distinctive white ring around their eyes, Adélie penguins are excellent swimmers that can travel up to 185 km (115 miles) round trip to forage for food and can reach swimming speeds of up to 45 km/h (28 mph)."
]

print('This is turn 2')
print(f"User: {user_msg_2}\n\n")

response_2_bad = client.generate.create(
    knowledge=knowledge_2,
    messages=messages_2,
    model='v1',
)
print(f"Assistant: {response_2_bad.to_dict()['response']}")
```

```
This is turn 2
User: Compare the emperor penguin with the adelie penguin

Assistant: I can provide some basic comparisons between these two penguin species based on the available information:

Both Emperor and Adélie penguins are truly Antarctic species, with Adélie penguins breeding exclusively on the Antarctic continent and nearby islands.

Adélie penguins have distinctive physical characteristics, including a white ring around their eyes.

Regarding their behavior, Adélie penguins are known to:
- Build nests using small stones
- Sometimes steal stones from neighboring nests
- Use stones as gifts during courtship
- Travel up to 185 km (115 miles) for food
- Reach swimming speeds of up to 45 km/h (28 mph)

I don't have specific information about Emperor penguins in the provided documentation to make a more detailed comparison. If you'd like to know more about Emperor penguins specifically, I'd be happy to share that information if you provide it.
```

```
#@title Second Turn (with Extending Knowledge)
extended_knowledge = knowledge_1 + knowledge_2

print(f"User: {user_msg_2}\n\n")
response_2_good = client.generate.create(
    knowledge=extended_knowledge,
    messages=messages_2,
    model='v1',
)

print(f"Assistant: {response_2_good.to_dict()['response']}")
```

```
User: Compare the emperor penguin with the adelie penguin

Assistant: Let me compare these two fascinating penguin species based on the available information:

Emperor penguins are the largest penguin species, reaching heights of up to 122 cm (48 inches) and weighing up to 45 kg (99 pounds).

Both species are well adapted to extreme Antarctic conditions, with Emperor penguins being the only species that breeds during the Antarctic winter, enduring temperatures as low as -60°C (-76°F) and wind speeds up to 200 km/h (124 mph).

Adélie penguins are one of the most southerly distributed birds and, along with Emperor penguins, are truly Antarctic, breeding exclusively on the Antarctic continent and nearby islands.

When it comes to breeding behaviors:
- Emperor penguins have males incubating eggs for 65-75 days while fasting and losing up to 45% of their body weight
- Adélie penguins build nests using small stones, which they sometimes take from neighboring nests

In terms of swimming abilities:
- Emperor penguins can dive to 565 meters (1,850 feet) and stay underwater for up to 22 minutes
- Adélie penguins can travel up to 185 km (115 miles) round trip while foraging and reach swimming speeds of up to 45 km/h (28 mph)
```

## Additional Resources

* [Read the blog post](https://contextual.ai/blog/introducing-grounded-language-model) to learn more about the GLM and the criticality of groundedness in enterprise AI
* [Access the related notebook](https://github.com/ContextualAI/examples/blob/main/03-standalone-api/02-generate/generate.ipynb) that demonstrates how to use the GLM with the Contextual API directly, our Python SDK, and our Langchain package
* [API Reference](/api-reference/generate/generate)
* [Python SDK](https://github.com/ContextualAI/contextual-client-python/blob/main/api.md#generate)
* [Langchain Package](https://pypi.org/project/langchain-contextual/)
* [LlamaIndex Integration](https://github.com/run-llama/llama_index/tree/main/llama-index-integrations/llms/llama-index-llms-contextual)


# LMUnit
Source: https://docs.contextual.ai/how-to-guides/lmunit

Contextual AI How-to Guide

## Overview

Evaluating LLM outputs is critical, but underexplored for generative AI uses cases. Natural language unit tests provide a systematic approach for evaluating LLM response quality. Contextual AI's LMUnit is a specialized model that achieves state-of-the-art performance in creating and applying unit tests to evaluate LLM outputs.

### Why Natural Language Unit Testing?

Traditional LLM evaluation methods often face several challenges:

* Human evaluations are inconsistent and costly, while metrics like ROUGE fail to capture nuanced quality measures.
* General-purpose LLMs may not provide fine-grained feedback
* Simple yes/no evaluations miss important nuances

Natural language unit tests address these challenges by:

* Breaking down evaluation into specific, testable criteria
* Providing granular feedback on different quality aspects
* Enabling systematic improvement of LLM outputs
* Supporting domain-specific quality requirements

For example, financial compliance often requires precise regulatory phrasing, which is hard to assess with a generic style evaluation.

## 1. Set Up Development Environment

Set up your environment to start using LMUnit to evaluate LLM responses. This example uses LMUnit as provided through the Contextual AI python client, so install it first.

```python theme={null}
%pip install contextual-client tqdm
```

You'll need several Python packages for data handling and visualization:

```python theme={null}
import os
import pandas as pd
from contextual import ContextualAI

# polar plots
import numpy as np
import matplotlib.pyplot as plt
from typing import List, Dict, Optional, Union, Tuple

#clustering analysis
from sklearn.cluster import KMeans
from sklearn.preprocessing import StandardScaler
import seaborn as sns
```

<Note>
  To use LMUnit, you'll need an API key from Contextual AI. [Follow these instructions](/quickstarts/getting-started#get-your-api-key) to get your API key.
</Note>

```python theme={null}
client = ContextualAI(api_key="ADD YOUR KEY HERE")
# Consider using environment variables for production environments.
```

## 2. Load Evaluation Dataset

LMUnit evaluates query–response pairs, which means we need:

* **The original query/prompt** — `prompt`
* **The LLM’s response** — `response`

This example uses synthetic financial data. The dataset contains 10 financial questions and responses designed to highlight different aspects of response-quality evaluation.

```python theme={null}
df = pd.read_csv(
    'data/financial_qa_pairs.csv' if os.path.exists('data/financial_qa_pairs.csv')
    else "https://raw.githubusercontent.com/ContextualAI/examples/refs/heads/main/03-lmunit/data/financial_qa_pairs.csv"
)
df.head()
```

## 3. Identify Unit Tests

Unit tests offer deeper insight than simply asking an LLM whether a response is “high quality.” When writing effective unit tests, strive to ensure they are:

* **Specific** and focused on a single aspect
* **Clear** and unambiguous
* **Measurable** and consistent
* **Relevant** to the domain
* **Framed positively**

You should create unit tests tailored to your own use case.

For this example, we use **six global unit tests** across all responses. These reflect critical dimensions of high-quality communication in financial services.

### **Context**

**Question:** “Are relevant market conditions or external factors acknowledged?”\
**Why:** Ensures responses consider the broader financial environment.

### **Clarity**

**Question:** “Is complex financial information presented in an accessible way?”\
**Why:** Tests whether technical concepts are explained effectively.

### **Precision**

**Question:** “Is terminology used accurately and consistently?”\
**Why:** Validates the correct use of financial terms.

### **Compliance**

**Question:** “Does the response adhere to relevant financial regulations and disclosure requirements?”\
**Why:** Ensures regulatory alignment.

### **Actionable**

**Question:** “Does the response provide clear next steps or implications?”\
**Why:** Tests practical usefulness.

### **Risks**

**Question:** “Are potential risks clearly identified and explained?”\
**Why:** Verifies appropriate risk disclosure.

```python theme={null}

unit_tests = [
    "Are relevant market conditions or external factors acknowledged?",
    "Is complex financial information presented in an accessible way?",
    "Is terminology used accurately and consistently?",
    "Does the response adhere to relevant financial regulations and disclosure requirements?",
    "Does the response provide clear next steps or implications?",
    "Are potential risks clearly identified and explained?"
]
```

## 4. Evaluate Unit Tests Using LMUnit

LMUnit is specifically trained to evaluate natural-language unit tests and provides several advantages:

* **Scores on a continuous 1–5 scale**
* **Consistent evaluation** across different criteria
* **Stronger performance** than general-purpose LLMs like GPT-4
* **Support for custom scoring rubrics**
* **Threshold-based binary scoring**, e.g., *score > 2.5 → 1, else 0*

Below is a simple example demonstrating how LMUnit evaluates a response against a single unit test.

```python theme={null}
response = client.lmunit.create(
    query="What material is used in N95 masks?",
    response=(
        "N95 masks are made primarily of polypropylene. This synthetic material is created "
        "through a melt-blowing process that creates multiple layers of microfibers. "
        "The material was chosen because it can be electrostatically charged to attract "
        "particles. Particles are the constituents of the universe"
    ),
    unit_test="Does the response avoid unnecessary information?"
)

print(response)
```

Here is more complex example with a custom scoring rubric:

```python theme={null}
response = client.lmunit.create(
                    query="How effectively can the company's current AI system handle customer service inquiries?",
                    response= """ Response: Our AI system currently handles 70% of customer inquiries without human intervention. 
                    It excels at processing returns and tracking orders, but struggles with complex billing disputes. 
                    Response times average 30 seconds, though this increases to 2 minutes during peak hours. 
                    The system successfully resolves basic inquiries but often fails to understand context-dependent questions 
                    or multiple requests within the same conversation. """,
                  unit_test= """
                    Does the response provide specific, measurable performance metrics?
                  Scoring Scale:
                  Score 1: No specific metrics provided; vague or general statements only
                  Score 2: Limited metrics provided; either strengths or limitations discussed, but not both
                  Score 3: Basic metrics provided with surface-level analysis of strengths and limitations
                  Score 4: Clear metrics provided with detailed analysis of both strengths and limitations
                  Score 5: Comprehensive metrics with in-depth analysis of strengths, limitations, and contextual factors
                    """
                    
                )
print(response)
```

For this use case, you will need to apply each global unit test to the query/response pairs we identified in the evaluation data. Here is helper function for testing batches:

```python theme={null}
from typing import List, Dict
from tqdm import tqdm

def run_unit_tests_with_progress(
    df: pd.DataFrame,
    unit_tests: List[str],
    batch_size: int = 10
) -> List[Dict]:
    """
    Run unit tests with progress tracking and error handling.

    Args:
        df: DataFrame with prompt-response pairs
        unit_tests: List of unit test strings
        batch_size: Number of tests to run in parallel

    Returns:
        List of test results
    """
    results = []

    # Process in batches with progress bar
    for idx in tqdm(range(0, len(df)), desc="Processing responses"):
        row = df.iloc[idx]
        row_results = []

        for test in unit_tests:
            try:
                result = client.lmunit.create(
                    query=row['prompt'],
                    response=row['response'],
                    unit_test=test
                )
                row_results.append({
                    'test': test,
                    'score': result.score,
                    'metadata': result.metadata if hasattr(result, 'metadata') else None
                })
            except Exception as e:
                print(f"Error with prompt {idx}, test '{test}': {e}")
                row_results.append({
                    'test': test,
                    'score': None,
                    'error': str(e)
                })

        results.append({
            'prompt': row['prompt'],
            'response': row['response'],
            'test_results': row_results
        })

    return results
```

```python theme={null}
results = run_unit_tests_with_progress(df, unit_tests)
```

Now examine the results—you see every unit test is scored on a continuous scale of 1-5.

```python theme={null}
for result in results[:2]:  # Slice to get the first two entries
    print(f"\nPrompt: {result['prompt']}")
    print(f"Response: {result['response']}")
    print("Test Results:")
    for test_result in result['test_results']:
        print(f"- {test_result['test']}: {test_result['score']}")
```

Save out the results

```python theme={null}
pd.DataFrame([(r['prompt'], r['response'], t['test'], t['score']) for r in results for t in r['test_results']], columns=['prompt', 'response', 'test', 'score']).to_csv(f"unit_test_results.csv", index=False)
```

## 5. Visualize Individual Results

Visualizations are helpful for understanding unit test results. Create a visualization of individual response radar plots showing performance across all dimensions:

```python theme={null}
def map_test_to_category(test_question: str) -> str:
    """Map the full test question to its category."""
    category_mapping = {
        'Are relevant market conditions or external factors': 'CONTEXT',
        'Is complex financial information presented': 'CLARITY',
        'Is terminology used accurately': 'PRECISION',
        'Does the response adhere to relevant financial regulations': 'COMPLIANCE',
        'Does the response provide clear next steps': 'ACTIONABLE',
        'Are potential risks clearly identified': 'RISK'
    }

    for key, value in category_mapping.items():
        if key.lower() in test_question.lower():
            return value
    return None

def create_unit_test_plots(results: List[Dict],
                          test_indices: Optional[Union[int, List[int]]] = None,
                          figsize: tuple = (10, 10)):
    """
    Create polar plot(s) for unit test results. Can plot either a single test,
    specific multiple tests, or all tests in a row.

    Args:
        results: List of dictionaries containing test results
        test_indices: Optional; Either:
            - None (plots all results)
            - int (plots single result)
            - List[int] (plots multiple specific results)
        figsize: Tuple specifying the figure size (width, height)
    """
    # Handle different input cases for test_indices
    if test_indices is None:
        indices_to_plot = list(range(len(results)))
    elif isinstance(test_indices, int):
        if test_indices >= len(results):
            raise IndexError(f"test_index {test_indices} is out of range. Only {len(results)} results available.")
        indices_to_plot = [test_indices]
    else:
        if not test_indices:
            raise ValueError("test_indices list cannot be empty")
        if max(test_indices) >= len(results):
            raise IndexError(f"test_index {max(test_indices)} is out of range. Only {len(results)} results available.")
        indices_to_plot = test_indices

    # Categories in desired order
    categories = ['CONTEXT', 'CLARITY', 'PRECISION',
                 'COMPLIANCE', 'ACTIONABLE', 'RISK']

    # Set up the angles for the polar plot
    angles = np.linspace(0, 2*np.pi, len(categories), endpoint=False)
    angles = np.concatenate((angles, [angles[0]]))  # Close the plot

    # Calculate figure size based on number of plots
    num_plots = len(indices_to_plot)
    fig_width = figsize[0] * num_plots
    fig = plt.figure(figsize=(fig_width, figsize[1]))

    # Create a subplot for each result
    for plot_idx, result_idx in enumerate(indices_to_plot):
        result = results[result_idx]

        # Create subplot
        ax = plt.subplot(1, num_plots, plot_idx + 1, projection='polar')

        # Get scores for this result
        scores = []
        for category in categories:
            score = None
            for test_result in result['test_results']:
                mapped_category = map_test_to_category(test_result['test'])
                if mapped_category == category:
                    score = test_result['score']
                    break
            scores.append(score if score is not None else 0)

        # Close the scores array
        scores = np.concatenate((scores, [scores[0]]))

        # Plot the scores
        ax.plot(angles, scores, 'o-', linewidth=2)
        ax.fill(angles, scores, alpha=0.25)

        # Set the labels
        ax.set_xticks(angles[:-1])
        ax.set_xticklabels(categories)

        # Set the scale
        ax.set_ylim(0, 5)

        # Add grid
        ax.grid(True)

        # Add score values as annotations
        for angle, score, category in zip(angles[:-1], scores[:-1], categories):
            ax.text(angle, score + 0.2, f'{score:.2f}',
                    ha='center', va='bottom')

        # Add title for each subplot
        prompt = result['prompt']
        ax.set_title(f"Test {result_idx}\n{prompt}", pad=20)

    plt.tight_layout()
    return fig
```

Radar plots are a great way to visualize the different dimensions that the unit tests provide. Try changing the index to view other plots:

```python theme={null}
# Plot the second test result
fig = create_unit_test_plots(results, test_indices=0)
```

You want to compare multiple plots? Try this

```python theme={null}
fig = create_unit_test_plots(results, test_indices=[0, 1, 2,])
fig = create_unit_test_plots(results, test_indices=[3, 4, 5,])
fig = create_unit_test_plots(results, test_indices=[6, 7, 8,])
```

## 6. Visualize Group Results

For analyzing larger sets of results, it's useful to use clustering methods. Let's walk through using clustering to help analyze a dataset of 40 unit test results.

```python theme={null}
df = pd.read_csv(
    'data/synthetic_financial_responses.csv' if os.path.exists('data/synthetic_financial_responses.csv')
    else "https://raw.githubusercontent.com/ContextualAI/examples/refs/heads/main/03-lmunit/data/synthetic_financial_responses.csv"
)
df.head()
```

Start by using Kmeans and clustering this into four groups. For your analysis, you may need to use fewer or more clusters.

```python theme={null}
def cluster_responses(df: pd.DataFrame, n_clusters: int = 4) -> Tuple[pd.DataFrame, pd.DataFrame]:
    """
    Perform clustering on response evaluation data.

    Args:
        df: DataFrame containing evaluation scores
        n_clusters: Number of clusters to identify

    Returns:
        tuple: (DataFrame with cluster assignments, DataFrame of cluster centers)
    """
    categories = ['CONTEXT', 'CLARITY', 'PRECISION',
                 'COMPLIANCE', 'ACTIONABLE', 'RISK']
    # Prepare and perform clustering
    scaler = StandardScaler()
    X_scaled = scaler.fit_transform(df)

    kmeans = KMeans(n_clusters=n_clusters, random_state=42)
    df_clustered = df.copy()
    df_clustered['cluster'] = kmeans.fit_predict(X_scaled)

    # Calculate cluster centers
    cluster_centers = pd.DataFrame(
        scaler.inverse_transform(kmeans.cluster_centers_),
        columns=categories
    )
    return df_clustered, cluster_centers
```

Look at how each of our samples are now clustered:

```python theme={null}
df_clustered, centers = cluster_responses(df)
df_clustered.head()
```

You can visualize these cluster, both in terms of how the clusters centers vary as well as how the individuals points.

```python theme={null}

def visualize_clusters(df: pd.DataFrame, cluster_centers: pd.DataFrame):
    """
    Create visualizations for cluster analysis.

    Args:
        df: DataFrame with cluster assignments
        cluster_centers: DataFrame of cluster centers
    """
    # 1. Heatmap of cluster centers
    plt.figure(figsize=(12, 8))
    sns.heatmap(cluster_centers, annot=True, cmap='RdYlGn', fmt='.2f')
    plt.title('Response Pattern Cluster Centers')
    plt.ylabel('Cluster')
    plt.tight_layout()
    plt.show()

    # 2. Scatter plot of key dimensions
    plt.figure(figsize=(12, 8))
    scatter = plt.scatter(df['CONTEXT'], df['ACTIONABLE'],
                         c=df['cluster'], cmap='viridis')
    plt.xlabel('CONTEXT Score')
    plt.ylabel('ACTIONABLE Score')
    plt.title('Cluster Distribution (Context vs Actionable)')
    plt.colorbar(scatter, label='Cluster')
    plt.grid(True)
    plt.tight_layout()
    plt.show()

visualize_clusters(df_clustered, centers)
```

The following code helps analyze the clusters by the categories used for unit tests:

```python theme={null}

def explain_clusters(df: pd.DataFrame, cluster_centers: pd.DataFrame):
    """
    Provide detailed explanation of cluster characteristics.

    Args:
        df: DataFrame with cluster assignments
        cluster_centers: DataFrame of cluster centers
    """
    expected_categories = ['CONTEXT', 'CLARITY', 'PRECISION',
                         'COMPLIANCE', 'ACTIONABLE', 'RISK']

    print("\nCluster Analysis:")
    print("-----------------")

    # Print cluster centers
    print("\nCluster Centers:")
    print(cluster_centers.round(2))

    # Print cluster sizes
    print("\nCluster Sizes:")
    print(df['cluster'].value_counts().sort_index())

    # Analyze each cluster
    print("\nCluster Characteristics:")
    for i in range(len(cluster_centers)):
        cluster_df = df[df['cluster'] == i]
        print(f"\nCluster {i}:")

        # Calculate average scores
        avg_scores = cluster_df[expected_categories].mean()
        sorted_scores = avg_scores.sort_values(ascending=False)

        # Get top and bottom categories
        top_cats = list(sorted_scores.head(2).items())
        bottom_cats = list(sorted_scores.tail(2).items())

        # Print characteristics
        print(f"Size: {len(cluster_df)} responses")
        print(f"Strongest areas: {top_cats[0][0]} ({top_cats[0][1]:.2f}), "
              f"{top_cats[1][0]} ({top_cats[1][1]:.2f})")
        print(f"Weakest areas: {bottom_cats[0][0]} ({bottom_cats[0][1]:.2f}), "
              f"{bottom_cats[1][0]} ({bottom_cats[1][1]:.2f})")


explain_clusters(df_clustered, centers)
```

### Interpret the clusters

Now that you have a better understanding of the response clusters, you can identify the patterns and characteristics of each cluster. After looking at the clusters, these patterns should emerge:

**Cluster 0:** Compliance Blind Spot.
High CLARITY/PRECISION, Low COMPLIANCE/RISK
Clear communication but missing regulatory elements

**Cluster 1:** Clarity Gap.
High CONTEXT/RISK, Low CLARITY/PRECISION
High context awareness but poor explanation clarity

**Cluster 2:** Theory-Practice Gap.
High PRECISION/CLARITY, Low ACTIONABLE.
Strong theoretical understanding but impractical

**Cluster 3:** Surface Analysis
Medium CLARITY but Low CONTEXT/RISK
Basic understanding without depth

<Note>
  Your clusters may be less straightforward to interpret, so use the patterns that do emerge to guide error analysis and refinement.
</Note>

## Best Practices for Using LMUnit

### Unit Test Design:

* Keep tests focused and specific
* Avoid compound criteria
* Use clear, unambiguous language
* Assess a desirable quality, such as “Is the response coherent?” rather than “Is the response incoherent?”

### Evaluation Strategy:

* Start with global tests
* Add query-level tests as needed
* Monitor patterns across responses

### Score Interpretation:

* 5: Excellent - Fully satisfies criteria
* 4: Good - Minor issues
* 3: Acceptable - Some issues
* 2: Poor - Significant issues
* 1: Unacceptable - Fails criteria

<Note>
  You can provide a custom rubric for scoring.
</Note>

### Next Steps

* Customize unit tests for your use case
* Integrate with your evaluation pipeline
* Monitor and adjust based on results

## Additional Resources

* [LMUnit Blog Post](https://contextual.ai/blog/lmunit/)
* [API Reference](/api-reference/lmunit/lmunit)
* [Notebook](https://github.com/ContextualAI/examples/tree/main/01-getting-started)


# Contextual AI MCP Server
Source: https://docs.contextual.ai/how-to-guides/mcp-server-user-guide

How-to Guide

Contextual AI's Model Context Protocol (MCP) server provides RAG (Retrieval-Augmented Generation) capabilities that integrate with a variety of MCP clients. It provides flexibility in that you can decide what functionality to offer in the server.

<Note>
  Please visit the Contextual AI MCP Server [README](https://github.com/ContextualAI/contextual-mcp-server?tab=readme-ov-file) on GitHub for more information.
</Note>

Contextual AI now offers a hosted server inside the platform available at: [https://mcp.app.contextual.ai/mcp/](https://mcp.app.contextual.ai/mcp/)
After you connect to the server, you can use the tools, such as query, provided by the platform MCP server.
For a complete walkthrough, check out the [Contextual AI MCP Server Quick Start](/quickstarts/mcp-server)

***

## Overview

An MCP server acts as a bridge between AI interfaces (Cursor IDE or Claude Desktop) and a specialized Contextual AI agent. It enables:

Query Processing: Direct your domain specific questions to a dedicated Contextual AI agent
Intelligent Retrieval: Searches through comprehensive information in your knowledge base
Context-Aware Responses: Generates answers that are:
Grounded in source documentation
Include citations and attributions
Maintain conversation context

### Integration Flow

This guide walks through integration with both the Cursor IDE and Claude Desktop.

```
Cursor/Claude Desktop → MCP Server → Contextual AI RAG Agent
        ↑                  ↓             ↓                         
        └──────────────────┴─────────────┴─────────────── Response with citations
```

## Prerequisites

* Python 3.10 or higher
* Cursor IDE and/or Claude Desktop
* Contextual AI API key
* MCP-compatible environment

## Installation

Clone the repository:

```
git clone https://github.com/ContextualAI/contextual-mcp-server.git
cd contextual-mcp-server
```

Create and activate a virtual environment:

```
python -m venv .venv
source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
```

Install dependencies:

```
pip install -e .
```

## Configuration

### Configure MCP Server

The server requires modifications of settings or use. For example, the single\_agent server should be customized with an appropriate docstring for your RAG Agent.

The docstring for your query tool is critical as it helps the MCP client understand when to route questions to your RAG agent. Make it specific to your knowledge domain. Here is an example:

A research tool focused on financial data on the largest US firms
or

A research tool focused on technical documents for Omaha semiconductors
The server also requires the following settings from your RAG Agent:

API\_KEY: Your Contextual AI API key
AGENT\_ID: Your Contextual AI agent ID
If you'd like to store these files in .env file you can specify them like so:

```
cat > .env << EOF
API_KEY=key...
AGENT_ID=...
EOF
```

The repo also contains more advance MPC servers for multi-agent systems or a document-agent.

AI Interface Integration
This MCP server can be integrated with a variety of clients. To use with either Cursor IDE or Claude Desktop create or modify the MCP configuration file in the appropriate location:

First, find the path to your uv installation:

```
UV_PATH=$(which uv)
echo $UV_PATH
# Example output: /Users/username/miniconda3/bin/uv
Create the configuration file using the full path from step 1:
cat > mcp.json << EOF
{
 "mcpServers": {
   "ContextualAI-TechDocs": {
     "command": "$UV_PATH", # make sure this is set properly
     "args": [
       "--directory",
       "\${workspaceFolder}",  # Will be replaced with your project path
       "run",
       "multi-agent/server.py"
     ]
   }
 }
}
EOF
```

Move to the correct folder location, see below for options:

```
mkdir -p .cursor/
mv mcp.json .cursor/
```

Configuration locations:

For Cursor:
Project-specific: `.cursor/mcp.json` in your project directory
Global: `~/.cursor/mcp.json` for system-wide access
For Claude Desktop:
Use the same configuration file format in the appropriate Claude Desktop configuration directory
Environment Setup
This project uses uv for dependency management, which provides faster and more reliable Python package installation.

Usage
The server provides Contextual AI RAG capabilities using the python SDK, which can available a variety of commands accessible from MCP clients, such as Cursor IDE and Claude Desktop. The current server focuses on using the query command from the Contextual AI python SDK, however you could extend this to support other features such as listing all the agents, updating retrieval settings, updating prompts, extracting retrievals, or downloading metrics.

Example Usage

# In Cursor, you might ask:

"Show me the code for initiating the RF345 microchip?"

# The MCP client will:

1. Determine if this should be routed to the MCP Server

# Then the MCP server will:

1. Route the query to the Contextual AI agent
2. Retrieve relevant documentation
3. Generate a response with specific citations
4. Return the formatted answer to Cursor
   Key Benefits
   Accurate Responses: All answers are grounded in your documentation
   Source Attribution: Every response includes references to source documents
   Context Awareness: The system maintains conversation context for follow-up questions
   Real-time Updates: Responses reflect the latest documentation in your datastore
   Development
   Modifying the Server
   To add new capabilities:

Add new tools by creating additional functions decorated with @mcp.tool()
Define the tool's parameters using Python type hints
Provide a clear docstring describing the tool's functionality

Example:

```
@mcp.tool()
def new_tool(param: str) -> str:
   """Description of what the tool does"""
   # Implementation
   return result
```

## Limitations

* The server runs locally and may not work in remote development environments
* Tool responses are subject to Contextual AI API limits and quotas
* Currently only supports stdio transport mode

For all the capabilities of Contextual AI, please see the MCP Server Quickstart Guide.


# Parse
Source: https://docs.contextual.ai/how-to-guides/parse

Contextual AI How-to Guide

## Overview

This guide demonstrates how to use `/parse` with the **Contextual AI API** directly and via our **Python SDK**. It uses the same document — *[Attention Is All You Need](https://arxiv.org/pdf/1706.03762)* — for both examples.

***

## 0. Fetch the Document & Set API Key

First, we'll fetch the document that we'll use throughout the notebook.

```
url = "https://arxiv.org/pdf/1706.03762"

import requests

# Download doc
file_path = "attention-is-all-you-need.pdf"
with open(file_path, "wb") as f:
    f.write(requests.get(url).content)
```

### API Key

Grab your API Key from the Contextual console and set it on the left in the **Secrets** pane as `CONTEXTUAL_API_KEY`.

```
# Set the API key in the pane of google colab
from google.colab import userdata
api_key = userdata.get('CONTEXTUAL_API_KEY')
```

## 1. REST API implementation

You can use our API directly with the requests package. See docs.contextual.ai for details.

```
import requests
import json

base_url = "https://api.contextual.ai/v1"

headers = {
    "accept": "application/json",
    "authorization": f"Bearer {api_key}"
}
```

### 1.1 Submit Parse Job

Next, we'll define the configuration for our parse job and submit it. This initiates an async parse job and returns a job\_id we can use to monitor progress.

```
url = f"{base_url}/parse"

config = {
    "parse_mode": "standard",
    "figure_caption_mode": "concise",
    "enable_document_hierarchy": True,
    "page_range": "0-5",
}

with open(file_path, "rb") as fp:
    file = {"raw_file": fp}
    result = requests.post(url, headers=headers, data=config, files=file)
    response = json.loads(result.text)

job_id = response['job_id']
job_id
```

### 1.2 Monitor Job Status

Using the `job_id` from above, we can monitor the status of our parse job.

```
# Check on parse job status
from time import sleep

url = f"{base_url}/parse/jobs/{job_id}/status"

while True:
    result = requests.get(url, headers=headers)
    parse_response = json.loads(result.text)['status']
    print(f"Job is {parse_response}")
    if parse_response == "completed":
        break
    sleep(30)
```

### 1.3 List all jobs

If we submit multiple jobs and want to see the status of each of them, then we can use the list jobs api:

```
url = f"{base_url}/parse/jobs"

result = requests.get(url, headers=headers)
parse_response = json.loads(result.text)
parse_response
```

### 1.4 Get Parse results

```
url = f"{base_url}/parse/jobs/{job_id}/results"

output_types = ["markdown-per-page"]

result = requests.get(
    url,
    headers=headers,
    params={"output_types": ",".join(output_types)},
)

result = json.loads(result.text)
```

### 1.5 Display 1st Page

```
from IPython.display import display, Markdown

display(Markdown(result['pages'][0]['markdown']))
```

## 2. Contextual SDK

```
try:
  from contextual import ContextualAI
except:
  %pip install --upgrade --quiet contextual-client
  from contextual import ContextualAI

# Setup Contextual Python SDK
client = ContextualAI(api_key=api_key)
```

### 2.1 Submit Parse Job

```
with open(file_path, "rb") as fp:
    response = client.parse.create(
        raw_file=fp,
        parse_mode="standard",
        figure_caption_mode="concise",
        enable_document_hierarchy=True,
        page_range="0-5",
    )

job_id = response.job_id
job_id
```

### 2.2 Monitor Job Status

```
# Check on parse job status
from time import sleep


while True:
    result = client.parse.job_status(job_id)
    parse_response = result.status
    print(f"Job is {parse_response}")
    if parse_response == "completed":
        break
    sleep(30)
```

### 2.3 List all jobs

```
client.parse.jobs()
```

### 2.4 Get Job Results

```
results = client.parse.job_results(job_id, output_types=['markdown-per-page'])
```

### 2.5 Display 1st Page

```
from IPython.display import display, Markdown

display(Markdown(results.pages[0].markdown))
```

## 3. Parse UI

To see job results in an interactive manner and submit new jobs, navigate to the UI using the following link by running the cell below.

<Note>
  You'll need to change your-tenant-name to your tenant.
</Note>

```
tenant = "your-tenant-name"
print(f"https://app.contextual.ai/{tenant}/components/parse?job={job_id}")
```

<img alt="" />

## 4. Output Types

You can set the desired output format(s) of the parsed file using the `output_types` parameter. Valid values are:

* `markdown-document`
* `markdown-per-page`
* `blocks-per-page`

Specify multiple values to receive multiple formats in the response.

**Format descriptions:**

* **`markdown-document`** parses the entire document into one concatenated markdown output.
* **`markdown-per-page`** provides markdown output per page.
* **`blocks-per-page`** provides a structured JSON representation of content blocks on each page, sorted by reading order.

### 4.1 Display Markdown-per-page

```python theme={null}
results = client.parse.job_results(job_id, output_types=['markdown-per-page'])

for page in results.pages:
    display(Markdown(page.markdown))
```

### 4.2 Blocks per page

```python theme={null}
results = client.parse.job_results(job_id, output_types=['blocks-per-page'])

for page in results.pages:
    for block in page.blocks:
        display(Markdown(block.markdown))
```

### 4.3 Markdown-document

This returns the document text into a single field markdown\_document.

```python theme={null}
result = client.parse.job_results(job_id, output_types=['markdown-document'])

display(Markdown(result.markdown_document))
```

## 5. Hierarchy Metadata

### 5.1 Display hierarchy

To easily inspect the document hierarchy, rendered as a markdown table of contents you can run:

```python theme={null}
from IPython.display import display, Markdown

display(Markdown(results.document_metadata.hierarchy.table_of_contents))
```

### 5.2 Add hierarchy context

LLMs work best when they're provided with structured information about the document's hierarchy and organization. That's why we've written the parse api to be context aware, i.e. we can include metadata such as which section the text is from.

To do this we'll set output\_type to blocks-per-page and use the parameter parent\_ids to get the corresponding section headings. The parent\_ids are sorted from root-level to bottom in case of nested sections.

```python theme={null}
results = client.parse.job_results(job_id, output_types=['blocks-per-page'])

hash_table = {}

for page in results.pages:
  for block in page.blocks:
    hash_table[block.id] = block.markdown

page = results.pages[3]  # example
for block in page.blocks:
  if block.parent_ids:
    parent_content = "\n".join([hash_table[parent_id] for parent_id in block.parent_ids])
    print(f"Metadata:\n------\n{parent_content} \n\n  Text\n------\n {block.markdown}\n\n")
```

## 6. Table Extraction

If we're interested in extracting large tables, sometimes we need to split up those tables to use them in the LLM but preserve table header information across each chunk. To do that we'll use the enable\_split\_tables and max\_split\_table\_cells parameters like so:

We're using a document with a large table. You can take a look at the [original doc here](https://github.com/ContextualAI/examples/blob/main/03-standalone-api/04-parse/data/omnidocbench-text.pdf).

<img alt="image" />

```python theme={null}
url = 'https://raw.githubusercontent.com/ContextualAI/examples/refs/heads/main/03-standalone-api/04-parse/data/omnidocbench-text.pdf'

# Download doc
file_path = "omnidocbench-text_pdf.pdf"
with open(file_path, "wb") as f:
    f.write(requests.get(url).content)
```

```python theme={null}
file_path = 'omnidocbench-text_pdf.pdf'
with open(file_path, "rb") as fp:
    response = client.parse.create(
        raw_file=fp,
        parse_mode="standard",
        enable_split_tables=True,
        max_split_table_cells=100,
    )

job_id = response.job_id
job_id
```

```python theme={null}
# Check on parse job status
while True:
    result = client.parse.job_status(job_id)
    parse_response = result.status
    print(f"Job is {parse_response}")
    if parse_response == "completed":
        break
    sleep(30)
```

```python theme={null}
result = client.parse.job_results(job_id, output_types=['markdown-per-page'])

for page in result.pages:
  display(Markdown(page.markdown))
```


# Rerank
Source: https://docs.contextual.ai/how-to-guides/rerank

Contextual AI How-to Guide

## Overview

Contextual AI's reranker is the first with instruction-following capabilities to handle conflicts in retrieval. It is the most accurate reranker in the world per industry-leading benchmarks like BEIR. To learn more about the reranker and its importance in RAG pipelines, please see our blog.

This how-to guide uses the same example to demonstrate how to use the reranker with the Contextual API directly, our Python SDK, and our Langchain package.

The current reranker models include:

* ctxl-rerank-v2-instruct-multilingual
* ctxl-rerank-v2-instruct-multilingual-mini
* ctxl-rerank-v1-instruct

## Global Variables & Examples

First, we will set up the global variables and examples we'll use with each different implementation method.

```python theme={null}
from google.colab import userdata

api_key = userdata.get("API_TOKEN")
base_url = "https://api.contextual.ai/v1"
rerank_api_endpoint = f"{base_url}/rerank"
```

```python theme={null}
query = "What is the current enterprise pricing for the RTX 5090 GPU for bulk orders?"

instruction = "Prioritize internal sales documents over market analysis reports. More recent documents should be weighted higher. Enterprise portal content supersedes distributor communications."

documents = [
    "Following detailed cost analysis and market research, we have implemented the following changes: AI training clusters will see a 15% uplift in raw compute performance, enterprise support packages are being restructured, and bulk procurement programs (100+ units) for the RTX 5090 Enterprise series will operate on a $2,899 baseline.",
    "Enterprise pricing for the RTX 5090 GPU bulk orders (100+ units) is currently set at $3,100-$3,300 per unit. This pricing for RTX 5090 enterprise bulk orders has been confirmed across all major distribution channels.",
    "RTX 5090 Enterprise GPU requires 450W TDP and 20% cooling overhead."
]

metadata = [
    "Date: January 15, 2025. Source: NVIDIA Enterprise Sales Portal. Classification: Internal Use Only",
    "TechAnalytics Research Group. 11/30/2023.",
    "January 25, 2025; NVIDIA Enterprise Sales Portal; Internal Use Only"
]

model = "ctxl-rerank-v2-instruct-multilingual"
```

## REST API implementation

```python theme={null}
import requests

headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": f"Bearer {api_key}"
}
```

```python theme={null}
payload = {
    "query": query,
    "instruction": instruction,
    "documents": documents,
    "metadata": metadata,
    "model": model
}

rerank_response = requests.post(rerank_api_endpoint, json=payload, headers=headers)

print(rerank_response.json())
```

## Python SDK

```python theme={null}
try:
  from contextual import ContextualAI
except:
  %pip install contextual-client
  from contextual import ContextualAI

client = ContextualAI (api_key = api_key, base_url = base_url)
```

```python theme={null}
rerank_response = client.rerank.create(
    query = query,
    instruction = instruction,
    documents = documents,
    metadata = metadata,
    model = model
)

print(rerank_response.to_dict())
```

## Langchain

```python theme={null}
try:
  from langchain_contextual import ContextualRerank
except:
  %pip install langchain-contextual
  from langchain_contextual import ContextualRerank

from langchain_core.documents import Document
```

```python theme={null}
# intialize Contextual reranker via langchain_contextual
compressor = ContextualRerank(
    model=model,
    api_key=api_key,
)

# Prepare metadata in dictionary format for Langchain Document class
metadata_dict = [
    {
        "Date": "January 15, 2025",
        "Source": "NVIDIA Enterprise Sales Portal",
        "Classification": "Internal Use Only"
    },
    {
        "Date": "11/30/2023",
        "Source": "TechAnalytics Research Group"
    },
    {
        "Date": "January 25, 2025",
        "Source": "NVIDIA Enterprise Sales Portal",
        "Classification": "Internal Use Only"
    }
]


# prepare documents as langchain Document objects
# metadata stored in document objects will be extracted and used for reranking
langchain_documents = [
    Document(page_content=content, metadata=metadata_dict[i])
    for i, content in enumerate(documents)
]

# print to validate langchain document
print(langchain_documents[0])
```

```python theme={null}
# use compressor.compress_documents to rerank the documents
reranked_documents = compressor.compress_documents(
    query=query,
    instruction=instruction,
    documents=langchain_documents,
)
print(reranked_documents)
```

## Additional Resources

* [Read the blog post](https://contextual.ai/blog/introducing-instruction-following-reranker) to learn more about the Contextual AI Reranker
* [Access the related notebook](https://github.com/ContextualAI/examples/blob/main/03-standalone-api/03-rerank/rerank.ipynb) that demonstrates how to use the reranker with the Contextual API directly, our Python SDK, and our Langchain package
* [API Reference](/api-reference/rerank/rerank)
* [Python SDK](https://github.com/ContextualAI/contextual-client-python/blob/main/api.md#rerank)
* [Langchain Package](https://pypi.org/project/langchain-contextual/)


# Structured Outputs
Source: https://docs.contextual.ai/how-to-guides/structured-outputs

Contextual AI How-to Guide

Contextual AI supports structured outputs in JSON format. Use structured output mode when responses must follow a consistent, easily parsed format—for example, to extract defined data fields or integrate with downstream applications and workflows.

<Info>
  This feature is currently in beta, with attributions and other capabilities planned for future release.
</Info>

To use structured outputs:

1. Define your schema, which must be valid JSON and include the `json_schema` key.
   <CodeGroup>
     ```python Python theme={null}
     # define schema
     schema = {
      "json_schema": {
             "type": "object",
             "properties": {
                 "regions": {
                     "type": "array",
                     "items": {
                         "type": "object",
                         "properties": {
                             "region": {"type": "string"},
                             "revenue": {"type": "number"},
                             "share_of_revenue": {"type": "number"}
                         },
                         "required": ["region", "revenue", "share_of_revenue"]
                     }
                 }
             },
             "required": ["regions"]
         }
     }
     ```
   </CodeGroup>
2. Pass the schema as part of your `/query` request.

<Note>
  [Contextual AI Python SDK](https://github.com/ContextualAI/contextual-client-python) users must include the schema under the `structured_output` key in the `extra_body` parameter.
</Note>

<CodeGroup>
  ```python Python SDK theme={null}
  from contextual import ContextualAI
  # initialize your client
  client = ContextualAI(
      api_key=os.environ.get("CONTEXTUAL_API_KEY"),
  )
  # define your schema and add it to the payload object under the
  # structured_output key
  payload = {
      "structured_output": schema
  }
  # pass the payload in the "extra_body" field, along with your other
  # query parameters
  response = client.agents.query.create(
  	# replace with your agent's id
  	agent_id="",
  	# replace with your query
  	messages=[{"content": "what was the regional revenue breakdown in 2022", "role": "user"}],
  	# pass the schema in the `extra_body` param
  	extra_body=payload
  )
  ```
</CodeGroup>

3. Parse the returned message as JSON-formatted data:
   <CodeGroup>
     ```python Python theme={null}
     import json
     results = json.loads(response.message.content)
     ```
   </CodeGroup>

The resulting structured output can then be used for a variety of downstream applications:

```json theme={null}
{'regions': [{'region': 'Americas',
   'revenue': 28079,
   'share_of_revenue': 44.0},
  {'region': 'Europe, Middle East & Africa',
   'revenue': 25301,
   'share_of_revenue': 39.5},
  {'region': 'Asia & Pacific', 'revenue': 10486, 'share_of_revenue': 16.4}]}
```


# Home
Source: https://docs.contextual.ai/index

Welcome to Contextual AI Docs

<div>
  <h1>
    Welcome to Contextual AI Docs
  </h1>

  <h2 />

  <hr />

  <p>
    © 2026 Contextual AI.
  </p>
</div>


# Databases
Source: https://docs.contextual.ai/integration/databases

Connecting your private data and third-party data sources

Bring together your AI models, workflows, tools, and data with ease. Contextual AI's integrations empower your RAG agents to operate smarter and share knowledge seamlessly across popular AI solutions.

## Available Integrations

***

### Chroma

Chroma is an open-source vector database tailored to applications with large language models.

* [Contextual AI on the Chroma Docs Integration Page](https://docs.trychroma.com/integrations/frameworks/contextual-ai)
* [Multimodal RAG with Chroma and Contextual AI Parser](https://github.com/ContextualAI/examples/blob/main/18-contextualai-chroma/01-contextual-ai-parser-chroma.ipynb)
* [Using the Contextual AI Reranker with Chroma](https://github.com/ContextualAI/examples/blob/main/18-contextualai-chroma/02-contextual-ai-reranker-chroma.ipynb)
* [Natural Language Unit Testing for RAG Systems with Chroma and LMUnit](https://github.com/ContextualAI/examples/blob/main/18-contextualai-chroma/03-contextual-ai-lmunit-chroma.ipynb)
* [Chroma on GitHub](https://github.com/chroma-core/chroma)

***

### Elastic

Elastic is a distributed vector database and search engine built on top of Apache Lucene

* [Creating a Contextual AI Endpoint in Elastic](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-inference-put-contextualai)
* [Elastic and Contextual AI Partnership Announcement](https://www.elastic.co/blog/elastic-contextual-ai-partnership)
* [Elastic on GitHub](https://github.com/elastic/)

***

### Snowflake

Snowflake is a leading cloud-native data platform consisting of a data warehouse, data lake, and suite of data services available as a SaaS.

* [Contextual AI How-to Guide: Snowflake Native App](/how-to-guides/snowflake)
* [Example Script: Contextual AI Python SDK & Snowflake Native App](https://github.com/ContextualAI/contextual-client-python/blob/main/examples/snowflake_native_app_example.py)
* [Snowflake and Contextual AI Native App Announcement](https://contextual.ai/blog/snowflake-marketplace)
* [Press Release: Snowflake + Contextual AI](https://contextual.ai/blog/contextual-ai-launches-enterprise-platform-as-snowflake-native-app-on-snowflake-marketplace)
* [Contextual AI in the Snowflake Marketplace](https://app.snowflake.com/marketplace/listing/GZTYZUILS2N/contextual-ai-contextual-ai-platform)
* [Snowflake Labs on GitHub](https://github.com/snowflake-labs)

***

### Weaviate

Weaviate is a vector database that supports object and vector storage, hybrid search, and highly selective filters.

#### Recipes

* [Contextual AI Parser + Weaviate Integration](https://github.com/weaviate/recipes/tree/8c025ae634e3aaef42786c031912f97b0b8df906/integrations/data-platforms/contextual-ai):
  Use Contextual AI’s Parser with Weaviate to build a RAG application over PDF documents.
* [Generative Search with Contextual AI](https://github.com/weaviate/recipes/blob/main/weaviate-features/model-providers/contextual/rag_contextual_v2.ipynb):
  Use Contextual AI’s generative model (`v2`) with Weaviate for RAG.
* [Reranking with Contextual AI](https://github.com/weaviate/recipes/blob/main/weaviate-features/reranking/contextual-reranking/rerank_contextual.ipynb):
  Use Contextual AI’s reranking model (`ctxl-rerank-v2-instruct-multilingual`) with Weaviate to improve search result quality.

#### Weaviate Docs on GitHub

* [Contextual AI + Weaviate Integrations](https://github.com/weaviate/docs/blob/abe97b07b950e2316f4d8702129d6b914ae1c0d7/docs/weaviate/model-providers/contextualai/index.md)
* [Contextual AI Generative AI with Weaviate](https://github.com/weaviate/docs/blob/abe97b07b950e2316f4d8702129d6b914ae1c0d7/docs/weaviate/model-providers/contextualai/generative.md)
* [Contextual AI Reranker Models with Weaviate](https://github.com/weaviate/docs/blob/abe97b07b950e2316f4d8702129d6b914ae1c0d7/docs/weaviate/model-providers/contextualai/reranker.md)

#### Weaviate.io Docs

* [Contextual AI Generative AI with Weaviate](https://docs.weaviate.io/weaviate/model-providers/contextualai/generative)
* [Contextual AI in Weaviate Docs](https://docs.weaviate.io/integrations/data-platforms/contextual-ai)
* [Model Integrations: Contextual AI + Weaviate](https://docs.weaviate.io/weaviate/model-providers/contextualai)
* [Weaviate on GitHub](https://github.com/weaviate/weaviate)


# Frameworks
Source: https://docs.contextual.ai/integration/frameworks

Integrations with leading AI/ML frameworks

Bring together your AI models, workflows, tools, and data with ease. Contextual AI's integrations empower your RAG agents to operate smarter and share knowledge seamlessly across popular AI solutions.

## Available Integrations

***

### CrewAI

CrewAI is an open source orchestration framework for building and deploying automated multi-agent workflows.

* [Contextual AI in the CrewAI Ecosystem](https://www.crewai.com/ecosystem)
* [CrewAI on GitHub](https://github.com/crewAIInc/crewAI)

***

### n8n

n8n is an no-code, open-source workflow automation platform that combines AI capabilities with business process automation.

* [n8n Integrations Page](https://n8n.io/integrations/contextual-ai/)
* [npm Package: Contextual AI n8n Community Node](https://www.npmjs.com/package/n8n-nodes-contextualai)
* [Contextual AI n8n How-to Guide](/how-to-guides/n8n)
* [n8n on GitHub](https://github.com/n8n-io/n8n)

***

### Ragas

Ragas is an open-source framework for testing and evaluating LLM applications and retrieval-augmented generation (RAG) AI systems.

* [Notebook: Using Ragas to Evaluate Contextual AI RAG Agents](https://github.com/ContextualAI/examples/blob/main/07-evaluation-ragas/Using_RAGAS.ipynb)
* [Ragas on GitHub](https://github.com/explodinggradients/ragas)


# Hugging Face
Source: https://docs.contextual.ai/integration/hugging-face





# Integrations Ecosystem
Source: https://docs.contextual.ai/integration/overview

Explore Contextual AI's integrations catalog

Bring together your AI models, workflows, tools, and data with ease. Contextual AI's integrations empower your RAG agents to operate smarter and share knowledge seamlessly across popular AI solutions.

## Available Integrations


# Platforms
Source: https://docs.contextual.ai/integration/platforms

Integrations with leading AI/ML and data platforms

Bring together your AI models, workflows, tools, and data with ease. Contextual AI's integrations empower your RAG agents to operate smarter and share knowledge seamlessly across popular AI solutions.

## Available Integrations

***

### Google Model Garden

Google Model Garden is a platform that helps you discover, test, customize, and deploy Google proprietary and select OSS models and assets.

* [Contextual AI Reranker in Google Model Garden](https://console.cloud.google.com/vertex-ai/publishers/contextualai/model-garden/rerank-v2-instruct)
* [Contextual AI in the Google Marketplace](https://console.cloud.google.com/marketplace/product/contextualai-public/contextual-ai-saas)

***

### n8n

n8n is an no-code, open-source workflow automation platform that combines AI capabilities with business process automation.

<Note>
  The Contextual AI n8n integration is currently available on a **preview** basis.
</Note>

* [npm Package: Contextual AI n8n Community Node](https://www.npmjs.com/package/n8n-nodes-contextualai)
* [Contextual AI n8n How-to Guide](/how-to-guides/n8n)

***

### Snowflake

Snowflake is a leading cloud-native data platform consisting of a data warehouse, data lake, and suite of data services available as a SaaS.

* [Example Script: Contextual AI Python SDK & Snowflake Native App](https://github.com/ContextualAI/contextual-client-python/blob/main/examples/snowflake_native_app_example.py)
* [Snowflake and Contextual AI Native App Announcement](https://contextual.ai/blog/snowflake-marketplace)
* [Press Release: Snowflake + Contextual AI](https://contextual.ai/blog/contextual-ai-launches-enterprise-platform-as-snowflake-native-app-on-snowflake-marketplace)
* [Contextual AI in the Snowflake Marketplace](https://app.snowflake.com/marketplace/listing/GZTYZUILS2N/contextual-ai-contextual-ai-platform)
* [Snowflake Labs on GitHub](https://github.com/snowflake-labs)


# Tooling
Source: https://docs.contextual.ai/integration/tooling

Integrations with popular tools

Bring together your AI models, workflows, tools, and data with ease. Contextual AI's integrations empower your RAG agents to operate smarter and share knowledge seamlessly across popular AI solutions.

## Available Integrations

***

### CrewAI

CrewAI is an open source orchestration framework for building and deploying automated multi-agent workflows.

* [Contextual AI in the CrewAI Ecosystem](https://www.crewai.com/ecosystem)
* [CrewAI on GitHub](https://github.com/crewAIInc/crewAI)

***

### n8n

n8n is an no-code, open-source workflow automation platform that combines AI capabilities with business process automation.

<Note>
  The Contextual AI n8n integration is currently available on a **preview** basis.
</Note>

* [npm Package: Contextual AI n8n Community Node](https://www.npmjs.com/package/n8n-nodes-contextualai)
* [Contextual AI n8n How-to Guide](/how-to-guides/n8n)
* [n8n on GitHub](https://github.com/n8n-io/n8n)

***

### Ragas

Ragas is an open-source framework for testing and evaluating LLM applications and retrieval-augmented generation (RAG) AI systems.

* [Notebook: Using Ragas to Evaluate Contextual AI RAG Agents](https://github.com/ContextualAI/examples/blob/main/07-evaluation-ragas/Using_RAGAS.ipynb)
* [Ragas on GitHub](https://github.com/explodinggradients/ragas)


# Agent Composer
Source: https://docs.contextual.ai/quickstarts/agent-composer

Quickstart Guide

<Note>
  **Template agents (Basic Search and Agentic Search) are available for self-serve users.** Full Agent Composer capabilities, including building custom workflows with prompts and full config customization via either the visual GUI builder or YAML are available in public preview for enterprise users. For more information or to request access, please contact your Contextual AI representative.
</Note>

## Overview

Contextual AI’s Agent Composer is a framework that enables platform users to build customized query workflows by assembling pre-made components such as search tools, third-party API/MCP integrations, and various LLMs.

By combining these primitives into arbitrary computational graphs, users can design specialized agents tailored to their needs.

### Why Agent Composer?

Engineering teams across semiconductor, manufacturing, energy, and other highly technical industries spend significant time on complex and repetitive work—analyzing device logs, planning production, resolving customer engineering tickets, and more. These tasks demand deep domain expertise, yet occur often enough that the right automation can deliver transformative results.

Until now, AI hasn’t delivered on that promise. Generic AI tools struggle with specialized technical content and often hallucinate. Custom-built solutions take months to deploy and quickly break as underlying data evolves. Agent frameworks provide building blocks, but leave teams to stitch together fragile, production-grade systems on their own.

**What’s been missing is context:** a reliable way for AI to access and reason over the technical documentation, specifications, and institutional knowledge engineers rely on every day.

Agent Composer is Contextual AI’s answer: the infrastructure and orchestration layer that manages context, enforces guardrails, and maintains accuracy throughout multi-step engineering workflows.

### What Makes Agent Composer Unique

Unlike simple workflow tools, Agent Composer supports **hybrid agentic behavior**:

* **Static Workflows:** Defined steps, loops, and branches where you control the recipe
* **Agentic Research Steps:** LLM-powered research agents that operate within a structured agent loop, using explicitly defined tools and constraints to plan, retrieve information, and determine the best approach for answering a query.

This gives enterprises the best of both worlds: intelligence where you need flexibility, and control where you need predictability.

### Real World Results

Agent Composer is in public preview, early customers are seeing dramatic improvements:

| Industry       | Task                                  | Before   | With Agent Composer |
| :------------- | :------------------------------------ | :------- | :------------------ |
| Semiconductors | Customer engineering issue resolution | 8 hours  | 10 minutes          |
| Electronics    | Device log analysis                   | 10 hours | 20 minutes          |
| Logistics      | Technical docs Q\&A                   | 5 hours  | 5 minutes           |
| Manufacturing  | Production planning                   | 10 hours | 5 minutes           |

***

## Agent Composer Workflows

You can create Agent Composer workflows in three ways: using natural language with the Prompt Builder, building visually with the GUI, or editing YAML directly.

### [Prompt Builder](/quickstarts/prompt-builder)

Describe what you want your agent to do in plain language, and the Prompt Builder generates the workflow configuration automatically. This is the fastest way to create a new agent.

* [Prompt Builder Quickstart](/quickstarts/prompt-builder)

### [Agent Composer GUI](/how-to-guides/agent-composer-gui)

The Agent Composer GUI offers a visual workflow builder that lets users design workflows graphically, which are then automatically translated into the corresponding YAML.

* [Agent Composer GUI How-to Guide](/how-to-guides/agent-composer-gui)

### [Agent Composer YAML](/how-to-guides/agent-composer-yaml)

Users can create Agent Composer workflows programmatically by providing a YAML file that defines the workflow graph and its configuration. This file outlines the required syntax, framework rules, and expected behaviors.

The YAML can be entered directly into the text field under the **Advanced Context** tab when creating an agent.

* [Agent Composer YAML How-to Guide](/how-to-guides/agent-composer-yaml)
* [Reference Catalog](/how-to-guides/ac-yaml-reference)
* [Cheatsheet](/how-to-guides/ac-yaml-cheatsheet)

### Tools Included

The following tools can be added to your workflows to help your agents carry out a variety of tasks and functions.

* **Retrieval tools:** Search vector databases, structured data sources, MCP servers, enterprise applications, and any external API read call
* **Ingestion tools:** [Parse](/connectors/overview), extraction, ingestion, [enterprise data connections](/connectors/overview)
* **Action tools:** Connect to business applications, webhooks
* **Planning Tools:** [Query reformulation](/reference/enable-query-expansion), decomposition
* **Evaluation Tools:** [LMUnit](/quickstarts/lmunit), groundedness checks
* **Memory Tools:** Chat history, multi-turn manager, and more to come

***

## Additional Resources

The following resources will help you get up to speed with Agent Composer and make the most of it as you build your workflows.

### Blog Post

Read the launch announcement to learn more about the vision and capabilities:

* [Introducing Agent Composer—AI for when it IS rocket science](https://contextual.ai/blog/introducing-agent-composer)

### Examples

See Agent Composer in action to get a clearer view of how it works.

* [Rocket Science Demo](/examples/rocket_science)
* [Test Program Generation](/examples/test-automation)


# Generate
Source: https://docs.contextual.ai/quickstarts/generate

Contextual AI Component Quickstart

## Overview

By accessing Contextual AI's Generate API component, you can generate responses using Contextual AI's Grounded Language Model (GLM), an LLM engineered specifically to prioritize faithfulness to in-context retrievals over parametric knowledge to reduce hallucinations in retrieval-augmented generation (RAG) and agentic use cases.

## Key Features

* State-of-the-art groundedness with top performance on FACTS and real enterprise benchmarks.
* Hallucination-resistant generation that prioritizes retrieved knowledge over training data.
* Inline source attributions for transparent, traceable responses.
* Reliable multi-turn reasoning that maintains grounding in long or complex workflows.
* RAG-optimized design built specifically for retrieval and agentic applications.
* Configurable groundedness via the avoid\_commentary flag.
* Easy integration through `/generate`, Python SDK, and LangChain examples.
* Enhanced performance when used with the Contextual AI Platform’s unified RAG stack.

## Getting Started

See the [Generate How-to guide](/how-to-guides/generate) for a detailed walkthrough on how to use the Generate API.

## Additional Resources

* [Contextual AI Grounded Language Model (GLM) Blog Post](https://contextual.ai/blog/introducing-grounded-language-model)
* [FACTS Benchmark for Evaluating Grounding in LLMs](https://github.com/ContextualAI/examples/blob/main/10-FACTS-benchmark)
* [Notebook and Examples](https://github.com/ContextualAI/examples/blob/main/03-standalone-api/02-generate/generate.ipynb)


# Getting Started
Source: https://docs.contextual.ai/quickstarts/getting-started

Everything you need to get up and running with Contextual AI

[Contextual AI](https://contextual.ai/) is the context layer for technical industries. We help R\&D teams and domain experts tackle complex knowledge work—device log analysis, root cause investigation, technical support, production planning—by giving AI access to the documentation, specifications, and institutional knowledge they rely on every day.

<Note>We never train on your data, and any agents you build on the platform remain entirely your intellectual property.</Note>

***

## How It Works

Getting started takes just three steps:

1. **Build an agent** — Start with Basic Search or Agentic Search templates (self-serve), or use Agent Composer's visual builder to create custom workflows (enterprise).
2. **Connect your documents** — Connect via connectors, or upload PDFs, specs, manuals, logs. Our parsing handles tables, figures, and complex layouts.
3. **Query and iterate** — Ask questions, get grounded answers with citations, and refine your agent as needed.

You can have your first agent running in minutes—no code required.

<img alt="The Contextual AI platform: from data sources through ingestion, retrieval, and generation to outputs" />

***

## Sign Up and Log In

Once you've signed up, [log in to the platform](https://app.contextual.ai) to create your first datastore and agent.

***

## What's Available

<Tabs>
  <Tab title="Self-Serve">
    All self-serve accounts include:

    * **Basic Search** template — Single-turn Q\&A with document retrieval and citations
    * **Agentic Search** template — Multi-step reasoning with iterative retrieval
    * Document upload, datastore management, and connectors
    * API access via Python SDK
    * Usage-based pricing with free credits to start
  </Tab>

  <Tab title="Enterprise">
    Enterprise plans add:

    * Advanced agent templates (Root Cause Analysis, Deep Research, Task Execution, Structured Extraction)
    * Prompt-based workflow builder and editor
    * Visual workflow builder with full customization
    * Enterprise connectors and features like RBAC
    * Dedicated support and SLAs

    [Contact us](https://contextual.ai/contact) to learn more.
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup>
  <Card title="Platform Quickstart (GUI)" icon="browser" href="/quickstarts/platform-gui">
    Create your first agent and datastore in the platform
  </Card>

  <Card title="Platform Quickstart (API)" icon="code" href="/quickstarts/platform-api">
    Create agents programmatically via the Python SDK
  </Card>
</CardGroup>

### Learn More

* [Why Contextual AI](/quickstarts/why-contextual-ai) — What makes Contextual AI different and when to use it
* [Agent Composer](/quickstarts/agent-composer) — Build custom agent workflows (enterprise) or use templates (self-serve)
* [Datasources & Connectors](/connectors/overview) — Connect your enterprise data sources
* [How-to Guides](/how-to-guides/platform) — Deep dives on specific capabilities


# LMUnit
Source: https://docs.contextual.ai/quickstarts/lmunit

Contextual AI Component Quickstart

## Overview

Natural language unit tests bring the clarity and rigor of software unit testing to LLM evaluation. By defining simple, testable statements about desired response qualities, teams can assess model outputs with far more precision than traditional metrics or general-purpose judges.

LMUnit is a specialized model built for this paradigm—delivering state-of-the-art fine-grained evaluation, strong human alignment, and clearer, more actionable insights to help teams debug, improve, and safely deploy LLM applications.

## Key Features

* Natural language unit tests for evaluating specific response qualities.
* State-of-the-art accuracy on fine-grained benchmarks (FLASK, BigGBench).
* Superior to frontier models on targeted evaluation tasks.
* High human alignment with 93.5% RewardBench accuracy.
* Actionable feedback with more granular error detection than LM judges.
* Easy integration into CI/CD and existing evaluation workflows.
* Accessible to all stakeholders via readable, test-based criteria.

## Getting Started

See the [LMUnit How-to guide](/how-to-guides/lmunit) for a detailed walkthrough on how to use the LMUnit API.

## Additional Resources

* [Contextual AI LMUnit Blog Post](https://contextual.ai/research/lmunit)
* [Developer Guide: Ensuring Agent and LLM Quality with CircleCI and LMUnit](https://contextual.ai/blog/lmunit-circleci)
* [LMUnit Evaluation Script for RewardBench](https://github.com/ContextualAI/examples/tree/main/09-lmunit-rewardbench)
* [Notebook and Examples](https://github.com/ContextualAI/examples/blob/main/03-standalone-api/01-lmunit/lmunit.ipynb)


# Contextual AI MCP Server
Source: https://docs.contextual.ai/quickstarts/mcp-server

Integrate Contextual MCP server with compatible AI clients

Our AI's Model Context Protocol (MCP) server provides RAG capabilities using Contextual AI. This guide walks through integrating Contextual AI’s MCP Server in both local and remote configurations for:

* [OpenAI GUI](#openai-gui)
* [Cursor IDE](#cursor-ide)
* [Local Installation](#local-mcp-server-installation)

## Overview

The Contextual AI MCP server acts as a bridge between AI interfaces and a specialized Contextual AI agent. It enables:

* **Query Processing**: Direct your domain specific questions to a dedicated Contextual AI agent
* **Intelligent Retrieval**: Searches through comprehensive information in your knowledge base
* **Context-Aware Responses**: Generates answers that are grounded in source documentation and include citations and attributions.

***

## Remote MCP server

The Remote MCP server enables direct access to hosted MCP services, no local installation required. Just provide the following:

* Server URL: `https://mcp.app.contextual.ai/mcp`
* Contextual API key for authentication.
* Contextual Agent ID. You can create your agent by following the [**Getting Started Guide**](getting-started).

### OpenAI GUI

1. Go to [platform.openai.com/chat](https://platform.openai.com/chat/) and click `+ Create`.

<img alt="" />

2. Under **Tools**, click `+ Add` followed by `MCP server` in the drop-down menu.

<img alt="" />

3. Click `+ Server` in the **Add MCP server** window.

<img alt="" />

4. Enter the following information:

* **URL:** `https://mcp.app.contextual.ai/mcp`
* **Label:** `Contextual_AI_RAG_agent`
* **Authentication:** `Access token / API key`

Copy/paste your Contextual AI API key and click `Connect`.

<img alt="" />

5. Verify your settings and click `Add`.

<img alt="" />

6. Your new MCP server should appear next to **Tools**.

<img alt="" />

Under **Developer message**, enter a message like this:

```
Use RAG platform with agent_id {YOUR_AGENT_ID} to answer {RELEVANT_QUERY}.
```

<img alt="" />

5. In settings under [Data controls -> Hosted tools](https://platform.openai.com/settings/organization/data-controls/hosted-tools), verify that **MCP tool usage** is enabled for your project.

<img alt="" />

You’re now ready to chat!

> ⚠️ **Note:** If you’re using one or more MCP servers, they’ll stop working after you save your prompt or reopen the chat. To reconfigure:
>
> 1. Open the MCP server settings in your AI client (e.g., OpenAI, Cursor IDE).
> 2. For each MCP server, verify the server URL, API key, and Agent ID are correct.
> 3. Re-enter or update any missing information, then save the configuration.
> 4. Wait up to 30 seconds for the servers to reconnect and become available.
>    This process ensures your MCP servers are restored and ready for use.

### Cursor IDE

1. Create the MCP configuration file. For Cursor, you can use one of these locations:

* Project-specific -  `.cursor/mcp.json` in your project directory
* Global - `~/.cursor/mcp.json` for system-wide access

2. Add the configuration:

```
{
 "mcpServers": {
   "ContextualAI": {
     "url": "https://mcp.app.contextual.ai/mcp/",
  }
 }
}
```

3. Restart Cursor IDE

Now, you can use your Contextual MCP server with Cursor in several ways.

1. Cursor IDE chat

In Cursor's chat interface, you might ask:

```
Use RAG platform with api_key key-YOUR_API_KEY and agent_id YOUR_AGENT_ID, show me RELEVANT_QUERY.
```

The MCP client will route the query to your Contextual AI agent and generate a response to Cursor.

2. Test script to check for connectivity

You may also run a short test script to verify the connection in Cursor:

```
#!/usr/bin/env python3
"""
Quick test script for ContextualAI HTTP MCP Server
Replace the following placeholders with your actual values:
- YOUR_API_KEY: Your Contextual AI API key
- YOUR_AGENT_ID: Your Contextual AI agent ID
- YOUR_QUERY: Your test question for the agent
"""

import asyncio
from fastmcp import Client

# Server configuration
SERVER_URL = "https://mcp.app.contextual.ai/mcp/"
API_KEY = "key-YOUR_API_KEY"

def extract_result(result):
   """Extract text from FastMCP result format"""
   if isinstance(result, list) and len(result) > 0:
       return result[0].text
   return str(result)

async def quick_test():
   """Quick test of essential functionality"""
   print("=== Quick ContextualAI HTTP MCP Test ===\n")
   
   try:
       # Use Streamable HTTP transport (the working one!)
       from fastmcp.client.transports import StreamableHttpTransport
       transport = StreamableHttpTransport(
           url=SERVER_URL,
           headers={
               "Authorization": f"Bearer {API_KEY}",
               "Content-Type": "application/json"
           }
       )
       
       async with Client(transport) as client:
           # Test 1: Server connection
           print("🔌 Testing server connection...")
           await client.ping()
           print("✅ Server is reachable")
           
           # Test 2: List tools
           tools = await client.list_tools()
           print(f"✅ Available tools: {[tool.name for tool in tools]}")
           
           # Test 3: Your query
           print("\n🔍 Testing query:")
           print("Query: 'YOUR_QUERY'")
           result = await client.call_tool("query", {
               "prompt": "YOUR_QUERY",
               "agent_id": "YOUR_AGENT_ID",
               "api_key": API_KEY
           })
           response = extract_result(result)
           print(f"Response: {response}")
           print("\n" + "="*80 + "\n")
           print("🎉 All tests completed successfully!")
           
   except Exception as e:
       print(f"❌ Test failed: {e}")
       print("Please check:")
       print("- Server URL is correct")
       print("- API key is valid")
       print("- Network connectivity")
       print("- FastMCP is installed: pip install fastmcp")

if __name__ == "__main__":
   asyncio.run(quick_test())
```

To run the test:

1. Install FastMCP: `pip install fastmcp`
2. Replace placeholders with your actual values
3. Run: `python test_script.py`

***

## Local MCP Server Installation

### Prerequisites

* Python 3.10 or higher
* Cursor IDE and/or Claude Desktop
* Contextual AI API key
* MCP-compatible environment

### Installation

1. Clone the repository:

```bash theme={null}
git clone https://github.com/ContextualAI/contextual-mcp-server.git
cd contextual-mcp-server
```

2. Create and activate a virtual environment:

```bash theme={null}
python -m venv .venv
source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
```

3. Install dependencies:

```bash theme={null}
pip install -e .
```

### Configuration

#### Configure MCP Server

The server requires modifications of settings or use. For example, the single use server should be customized with an appropriate docstring for your RAG Agent.

The docstring for your query tool is critical as it helps the MCP client understand when to route questions to your RAG agent. Make it specific to your knowledge domain. Here is an example:

```
A research tool focused on financial data on the largest US firms
```

or

```
A research tool focused on technical documents for Omaha semiconductors
```

The server also requires the following settings from your RAG Agent:

* `API_KEY`: Your Contextual AI API key
* `AGENT_ID`: Your Contextual AI agent ID

If you'd like to store these files in `.env` file you can specify them like so:

```bash theme={null}
cat > .env << EOF
API_KEY=key...
AGENT_ID=...
EOF
```

#### AI Interface Integration

This MCP server can be integrated with a variety of clients. To use with either Cursor IDE or Claude Desktop create or modify the MCP configuration file in the appropriate location:

1. First, find the path to your `uv` installation:

```bash theme={null}
UV_PATH=$(which uv)
echo $UV_PATH
# Example output: /Users/username/miniconda3/bin/uv
```

2. Create the configuration file using the full path from step 1:

```bash theme={null}
cat > mcp.json << EOF
{
 "mcpServers": {
   "ContextualAI-TechDocs": {
     "command": "$UV_PATH", # make sure this is set properly
     "args": [
       "--directory",
       "\${workspaceFolder}",  # Will be replaced with your project path
       "run",
       "multi-agent/server.py"
     ]
   }
 }
}
EOF
```

3. Move to the correct folder location, see below for options:

```bash theme={null}
mkdir -p .cursor/
mv mcp.json .cursor/
```

Configuration locations:

* For Cursor:
  * Project-specific: `.cursor/mcp.json` in your project directory
  * Global: `~/.cursor/mcp.json` for system-wide access
* For Claude Desktop:
  * Use the same configuration file format in the appropriate Claude Desktop configuration directory

#### Environment Setup

This project uses `uv` for dependency management, which provides faster and more reliable Python package installation.

### Usage

\
The current server focuses on using the query command from the Contextual AI python SDK, however you could extend this to support other features such as listing all the agents, updating retrieval settings, updating prompts, extracting retrievals, or downloading metrics.

For example, in Cursor, you might ask:

```
Show me the code for initiating the RF345 microchip?
```

The MCP client will

1. Determine if this should be routed to the MCP Server

Then the MCP server will

1. Route the query to the Contextual AI agent
2. Retrieve relevant documentation
3. Generate a response with specific citations
4. Return the formatted answer to Cursor

## Additional Resources

* [Contextual AI MCP Server on GitHub](https://github.com/ContextualAI/contextual-mcp-server)
* [Contextual AI MCP Server How-to Guide](/how-to-guides/mcp-server-user-guide)


# Parse
Source: https://docs.contextual.ai/quickstarts/parse

Contextual AI Component Quickstart

## Overview

Parse is Contextual AI's structured data extraction model. It excels at converting unstructured text (PDF, DOCX) into markdown format by identifying and extracting key information.

## Key Features

* Extracts unstructured data into markdown text
* Hierarchical representation of sections including title, headers, etc.
* Table extraction
* Multiple output formats (markdown-per-page, markdown-document, and blocks-per-page)

## Getting Started

See the [Parse How-to guide](/how-to-guides/parse) for a detailed walkthrough on how to use the Parse API to extract structured data from documents.

## Additional Resources

* [Contextual AI Parser Blog Post](https://contextual.ai/blog/document-parser-for-rag)
* [Notebook and Example](https://github.com/ContextualAI/examples/blob/main/03-standalone-api/04-parse/parse.ipynb)


# Platform Quickstart (API)
Source: https://docs.contextual.ai/quickstarts/platform-api

Create a specialized RAG agent programmatically

## Create and Prompt Your First Agent

This guide walks you through creating a **research-oriented agent designed for long, technical documents and multi-step reasoning**. The agent uses **Agent Composer (AC)** to run a graph-based workflow that performs iterative retrieval, analysis, and synthesis across complex source material.

The document set for this tutorial consists of **NASA technical reports focused on Fault Detection, Isolation, and Recovery (FDIR)** in safety-critical autonomous systems. These documents are intentionally dense and fragmented, making them ideal for demonstrating agentic research rather than simple single-pass RAG.

***

### Learning Outcomes

By completing this quickstart, you'll learn how to:

1. **Create and configure datastores** for securely storing and indexing long technical documents
2. **Ingest complex PDFs** with hierarchy-aware parsing, including figures, tables, and cross-references
3. **Define a research workflow** using a default Agent Composer YAML graph
4. **Create an agent** that uses Agent Composer to perform multi-document research and synthesis
5. **Query and interact with the agent** through both the UI and API, observing retrievals, generation, and workflow execution

⏱️ This tutorial can be completed in **under 15 minutes**. All steps can also be performed through the **GUI** for a no-code Agent Composer experience.

***

### Step 0: Set Up Your Environment

Start by installing the required dependencies and setting up your development environment. The `contextual-client` library provides Python bindings for the Contextual AI platform, while the additional packages support data visualization and progress tracking.

```python theme={null}
# Install required packages for Contextual AI integration and data visualization
%pip install contextual-client matplotlib tqdm requests pandas python-dotenv
```

Next, import the necessary libraries that you'll use throughout this quickstart:

```python theme={null}
import os
import json
import requests
from pathlib import Path
from typing import List, Optional, Dict
from IPython.display import display, JSON
import pandas as pd
from contextual import ContextualAI
import ast
```

#### API Authentication Setup

Before we can start building our RAG agent, you'll need access to the Contextual AI platform.

**Step-by-Step API Key Setup:**

1. **Create Your Account**: Visit [app.contextual.ai](https://app.contextual.ai/?utm_campaign=agents-towards-production\&utm_source=diamantai\&utm_medium=github\&utm_content=notebook) and click the **"Start Free"** button
2. **Navigate to API Keys**: Once logged in, find **"API Keys"** in the sidebar
3. **Generate New Key**: Click **"Create API Key"** and follow the setup steps
4. **Store Securely**: Copy your API key and store it safely (you won't be able to see it again)

<div>
  <img alt="API Keys page in the Contextual AI platform" />
</div>

**Configuring Your API Key**

To run this quickstart, you can store your API key in a `.env` file. This keeps your keys separate from your code. After setting up your `.env` file, you can load the API key from `.env` to initialize the Contextual AI client. Feel free to use Google Secrets as well if in Google Colab.

Now, you can load the API key from `.env` to initialize the Contextual AI client.

```python theme={null}
# Load API key from .env or google secrets
from dotenv import load_dotenv
import os
try:
    # Try Colab secrets if in Google Colab
    from google.colab import userdata
    API_KEY = userdata.get('CONTEXTUAL_API_KEY')
except:
    # Fallback to environment variable
    load_dotenv()
    API_KEY = os.getenv('CONTEXTUAL_API_KEY')

if not API_KEY:
    raise ValueError("Please set your CONTEXTUAL_API_KEY in Colab Secrets or as an environment variable")

from contextual import ContextualAI
client = ContextualAI(api_key=API_KEY)
```

### Step 1: Create Your Document Datastore

A datastore in Contextual AI is a secure, isolated container for your documents and their processed representations. Each datastore provides:

* Isolated Storage: Documents are kept separate and secure for each use case
* Intelligent Processing: Automatic parsing, chunking, and indexing of uploaded documents
* Optimized Retrieval: High-performance search and ranking capabilities

#### Why Separate Datastores?

Each agent should have its own datastore to ensure:

* Data isolation between different use cases
* Security compliance for sensitive document collections
* Performance optimization agents can be customized for specific document types and query patterns

Let's create a datastore for our NASA document analysis agent:

<CodeGroup>
  ```python Python theme={null}
  # Adding Nasa PDF's

  datastore_name = 'NASA_Datastore'

  # Check if datastore exists
  datastores = client.datastores.list()
  existing_datastore = next((ds for ds in datastores if ds.name == datastore_name), None)

  if existing_datastore:
      datastore_id = existing_datastore.id
      print(f"Using existing datastore with ID: {datastore_id}")
  else:
      result = client.datastores.create(name=datastore_name)
      datastore_id = result.id
      print(f"Created new datastore with ID: {datastore_id}")

  print(client.datastores.list())
  ```
</CodeGroup>

### Step 2: Document Ingestion and Processing

Now that your agent’s datastore is set up, let’s add a collection of **NASA technical documents focused on Fault Detection, Isolation, and Recovery (FDIR)**. Contextual AI’s document processing engine provides enterprise-grade parsing that is well-suited for dense engineering and research content, including:

* **Complex Tables:** Experimental results, system parameters, and evaluation metrics
* **Charts and Figures:** Architecture diagrams, fault trees, and performance plots
* **Multi-page Technical Documents:** Long reports with deep hierarchical structure, appendices, and references

These capabilities are critical for enabling research and synthesis workflows, where no single document contains a complete answer.

#### Supported File Formats

The platform supports a wide range of document formats commonly used in technical and research workflows:

* PDF: Research papers, technical reports, and whitepapers
* HTML: Saved web pages and online documentation
* DOC/DOCX: Technical notes and written analyses
* PPT/PPTX: Conference presentations and engineering briefings

#### Sample NASA FDIR Documents

For this quickstart, we intentionally use complex, unstructured technical documents rather than clean or structured datasets. The document set includes NASA technical reports covering:

* Fault detection, isolation, and recovery (FDIR) in safety-critical systems
* Autonomous fault recovery for distributed electric propulsion aircraft
* Certification methodologies for lunar surface autonomy and construction missions
* System health management and failure analysis in tightly coupled subsystems

Readers are encouraged to open and skim the source documents directly to understand their length, structure, and technical depth:

* NASA Technical Reports Server (NTRS): [https://ntrs.nasa.gov](https://ntrs.nasa.gov)

These documents are deliberately chosen to be dense, technical, and fragmented across sources, making them ideal for demonstrating why agentic research and multi-document synthesis (not just simple RAG) is valuable.

#### Preparing the Document Collection

Next, we’ll upload these documents into the datastore. Once ingested, Contextual AI will automatically:

* Parse and extract text from each document
* Chunk content for efficient hybrid (semantic + lexical) retrieval
* Index the documents for grounded research and synthesis

This processed document set will serve as the knowledge foundation for the Agent Composer workflow you’ll build in the following steps.

<CodeGroup>
  ```python Python theme={null}
  import os
  import requests

  # Create data directory if it doesn't exist
  if not os.path.exists('data'):
      os.makedirs('data')

  files_to_upload = [
      (
          "A_Fault_Recovery_Distributed_Electric_Propulsion.pdf",
          "https://ntrs.nasa.gov/api/citations/20240013567/downloads/TM-20240013567.pdf",
      ),
      (
          "B_Lunar_Surface_Autonomy_Certification_FDIR.pdf",
          "https://ntrs.nasa.gov/api/citations/20250010214/downloads/MDA%20Paper%20ISS%20CaseStudy%202025%20Author%20Name%20Added.docx",
      ),
  ]
  ```
</CodeGroup>

#### Document Download & Ingestion Process

The following cell will:

* Download documents from Contextual AI's examples repository (if not already cached)
* Upload to Contextual AI for intelligent processing
* Track processing status and document IDs for later reference

<CodeGroup>
  ```python Python theme={null}
  # Download and ingest all files
  document_ids = []
  for filename, url in files_to_upload:
      file_path = f'data/{filename}'

      # Download file if it doesn't exist
      if not os.path.exists(file_path):
          print(f"Fetching {file_path}")
          try:
              response = requests.get(url)
              response.raise_for_status()  # Raise an exception for bad status codes
              with open(file_path, 'wb') as f:
                  f.write(response.content)
          except Exception as e:
              print(f"Error downloading {filename}: {str(e)}")
              continue

      # Upload to datastore
      try:
          with open(file_path, 'rb') as f:
              ingestion_result = client.datastores.documents.ingest(datastore_id, file=f)
              document_id = ingestion_result.id
              document_ids.append(document_id)
              print(f"Successfully uploaded {filename} to datastore {datastore_id}")
      except Exception as e:
          print(f"Error uploading {filename}: {str(e)}")

  print(f"Successfully uploaded {len(document_ids)} files to datastore")
  print(f"Document IDs: {document_ids}")
  ```
</CodeGroup>

### Step 3: Inspect Your Documents

Let's take a look at our documents at [https://app.contextual.ai/](https://app.contextual.ai/?utm_campaign=agents-towards-production\&utm_source=diamantai\&utm_medium=github\&utm_content=notebook)

1. Navigate to your workspace
2. Select **Datastores** on the left menu
3. Select **Documents**
4. Click on **Inspect** (once documents load)

You will see datastore uploads in progress. Click through the documents to see how they are chunked!

Once ingested, you can view the list of documents, see their metadata, and also delete documents via API.

<Note>It may take a few minutes for the document to be ingested and processed. If the documents are still being ingested, you will see `status='processing'`. Once ingestion is complete, the status will show as `status='completed'`.</Note>

You can learn more about the metadata [here](https://docs.contextual.ai/api-reference/datastores-documents/get-document-metadata?utm_campaign=agents-towards-production\&utm_source=diamantai\&utm_medium=github\&utm_content=notebook).

<CodeGroup>
  ```python Python theme={null}
  metadata = client.datastores.documents.metadata(datastore_id = datastore_id, document_id = document_ids[0])
  print("Document metadata:", metadata)
  ```
</CodeGroup>

### Step 4: Agent Creation & Configuration

Now you'll create an Agent Composer agent via the API by attaching a YAML workflow. This defines the agent as a graph of steps (research + generation), rather than a single fixed RAG path.

<CodeGroup>
  ```python Python theme={null}
  # Load the YAML (The workflow graph -> will add an explanation to this as well)
  acl_yaml = """
  version: 0.1
  inputs:
    query: str

  outputs:
    response: str

  nodes:
    create_message_history:
      type: CreateMessageHistoryStep
      input_mapping:
        query: __inputs__#query

    research:
      type: AgenticResearchStep
      ui_stream_types:
        retrievals: true
      config:
        tools_config:
          - name: search_docs
            description: |
              Search the datastore containing user-uploaded documents. This datastore is a vector database of text chunks which uses hybrid semantic and lexical search to find the most relevant chunks.
              Use this tool to find information within the uploaded documents.
            step_config:
              type: SearchUnstructuredDataStep
              config:
                top_k: 50
                lexical_alpha: 0.1
                semantic_alpha: 0.9
                reranker: "ctxl-rerank-v2-instruct-multilingual-FP8"
                rerank_top_k: 12
                reranker_score_filter_threshold: 0.2

        agent_config:
          agent_loop:
            num_turns: 10
            parallel_tool_calls: false
            model_name_or_path: "vertex_ai/claude-opus-4-5@20251101"
            identity_guidelines_prompt: |
              You are a retrieval-augmented assistant created by Contextual AI. You provide factual, grounded answers to user's questions by retrieving information via tools and then synthesizing a response based only on what you retrieved.

            research_guidelines_prompt: |
              You MUST always explore the unstructured datastore before answering. Use breadth-then-depth retrieval, avoid redundant searches, and be comprehensive.

      input_mapping:
        message_history: create_message_history#message_history

    generate:
      type: GenerateFromResearchStep
      ui_stream_types:
        generation: true
      config:
        model_name_or_path: "vertex_ai/claude-opus-4-5@20251101"
        identity_guidelines_prompt: |
          You are a retrieval-augmented assistant created by Contextual AI. Provide factual, grounded answers based only on retrieved information.
        response_guidelines_prompt: |
          - Output concise Markdown with headings/bullets.
          - Start immediately with the answer (no preamble).
          - If info is missing, say what's missing and what you can infer safely.

      input_mapping:
        message_history: create_message_history#message_history
        research: research#research

    __outputs__:
      type: output
      input_mapping:
        response: generate#response
  """.strip()
  ```

  Create the agent via API:

  ```python Python theme={null}
  import requests
  from google.colab import userdata

  BASE_URL = userdata.get("CONTEXTUAL_BASE_URL")
  API_KEY  = userdata.get("CONTEXTUAL_API_KEY")
  HEADERS  = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

  agent_name = "NASA_FDIR_AC_Demo"
  description = "Agent Composer (AC) demo: multi-document research & synthesis over NASA technical reports."

  payload = {
      "name": agent_name,
      "description": description,
      "system_prompt": (
          "You are a technical research assistant for fault detection, isolation, and recovery (FDIR) and autonomous systems. "
          "Use retrieved document evidence. If the documents do not support an answer, say what is missing and avoid guessing. "
          "Write concise Markdown with short headings and bullet points."
      ),
      "suggested_queries": [
          "Summarize the core principles of Fault Detection, Isolation, and Recovery (FDIR) across the uploaded NASA reports.",
          "Compare fault recovery approaches described for distributed electric propulsion aircraft vs lunar surface autonomy systems.",
          "Propose a structured fault investigation and recovery workflow based only on the uploaded documents.",
      ],
      "datastore_ids": [datastore_id],
      "agent_configs": {
          "acl_config": {
              "acl_active": True,
              "acl_yaml": acl_yaml
          }
      }
  }

  resp = requests.post(f"{BASE_URL}/agents", headers=HEADERS, json=payload)
  print(resp.status_code)
  print(resp.text)
  resp.raise_for_status()
  agent = resp.json()

  agent_id = agent["id"]
  print("Created agent:", agent_id)
  ```

  ```shell Shell theme={null}
  curl --request POST \
       --url https://api.contextual.ai/v1/agents \
       --header 'accept: application/json' \
       --header 'authorization: Bearer $API_KEY' \
       --header 'content-type: application/json' \
       --data '{
         "name": "NASA_FDIR_AC_Demo",
         "description": "Agent Composer (AC) demo: multi-document research & synthesis over NASA technical reports.",
         "system_prompt": "You are a technical research assistant for fault detection, isolation, and recovery (FDIR) and autonomous systems. Use retrieved document evidence. If the documents do not support an answer, say what is missing and avoid guessing. Write concise Markdown with short headings and bullet points.",
         "datastore_ids": ["YOUR_DATASTORE_ID"],
         "agent_configs": {
           "acl_config": {
             "acl_active": true,
             "acl_yaml": "YOUR_YAML_CONFIG"
           }
         }
       }'
  ```
</CodeGroup>

**Example Response:**

```text theme={null}
200
{"id":"1e6a7774-1191-424a-99d2-76effceed19e","datastore_ids":["4a631e7d-bc2e-4983-8824-0130eff2794c"]}
Created agent: 1e6a7774-1191-424a-99d2-76effceed19e
```

### Step 5: Analyze Your Agent (optional)

#### Open the Agent in the UI

* Go to: `app.contextual.ai`
* Navigate: **Agents -> select your agent: NASA\_FDIR\_AC\_Demo**
* Confirm the linked datastore is your semiconductor documents datastore.

#### Open Agent Composer

Inside the agent page:

* Click **Agent Composer** (or **AC**)
  You should see one of:
  * **Workflow Builder** (graph view)
  * **YAML editor** (text view)

#### Workflow Builder (Graph View)

* Open **Workflow Builder**
  Confirm the graph contains the core steps:
  * `CreateMessageHistoryStep`
  * `AgenticResearchStep` (streams retrievals)
  * `GenerateFromResearchStep` (streams generation)
  * Output node wired to `response`

#### YAML View

* Open the **YAML editor**
* Confirm the YAML matches the `acl_yaml` you used in the API section.

### Step 6: Query the Agent in the API

<CodeGroup>
  ```python Python theme={null}
  import requests
  from google.colab import userdata

  BASE_URL = userdata.get("CONTEXTUAL_BASE_URL")
  API_KEY  = userdata.get("CONTEXTUAL_API_KEY")
  HEADERS  = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

  query = "What are the main topics or themes covered in the documents?"

  print(f"Query: {query}\n")

  payload = {
      "messages": [{"role": "user", "content": query}],
      "stream": False
  }

  resp = requests.post(f"{BASE_URL}/agents/{agent_id}/query/acl", headers=HEADERS, json=payload)
  resp.raise_for_status()
  out = resp.json()

  print(out["message"]["content"])
  ```

  ```shell Shell theme={null}
  curl --request POST \
       --url https://api.contextual.ai/v1/agents/{agent_id}/query/acl \
       --header 'accept: application/json' \
       --header 'authorization: Bearer $API_KEY' \
       --header 'content-type: application/json' \
       --data '{
         "messages": [{"role": "user", "content": "What are the main topics or themes covered in the documents?"}],
         "stream": false
       }'
  ```
</CodeGroup>

**Example Response:**

```text theme={null}
Query: What are the main topics or themes covered in the documents?

Based on my comprehensive search of the document collection, I can now provide a summary of the main topics and themes covered.

# Main Topics and Themes in the Documents

Based on my review, the documents contain **a single NASA technical memorandum** (NASA/TM-20240013567) titled **"Piloted Evaluation of Fault Recovery System for Aircraft with Distributed Electric Propulsion"**. The main topics and themes are as follows:

---

## 1. **SUSAN Electrofan Concept Aircraft**
The documents focus on the SUbsonic Single Aft eNgine (SUSAN) Electrofan, a NASA concept aircraft designed as a series/parallel partial hybrid electric single-aisle transport aircraft targeting fuel burn and emissions reductions [14]() [11](). Key specifications include:
- 180 passengers, 2,500-mile design range, Mach 0.78 cruise speed [11]()
- 16 underwing Electric Engines (EEs) with eight on each side [11]()
- Single aft-mounted boundary layer-ingesting (BLI) gas turbine engine with generators [11]()

---

## 2. **Hybrid Electric Propulsion Architecture**
The powertrain design features a complex electromechanical system:
- Series/parallel partial hybrid Electric Aircraft Propulsion (EAP) system [14]() [17]()
- Power extraction from the gas turbine through 5 MW and 1 MW motor/generators [18]()
- Distributed Electric Propulsion (DEP) providing 65% of total thrust during normal operation [16]()
- Both rechargeable and single-use emergency batteries integrated into the electrical strings [11]() [18]()

---

## 3. **Integrated Vehicle Health Management (IVHM)**
A core theme is the implementation of health management systems:
- Automatic detection, diagnosis, prognosis, and mitigation of component failures [16]()
- SAE International's "Self-Adaptive Health Management System" framework [16]()
- Built-in redundancy allowing EE or generator failures to be accommodated without significant performance impact [16]()

---

## 4. **Thrust Reallocation Algorithm**
The documents detail an optimal control algorithm for fault recovery:
- Redistributes thrust commands when EEs fail or saturate [20]()
- Minimizes power consumption while maintaining commanded forces and moments [20]()
- Maintains total net thrust and net torque on the aircraft [6]()

---

## 5. **Flight Simulator Piloted Evaluation**
The research includes piloted testing in a flight simulator with three main examples [23]():
- **Example 1**: Pilot observes aircraft behavior during sequential EE failures [23]()
- **Example 2**: Pilot moves throttle during failures, causing saturations [24]()
- **Example 3**: Pilot actively maintains trim during failure scenarios [9]()

Results showed that disturbances from failures were minor and easily compensated [21]() [19]().

---

## 6. **Certification and Safety Considerations**
The documents address regulatory implications:
- Relation to FAA airworthiness standards (14 CFR § 25.143-149) [19]()
- Graceful degradation when powertrain redundancy is exceeded [19]()
- Controllability and maneuverability maintained even with multiple EEs inoperative [19]()

---

## Summary
The document collection is entirely focused on **advanced electrified aircraft propulsion technology**, specifically covering hybrid-electric powertrain design, automated fault detection and recovery systems, and piloted validation testing for the NASA SUSAN concept aircraft.
```

***

## Next Steps

* [Agent Composer](/quickstarts/agent-composer) — Build customized agent workflows
* [Python SDK Reference](/sdks/python) — Full SDK documentation


# Platform Quickstart (GUI)
Source: https://docs.contextual.ai/quickstarts/platform-gui

Create a specialized RAG agent in less than 5 minutes

## Create and Query Your First Agent

This guide walks you through creating a datastore, uploading documents, and building an agent—all through the Contextual AI web interface.

### Step 1: Create an Agent

Log in to app.contextual.ai with your user credentials. On the left-hand side navigation, click on **Agents**.

From the Agents overview page, click on `+ New Agent` to create a new agent. Give your agent an:

1. Agent Name
2. Description

Under **Configuration**, accept the defaults (Template, Agentic Search) and proceed to creating your datastore.

<video />

### Step 2: Create a Datastore

Under **Datastores**, click `+ Create new datastore`. Give your new datastore a `Datastore Name`, accept the defaults (File Upload, Unstructured) amd click **Next**.

Go back to your Datastores overview page and click on the name of your new datastore. Click `Upload` to add documents to it. Contextual AI securely stores your documents and parses them in formats optimized for RAG pipelines and agents.

Once your document has been processed, it will display `Processed` as its status.

<video />

<Note>
  **For best results:**

  * Use renderable PDFs and documents with text that can be copied and pasted.
  * Don’t have your own documents ready? Use these [sample documents](https://drive.google.com/drive/folders/1e2qfAp6rrpcOGyDdBHwHP-zKzC6K7nyg?usp=drive_link).
</Note>

### Step 3: Prompt Your New Agent

Click `Agents` in the left-hand navigation, followed by the name of your new agent. Try asking your agent a question.

<video />

<Note>
  **Note:** You can query your agent only after at least one document in the datastore has been fully processed.
</Note>

***

## Next Steps

* [Agent Composer](/quickstarts/agent-composer) — Build custom agent workflows (enterprise) or use templates (self-serve)
* [Platform Quickstart (API)](/quickstarts/platform-api) — Create agents programmatically via the Python SDK
* [Datasources & Connectors](/connectors/overview) — Connect your enterprise data sources


# Prompt Builder
Source: https://docs.contextual.ai/quickstarts/prompt-builder

Create agent workflows using natural language

<Note>
  The Prompt Builder is currently in **Beta**. It generates Agent Composer
  workflows from natural language descriptions.
</Note>

## Overview

The Prompt Builder lets you describe what you want your agent to do in
plain language, and it generates the workflow configuration automatically.
Instead of building nodes manually or writing YAML, you describe your use
case and the system creates the workflow for you.

## How It Works

1. **Describe your agent** — Write what the agent should do, what data
   sources it needs, and what output format you want
2. **Generate workflow** — The system creates an Agent Composer workflow
   based on your description
3. **Review and customize** — Fine-tune the generated workflow in the
   Visual Builder
4. **Deploy** — Save and start using your agent

## Create an Agent with Prompt Builder

### 1. Start a New Agent

1. Go to **Agents** in the left sidebar
2. Click **+ New Agent**
3. Select **Prompt** under Configuration

### 2. Describe Your Agent

Write a detailed description of what your agent should do. Include:

* **Your role** — Who will use this agent
* **The task** — What the agent needs to accomplish
* **Data sources** — What systems or documents it should search
* **Output format** — How results should be structured

**Example prompt:**

```
I am a rocket propulsion test engineer responsible for ensuring hot
fire tests meet compliance prerequisites. I need an agent that can
compile and cross-reference dozens of documents from multiple systems
to satisfy the requirements of NASA standard test readiness and build
them into a verification matrix document with an executive summary.

The agent should search for and verify these document categories:

1. Signed-off Test Procedures from MES/PLM systems
2. FTA, FMEA, and Hazard Controls from Safety databases
3. Approved Waivers from Configuration Management
4. Instrumentation Calibration Records from Metrology systems
5. Training and Certification records from LMS/ERP
6. Environmental and Safety Permits from EHS portals
7. Reference TRR Packages from Knowledge Management archives

The output should be a formal verification matrix showing the status
of each category (complete, needs attention, or missing) with document
citations and an executive summary with GO/NO-GO/CONDITIONAL status.
```

### 3. Generate and Customize

1. Click **Create & Customize** — the system generates a workflow
2. Review the workflow in the Visual Builder
3. Link your datastore with relevant documentation
4. Adjust nodes or connections as needed
5. Click **Save & Continue** → **Create**

Your agent is ready to use.

***

## Export and Import YAML

The workflow is stored as YAML. You can export it to save, share,
or version control your configuration.

**To Export:**

1. In the Visual Builder, click the **hamburger menu** (☰) next to
   "Agent Composer"
2. Click **Export**
3. Copy or download the YAML

**To Import:**

1. Create a new agent and open the Visual Builder
2. Click the **hamburger menu** (☰)
3. Click **Import**
4. Paste your YAML — the workflow appears visually

***

## Related

* [Agent Composer Quickstart](/quickstarts/agent-composer) —
  Overview of Agent Composer capabilities
* [Agent Composer GUI Guide](/how-to-guides/agent-composer-gui) —
  Build workflows visually without prompts
* [Agent Composer YAML Guide](/how-to-guides/agent-composer-yaml) —
  Write workflow configurations directly


# Rerank
Source: https://docs.contextual.ai/quickstarts/rerank

Contextual AI Component Quickstart

## Overview

Contextual AI’s instruction-following reranker is the world’s first reranker designed to follow custom instructions about how to prioritize documents based on specific criteria like recency, source, and metadata. With superior performance on the BEIR benchmark (scoring 61.2 and outperforming competitors by significant margins), it delivers unprecedented control and accuracy for enterprise RAG applications.

## Key Features

* **Instruction Following:** Dynamically control document ranking through natural language commands
* **Conflict Resolution:** Intelligently handle contradictory information from multiple knowledge sources
* **Superior Accuracy:** Achieve state-of-the-art performance on industry benchmarks
* **Seamless Integration:** Drop-in replacement for existing rerankers in your RAG pipeline

## Getting Started

See the [Rerank How-to guide](/how-to-guides/rerank) for a detailed walkthrough on how to use the Rerank API.

## Additional Resources

* [Contextual AI Reranker Blog Post](https://contextual.ai/blog/introducing-instruction-following-reranker)
* [Contextual AI Reranker V2 Announcement](https://contextual.ai/blog/rerank-v2)
* [Snowflake Cortex Integration](https://contextual.ai/blog/contextual-ais-state-of-the-art-reranker-coming-to-snowflake-cortex-ai)
* [Contextual AI Reranker v2 Benchmarks](https://github.com/ContextualAI/examples/blob/main/03-standalone-api/03-rerank/reranker_benchmarking.ipynb)
* [Notebook and Examples](https://github.com/ContextualAI/examples/tree/main/03-standalone-api/03-rerank)


# Why Contextual AI
Source: https://docs.contextual.ai/quickstarts/why-contextual-ai

What makes Contextual AI different and when to use it

Contextual AI is built for tasks that are **both complex and routine**—work that requires deep domain expertise but happens frequently enough that the right automation delivers transformative results. If your team spends hours digging through technical documents, logs, or specifications to answer questions or make decisions, Contextual AI can reduce that to minutes.

<img alt="Contextual AI focuses on complex, important, but routine tasks to 10x productivity" />

***

## When to Use Contextual AI

Our platform excels at six canonical AI workflows that eliminate routine expert work:

| Workflow                  | Use Cases                                                        | Availability |
| :------------------------ | :--------------------------------------------------------------- | :----------- |
| **Basic Search**          | Tech Customer Support, Consulting Proposal Generator             | Self-Serve   |
| **Agentic Search**        | Drilling Operations Advisor, Supply Chain Risk Visualization     | Self-Serve   |
| **Root Cause Analysis**   | Device Log Error Analysis, Process Safety Incident Investigation | Enterprise   |
| **Deep Research**         | Patent Reasoning Agent, Clinical Trial Research Agent            | Enterprise   |
| **Task Execution**        | Equipment Failure Prediction, Maintenance Planning               | Enterprise   |
| **Structured Extraction** | Compliance Evidence Collection, Incident & Postmortem Analysis   | Enterprise   |

<Note>
  **Self-serve users** get immediate access to **Basic Search** and **Agentic Search** templates. These cover most Q\&A and multi-step retrieval use cases. Enterprise templates require a custom engagement—[contact us](https://contextual.ai/contact) to learn more.
</Note>

***

## What's in Agent Composer

Agent Composer is the core interface for building and configuring agents on Contextual AI. [Read the launch announcement](https://contextual.ai/blog/introducing-agent-composer) to learn how it reduces complex technical tasks from hours to minutes.

It provides:

* **Pre-built agent templates** — Start with Basic Search or Agentic Search (self-serve) or use specialized templates for Root Cause Analysis, Deep Research, Task Execution, and Structured Extraction (enterprise).
* **Prompt-based generator** — Describe your use case in natural language and let the system generate an agent configuration.
* **Visual workflow builder** — Drag-and-drop interface for customizing agent behavior, adding tools, and defining multi-step workflows (enterprise).
* **APIs and Python SDK** — Programmatic access for integration into existing applications and automation pipelines.

The diagram below shows the full scope of Agent Composer capabilities across industry solutions, agent configuration, tools, security, and enterprise knowledge sources:

<img alt="Agent Composer includes pre-built templates, a visual workflow builder, tools for ingestion and retrieval, planning, evaluation, memory, data connectors, and agentic extraction—with enterprise security and governance built in" />

***

## Key Capabilities

### Multi-step Reasoning

Agents can decompose complex problems, execute multiple retrieval and generation steps, and revise outputs based on intermediate results. Unlike simple RAG systems that do single-hop Q\&A, Contextual AI agents iteratively refine their understanding—retrieving additional context when needed and cross-referencing information across documents.

### Multi-tool Orchestration

Coordinate retrieval across multiple sources within a single workflow: internal documents, structured databases, logs, web search, and external APIs. The platform handles both unstructured data (PDFs, manuals, specifications) and structured data (databases, tables, spreadsheets) through a unified retrieval interface.

### Customizable Workflows and Outputs

Configure agents to produce structured outputs tailored to your needs: investigation reports with ranked hypotheses, compliance checklists, maintenance plans with specific sections and artifacts. Define output schemas, required fields, and formatting to match your existing workflows.

### Hybrid Agentic Behavior

Combine fully dynamic agent steps (where the LLM decides what to do based on context) with static workflow steps (where you define the exact sequence). This gives you control and predictability where you need it while retaining flexibility for complex, open-ended tasks.

***

## Example: Device Log Analysis (Enterprise)

Complex workflows like device log analysis require correlating data across multiple sources—test logs, process history, design specifications—to identify root causes. This type of multi-source investigation is where Contextual AI delivers the most value.

With the Root Cause Analysis template (enterprise), agents can:

* Retrieve from all relevant data sources simultaneously
* Generate and rank hypotheses based on evidence
* Produce structured investigation reports with citations

<img alt="Device log analysis workflow powered by Contextual AI: correlating test logs, process history, and specifications to identify root causes" />

***

## Get Started

Ready to see what Contextual AI can do for your team?

<CardGroup>
  <Card title="Start Here" icon="rocket" href="/quickstarts/getting-started">
    Sign up and create your first agent in minutes
  </Card>

  <Card title="Agent Composer" icon="wand-magic-sparkles" href="/quickstarts/agent-composer">
    Learn how to build custom agent workflows
  </Card>
</CardGroup>

<Note>
  **Self-serve** accounts include Basic Search and Agentic Search templates with full API access. For Root Cause Analysis, Deep Research, and other enterprise workflows, [contact our team](https://contextual.ai/contact).
</Note>


# Agentic Workflows
Source: https://docs.contextual.ai/reference/ac-agentic-workflows

Build dynamic, tool-using agents with Agent Composer

## Description

Agent Composer provides the `AgenticResearchStep` pattern for building agentic workflows that can dynamically select and execute tools. This separates research (tool use) from response generation for better control and observability.

## AgenticResearchStep Pattern

The recommended pattern for research-focused agents:

```yaml theme={null}
version: 0.1
inputs:
  query: str

outputs:
  response: str

nodes:
  create_message_history:
    type: CreateMessageHistoryStep
    input_mapping:
      query: __inputs__#query

  research:
    type: AgenticResearchStep
    ui_stream_types:
      retrievals: true
    config:
      tools_config:
        - name: search_docs
          description: |
            Search the datastore containing user-uploaded documents.
          step_config:
            type: SearchUnstructuredDataStep
            config:
              top_k: 50
              lexical_alpha: 0.1
              semantic_alpha: 0.9
              reranker: "ctxl-rerank-v2-instruct-multilingual-FP8"
              rerank_top_k: 12
              reranker_score_filter_threshold: 0.2

      agent_config:
        agent_loop:
          num_turns: 10
          parallel_tool_calls: false
          model_name_or_path: "vertex_ai/claude-sonnet-4-5@20250929"
          identity_guidelines_prompt: |
            You are a retrieval-augmented assistant created by Contextual AI.
          research_guidelines_prompt: |
            You have access to the following tool:
            - `search_docs` — Search the document datastore.

    input_mapping:
      message_history: create_message_history#message_history

  generate:
    type: GenerateFromResearchStep
    ui_stream_types:
      generation: true
    config:
      model_name_or_path: "vertex_ai/claude-sonnet-4-5@20250929"
      identity_guidelines_prompt: |
        You are a retrieval-augmented assistant created by Contextual AI.
      response_guidelines_prompt: |
        Write a concise, well-structured answer in Markdown.

    input_mapping:
      message_history: create_message_history#message_history
      research: research#research

  __outputs__:
    type: output
    input_mapping:
      response: generate#response
```

## Agent Loop Configuration

| Parameter                    | Description                                              |
| ---------------------------- | -------------------------------------------------------- |
| `num_turns`                  | Maximum number of tool-use iterations                    |
| `parallel_tool_calls`        | Whether the agent can call multiple tools simultaneously |
| `model_name_or_path`         | The LLM to use for reasoning and planning                |
| `identity_guidelines_prompt` | Defines who the agent is and its purpose                 |
| `research_guidelines_prompt` | Instructions for tool use strategy                       |

## Agent Loop Prompts

| Prompt                       | Used By                    | Description                     |
| ---------------------------- | -------------------------- | ------------------------------- |
| `identity_guidelines_prompt` | Both steps                 | Defines who the agent is        |
| `research_guidelines_prompt` | `AgenticResearchStep`      | Instructions for tool selection |
| `response_guidelines_prompt` | `GenerateFromResearchStep` | Output format instructions      |

## Example Prompts

```yaml theme={null}
identity_guidelines_prompt: |
  You are an expert research assistant specializing in technical documentation.
  You work for Acme Corp and help employees find information in internal docs.

research_guidelines_prompt: |
  Use the search_docs tool to find relevant information.
  - For factual questions, search once with precise terms
  - For complex topics, search multiple times with different queries
  - Stop searching when you have sufficient information

response_guidelines_prompt: |
  Format your response as follows:
  1. Start with a direct answer
  2. Provide supporting details with citations
  3. Use markdown formatting for readability
  4. Include a "Sources" section at the end
```

## Related

* [Tools Configuration](/reference/ac-tools-config)
* [Step Reference Catalog](/how-to-guides/ac-yaml-reference)


# Code Execution
Source: https://docs.contextual.ai/reference/ac-code-execution

Execute Python code in Agent Composer workflows

## Description

`CodeExecutionStep` enables your agents to execute Python code in a sandboxed environment using Gemini's native code execution capabilities. This is useful for calculations, data transformations, and dynamic logic that can't be expressed in the workflow graph.

## CodeExecutionStep

```yaml theme={null}
code_exec:
  type: CodeExecutionStep
  config:
    model: "gemini-2.5-flash"
  input_mapping:
    query: __inputs__#query
```

## Configuration Parameters

| Parameter | Type  | Required | Default              | Description                                |
| --------- | ----- | -------- | -------------------- | ------------------------------------------ |
| `model`   | `str` | No       | `"gemini-2.5-flash"` | The Gemini model to use for code execution |

## Inputs

| Input   | Type  | Description                                 |
| ------- | ----- | ------------------------------------------- |
| `query` | `str` | The request describing what code to execute |

## Outputs

| Output        | Type                  | Description                      |
| ------------- | --------------------- | -------------------------------- |
| `code_result` | `CodeExecutionResult` | The result of the code execution |

## Example: Dynamic Calculations

```yaml theme={null}
nodes:
  # Extract numbers from the query
  extract_data:
    type: LanguageModelStep
    config:
      prompt_template: |
        Extract any numerical data from this query and format as JSON:
        Query: {query}
      model_id: "vertex_ai/gemini-2.0-flash"
    input_mapping:
      query: __inputs__#query

  # Perform calculations
  calculate:
    type: CodeExecutionStep
    config:
      model: "gemini-2.5-flash"
    input_mapping:
      query: calculation_prompt#output

  # Generate final response
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query
      calculation_result: calculate#code_result
```

## Example: Data Transformation

```yaml theme={null}
nodes:
  # Get structured data
  fetch_data:
    type: WebhookStep
    config:
      webhook_url: "https://api.example.com/data"
      method: GET
    input_mapping: {}

  # Transform the data with code
  transform:
    type: CodeExecutionStep
    config:
      model: "gemini-2.5-flash"
    input_mapping:
      query: transform_request#output

  __outputs__:
    type: output
    input_mapping:
      transformed_data: transform#code_result
```

## Using as an Agentic Tool

Configure code execution as a tool for research agents:

```yaml theme={null}
research:
  type: AgenticResearchStep
  config:
    tools_config:
      - name: search_docs
        description: Search documentation for information.
        step_config:
          type: SearchUnstructuredDataStep
          config:
            top_k: 50

      - name: run_calculation
        description: |
          Execute Python code to perform calculations.
          Use for math, data analysis, or generating charts.
        step_config:
          type: CodeExecutionStep
          config:
            model: "gemini-2.5-flash"

    agent_config:
      agent_loop:
        num_turns: 10
        model_name_or_path: "vertex_ai/claude-sonnet-4-5@20250929"
        research_guidelines_prompt: |
          You have access to:
          - `search_docs` — Find information in documents
          - `run_calculation` — Execute Python code for calculations
          
          Use run_calculation when you need to:
          - Perform mathematical operations
          - Analyze or transform data
          - Generate visualizations

  input_mapping:
    message_history: create_message_history#message_history
```

## Security

Code execution runs in a sandboxed environment with:

* No network access
* No file system access
* Limited execution time
* Memory constraints

This ensures safe execution of dynamically generated code.

## Related

* [Webhooks](/reference/ac-webhooks)
* [MCP Integration](/reference/ac-mcp-integration)
* [Agentic Workflows](/reference/ac-agentic-workflows)


# Conditional Nodes
Source: https://docs.contextual.ai/reference/ac-conditional-nodes

Branching logic in Agent Composer workflows

## Description

Conditional nodes execute one of multiple subgraphs based on a runtime condition. This enables workflows that adapt their behavior based on intermediate results.

## Syntax

```yaml theme={null}
conditional_node:
  type: ConditionalStep
  config:
    inputs:
      quality_score: float
      documents: List[str]
    outputs:
      result: str
    variable: quality_score
    branches:
      - condition: ">= 0.8"
        executable: HighQualityProcessor
        input_mapping:
          documents: __inputs__#documents
        output_mapping:
          __outputs__#result: processed_documents
      - condition: "< 0.8"
        executable: LowQualityProcessor
        input_mapping:
          documents: __inputs__#documents
        output_mapping:
          __outputs__#result: processed_documents
  input_mapping:
    quality_score: quality_checker#score
    documents: retriever#documents
```

## Config Fields

| Field      | Description                                       |
| ---------- | ------------------------------------------------- |
| `inputs`   | Input types for the conditional node              |
| `outputs`  | Output types for the conditional node             |
| `variable` | The input variable to evaluate conditions against |
| `branches` | List of condition/executable pairs                |

## Condition Operators

| Operator | Description           |
| -------- | --------------------- |
| `==`     | Equality              |
| `!=`     | Inequality            |
| `>=`     | Greater than or equal |
| `<=`     | Less than or equal    |
| `>`      | Greater than          |
| `<`      | Less than             |

## Branch Fields

| Field            | Description                                                |
| ---------------- | ---------------------------------------------------------- |
| `condition`      | Boolean predicate (right-hand side only, e.g., `">= 0.8"`) |
| `executable`     | Subgraph name or node type to execute                      |
| `input_mapping`  | Maps conditional node inputs to branch inputs              |
| `output_mapping` | Maps branch outputs to conditional node outputs            |

## Example: Route by Query Type

```yaml theme={null}
# Subgraphs for different query types
factual_handler:
  inputs:
    query: str
  outputs:
    response: str
  nodes:
    search:
      type: SearchUnstructuredDataStep
      config:
        temperature: 0.1
      input_mapping:
        query: __inputs__#query
    # ... generate response

creative_handler:
  inputs:
    query: str
  outputs:
    response: str
  nodes:
    generate:
      type: GenerationStep
      config:
        temperature: 0.8
      input_mapping:
        query: __inputs__#query
    # ... generate response

# Main workflow
inputs:
  query: str

nodes:
  classify:
    type: LanguageModelStep
    config:
      prompt_template: |
        Classify this query as 'factual' or 'creative'.
        Query: {query}
        Return only: factual or creative
      model_id: "vertex_ai/gemini-2.0-flash"
    input_mapping:
      query: __inputs__#query

  route:
    type: ConditionalStep
    config:
      inputs:
        query: str
        query_type: str
      outputs:
        response: str
      variable: query_type
      branches:
        - condition: "== factual"
          executable: factual_handler
          input_mapping:
            query: __inputs__#query
          output_mapping:
            __outputs__#response: response
        - condition: "== creative"
          executable: creative_handler
          input_mapping:
            query: __inputs__#query
          output_mapping:
            __outputs__#response: response
    input_mapping:
      query: __inputs__#query
      query_type: classify#response
```

## Related

* [Subgraphs](/reference/ac-subgraphs)
* [YAML Format](/reference/ac-yaml-format)


# Config Overrides
Source: https://docs.contextual.ai/reference/ac-config-overrides

Dynamic configuration at runtime in Agent Composer

## Description

Config overrides allow configuration parameters to be determined dynamically at execution time, rather than being fixed in the YAML. This enables workflows where configuration values depend on runtime inputs or outputs from other nodes.

## Syntax

Use `config_overrides` to source configuration values from graph inputs or node outputs:

```yaml theme={null}
search_node:
  type: SearchUnstructuredDataStep
  config:
    filter_retrievals: true
  config_overrides:
    top_k: __inputs__#top_k
  input_mapping:
    query: __inputs__#query
```

## Sourcing from Graph Inputs

Override values can come from graph-level inputs:

```yaml theme={null}
inputs:
  query: str
  top_k: int

nodes:
  search:
    type: SearchUnstructuredDataStep
    config_overrides:
      top_k: __inputs__#top_k
    input_mapping:
      query: __inputs__#query
```

## Sourcing from Node Outputs

Override values can also come from outputs of other nodes:

```yaml theme={null}
nodes:
  constant_k:
    type: ConstantStep
    config:
      value: 20

  search:
    type: SearchUnstructuredDataStep
    config_overrides:
      top_k: constant_k#output
    input_mapping:
      query: __inputs__#query
```

## Example: Dynamic Temperature

```yaml theme={null}
nodes:
  # Determine temperature based on query type
  temperature_selector:
    type: LanguageModelStep
    config:
      prompt_template: |
        Analyze this query and return a temperature value between 0 and 1.
        For factual queries, use 0.1. For creative queries, use 0.8.
        Query: {query}
        Return only the number.
      model_id: "vertex_ai/gemini-2.0-flash"
    input_mapping:
      query: __inputs__#query

  generate:
    type: GenerationStep
    config_overrides:
      temperature: temperature_selector#response
    input_mapping:
      message_history: create_message_history#message_history
```

## Combining Config and Config Overrides

Static and dynamic configuration can be combined on the same node:

```yaml theme={null}
search:
  type: SearchUnstructuredDataStep
  config:
    # Static configuration
    lexical_alpha: 0.1
    semantic_alpha: 0.9
    reranker: "ctxl-rerank-v2-instruct-multilingual-FP8"
  config_overrides:
    # Dynamic configuration
    top_k: dynamic_k#output
    rerank_top_k: dynamic_rerank_k#output
  input_mapping:
    query: __inputs__#query
```

## Related

* [YAML Format](/reference/ac-yaml-format)
* [Input Mapping](/reference/ac-input-mapping)


# External Integrations
Source: https://docs.contextual.ai/reference/ac-external-integrations

Connect Agent Composer to external systems and services

## Description

Agent Composer provides multiple ways to integrate with external systems, enabling agents to take actions, retrieve data, and interact with enterprise services.

## Integration Options

| Integration        | Use Case                               | Step Type             |
| ------------------ | -------------------------------------- | --------------------- |
| **MCP**            | Connect to MCP-compatible services     | `MCPClientStep`       |
| **Webhooks**       | Call REST APIs and trigger actions     | `WebhookStep`         |
| **Code Execution** | Run Python code for calculations       | `CodeExecutionStep`   |
| **Salesforce**     | Query Salesforce data                  | `SalesforceSOSLStep`  |
| **Web Search**     | Search the web for current information | `WebSearchStep`       |
| **Other Agents**   | Query other Contextual AI agents       | `ContextualAgentStep` |

## Salesforce Integration

Use `SalesforceSOSLStep` to execute SOSL searches against Salesforce:

```yaml theme={null}
salesforce_search:
  type: SalesforceSOSLStep
  config:
    client_id: "${SF_CLIENT_ID}"
    client_secret: "${SF_CLIENT_SECRET}"
    login_url: "https://login.salesforce.com"
    objects_to_return: "Case(Id, Subject, Status, Priority, Account.Name)"
    limit: 250
  input_mapping:
    query: __inputs__#query
```

### Salesforce Configuration

| Parameter           | Type  | Required | Description                                |
| ------------------- | ----- | -------- | ------------------------------------------ |
| `client_id`         | `str` | Yes\*    | Salesforce connected app client ID         |
| `client_secret`     | `str` | Yes\*    | Salesforce connected app client secret     |
| `login_url`         | `str` | No       | Salesforce login URL (default: production) |
| `objects_to_return` | `str` | No       | SOSL RETURNING clause                      |
| `limit`             | `int` | No       | Maximum results (default: `250`)           |
| `timeout`           | `int` | No       | Request timeout (default: `30`)            |

\*Alternative: Use `username`, `password`, and `security_token` for user-based auth.

## Web Search

Use `WebSearchStep` for real-time web information:

```yaml theme={null}
web_search:
  type: WebSearchStep
  config:
    model: "gemini-2.5-flash"
  input_mapping:
    query: __inputs__#query
```

### Web Search Outputs

| Output       | Type        | Description                 |
| ------------ | ----------- | --------------------------- |
| `web_result` | `WebResult` | Search results with sources |

## Query Other Agents

Use `ContextualAgentStep` to retrieve information from other Contextual AI agents:

```yaml theme={null}
query_specialist:
  type: ContextualAgentStep
  config:
    agent_ids:
      - "agent-id-for-hr-docs"
      - "agent-id-for-legal-docs"
  input_mapping:
    query: __inputs__#query
```

This enables multi-agent architectures where specialized agents handle specific domains.

## Vision Language Models

Use `VisionLanguageModelStep` for multimodal inputs:

```yaml theme={null}
analyze_image:
  type: VisionLanguageModelStep
  config:
    model_id: "vertex_ai/gemini-2.0-flash"
    temperature: 0.0
    max_tokens: 4096
  input_mapping:
    query: __inputs__#query
    images: image_extractor#extracted_images
```

### VLM Configuration

| Parameter     | Type    | Default                        | Description             |
| ------------- | ------- | ------------------------------ | ----------------------- |
| `model_id`    | `str`   | `"vertex_ai/gemini-2.0-flash"` | Vision-capable model    |
| `temperature` | `float` | `0.0`                          | Response creativity     |
| `max_tokens`  | `int`   | `4096`                         | Maximum response length |

## Example: Multi-System Agent

```yaml theme={null}
version: 0.1
inputs:
  query: str

outputs:
  response: str

nodes:
  create_message_history:
    type: CreateMessageHistoryStep
    input_mapping:
      query: __inputs__#query

  research:
    type: AgenticResearchStep
    ui_stream_types:
      retrievals: true
    config:
      tools_config:
        # Internal documentation
        - name: search_docs
          description: Search internal documentation and policies.
          step_config:
            type: SearchUnstructuredDataStep
            config:
              top_k: 50

        # CRM data via MCP
        - name: search_crm
          description: Look up customer records and history.
          step_config:
            type: MCPClientStep
            config:
              server_url: "https://crm.example.com/mcp"
              tool_name: "search"
              tool_args: '{"query": "$query"}'
              auth_headers:
                Authorization: "Bearer ${CRM_TOKEN}"

        # Salesforce cases
        - name: search_salesforce
          description: Find support cases in Salesforce.
          step_config:
            type: SalesforceSOSLStep
            config:
              client_id: "${SF_CLIENT_ID}"
              client_secret: "${SF_CLIENT_SECRET}"
              objects_to_return: "Case(Id, Subject, Status)"

        # Real-time web info
        - name: search_web
          description: Search the web for current information.
          step_config:
            type: WebSearchStep

      agent_config:
        agent_loop:
          num_turns: 10
          model_name_or_path: "vertex_ai/claude-sonnet-4-5@20250929"
          research_guidelines_prompt: |
            Choose the appropriate tool based on the query:
            - `search_docs` for policies and procedures
            - `search_crm` for customer information
            - `search_salesforce` for support cases
            - `search_web` for current events or external info

    input_mapping:
      message_history: create_message_history#message_history

  generate:
    type: GenerateFromResearchStep
    ui_stream_types:
      generation: true
    config:
      model_name_or_path: "vertex_ai/claude-sonnet-4-5@20250929"
    input_mapping:
      message_history: create_message_history#message_history
      research: research#research

  __outputs__:
    type: output
    input_mapping:
      response: generate#response
```

## Related

* [MCP Integration](/reference/ac-mcp-integration)
* [Webhooks](/reference/ac-webhooks)
* [Code Execution](/reference/ac-code-execution)
* [Agentic Workflows](/reference/ac-agentic-workflows)


# Input Mapping
Source: https://docs.contextual.ai/reference/ac-input-mapping

Connect nodes together in Agent Composer workflows

## Description

Input mapping defines how nodes connect to each other in an Agent Composer workflow. It specifies which outputs from previous nodes flow into the inputs of subsequent nodes.

## Syntax

Input mappings use the syntax `source_node#output_key`:

```yaml theme={null}
input_mapping:
  current_node_input: earlier_node#output_key
```

This connects the `output_key` output from `earlier_node` to the `current_node_input` input of the current node.

## Accessing Graph Inputs

Every graph has an implicit input node named `__inputs__`. Access graph-level inputs via:

```yaml theme={null}
input_mapping:
  query: __inputs__#query
```

## Example

```yaml theme={null}
nodes:
  # First node receives input from the graph
  search:
    type: SearchUnstructuredDataStep
    input_mapping:
      query: __inputs__#query

  # Second node receives input from the first node
  rerank:
    type: RerankRetrievalsStep
    input_mapping:
      query: __inputs__#query
      retrievals: search#retrievals

  # Third node receives inputs from multiple nodes
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query
      retrievals: rerank#retrievals

  # Output node collects final outputs
  __outputs__:
    type: output
    input_mapping:
      response: generate#response
```

## Rules

* All inputs of a node must be connected
* Unused outputs are allowed
* A node can receive inputs from multiple source nodes
* The same output can be connected to multiple downstream nodes

## Multiple Inputs from Same Source

You can connect multiple inputs from the same source node:

```yaml theme={null}
generate:
  type: ResponseGenerationStep
  input_mapping:
    query: __inputs__#query
    retrievals: search#retrievals
    translate_needed: translate#translate_needed
    detected_language: translate#detected_language
```

## Related

* [YAML Format](/reference/ac-yaml-format)
* [Config Overrides](/reference/ac-config-overrides)


# MCP Integration
Source: https://docs.contextual.ai/reference/ac-mcp-integration

Connect to Model Context Protocol servers in Agent Composer

## Description

Agent Composer supports the Model Context Protocol (MCP), allowing your agents to execute tools on external MCP servers. This enables integration with CRM systems, databases, APIs, and other enterprise services.

## MCPClientStep

Use `MCPClientStep` to execute tools on MCP servers:

```yaml theme={null}
mcp_call:
  type: MCPClientStep
  config:
    server_url: "https://mcp-server.example.com"
    tool_name: "search_accounts"
    tool_args: '{"query": "$query"}'
    auth_headers:
      Authorization: "Bearer ${API_TOKEN}"
  input_mapping:
    query: __inputs__#query
```

## Configuration Parameters

| Parameter            | Type   | Required | Description                                   |
| -------------------- | ------ | -------- | --------------------------------------------- |
| `server_url`         | `str`  | Yes      | URL of the MCP server                         |
| `tool_name`          | `str`  | Yes      | Name of the tool to execute                   |
| `tool_args`          | `str`  | Yes      | JSON template for tool arguments              |
| `transport_type`     | `str`  | No       | Transport protocol (default: `"http"`)        |
| `connection_timeout` | `int`  | No       | Connection timeout in seconds (default: `30`) |
| `server_name`        | `str`  | No       | Optional server identifier                    |
| `auth_headers`       | `Dict` | No       | Authentication headers                        |

## Dynamic Tool Arguments

Use `$variable` syntax in `tool_args` to inject runtime values:

```yaml theme={null}
mcp_call:
  type: MCPClientStep
  config:
    server_url: "https://crm.example.com/mcp"
    tool_name: "get_customer"
    tool_args: '{"customer_id": "$customer_id", "include_history": true}'
  input_mapping:
    customer_id: extract_id#customer_id
```

## Using MCP as an Agentic Tool

Configure MCP as a tool for `AgenticResearchStep`:

```yaml theme={null}
research:
  type: AgenticResearchStep
  config:
    tools_config:
      - name: search_crm
        description: |
          Search customer records in the CRM system.
          Returns customer details, order history, and support tickets.
        step_config:
          type: MCPClientStep
          config:
            server_url: "https://crm.example.com/mcp"
            tool_name: "search_customers"
            tool_args: '{"query": "$query"}'
            auth_headers:
              Authorization: "Bearer ${CRM_API_TOKEN}"

      - name: search_docs
        description: Search internal documentation.
        step_config:
          type: SearchUnstructuredDataStep
          config:
            top_k: 50

    agent_config:
      agent_loop:
        num_turns: 10
        model_name_or_path: "vertex_ai/claude-sonnet-4-5@20250929"
        research_guidelines_prompt: |
          You have access to:
          - `search_crm` — Look up customer information
          - `search_docs` — Search documentation

  input_mapping:
    message_history: create_message_history#message_history
```

## Authentication

### Bearer Token

```yaml theme={null}
config:
  auth_headers:
    Authorization: "Bearer ${API_TOKEN}"
```

### API Key

```yaml theme={null}
config:
  auth_headers:
    X-API-Key: "${API_KEY}"
```

### Custom Headers

```yaml theme={null}
config:
  auth_headers:
    Authorization: "Bearer ${TOKEN}"
    X-Tenant-ID: "${TENANT_ID}"
    X-Request-Source: "contextual-agent"
```

## Secret Handling

Secrets (API keys, tokens) are automatically encrypted when saved. After encryption, secrets are replaced with unique IDs (e.g., `CTXL_AGENT_SECRET_ohs3gpu6llyt`). To update a secret, replace the secret ID with the new value and save.

## Outputs

| Output       | Type             | Description                         |
| ------------ | ---------------- | ----------------------------------- |
| `mcp_result` | `Dict[str, Any]` | The result returned by the MCP tool |

## Example: Multi-System Integration

```yaml theme={null}
nodes:
  # Get customer from CRM
  get_customer:
    type: MCPClientStep
    config:
      server_url: "https://crm.example.com/mcp"
      tool_name: "get_customer"
      tool_args: '{"email": "$email"}'
      auth_headers:
        Authorization: "Bearer ${CRM_TOKEN}"
    input_mapping:
      email: extract_email#email

  # Get orders from order system
  get_orders:
    type: MCPClientStep
    config:
      server_url: "https://orders.example.com/mcp"
      tool_name: "get_orders"
      tool_args: '{"customer_id": "$customer_id"}'
      auth_headers:
        Authorization: "Bearer ${ORDERS_TOKEN}"
    input_mapping:
      customer_id: get_customer#mcp_result

  # Generate response with all context
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query
      customer_info: get_customer#mcp_result
      order_history: get_orders#mcp_result
```

## Related

* [Webhooks](/reference/ac-webhooks)
* [Tools Configuration](/reference/ac-tools-config)
* [Agentic Workflows](/reference/ac-agentic-workflows)


# Agent Composer Overview
Source: https://docs.contextual.ai/reference/ac-overview

Build custom agent workflows with Agent Composer

## Description

Agent Composer is a framework that allows you to compose custom query path implementations using pre-made building blocks. By combining primitives such as search tools, third-party API/MCP tools, and various LLMs, you can construct arbitrary computational graphs and configure them to build specialized agents.

<Note>
  Template agents (Basic Search and Agentic Search) are available for self-serve users. Full Agent Composer capabilities—including the visual workflow builder for custom workflows, YAML customization, and the prompt-based workflow generator—are available in public preview for enterprise users.
</Note>

<Card title="Read the launch announcement" icon="newspaper" href="https://contextual.ai/blog/introducing-agent-composer">
  Learn how Agent Composer reduces complex technical tasks from hours to minutes.
</Card>

## Two Ways to Build

The framework offers two ways to construct workflows:

1. **YAML Configuration**: Specify a YAML with a specific format describing the graph and its configuration. Enter this YAML in the "Agent Composer" tab during agent creation.

2. **Visual Workflow Builder**: Use the visual frontend builder, which internally translates to YAML.

## Key Concepts

| Concept               | Description                                                           |
| --------------------- | --------------------------------------------------------------------- |
| **Nodes**             | Basic operations in the graph (search, generate, transform, etc.)     |
| **Input Mapping**     | How nodes connect to each other using `source_node#output_key` syntax |
| **Config**            | Configuration parameters passed to step constructors                  |
| **Subgraphs**         | Reusable components that can be referenced in larger workflows        |
| **Conditional Nodes** | Execute different paths based on runtime conditions                   |
| **UI Stream Types**   | Control what data streams to the UI during execution                  |

## Example: Minimal Agent

```yaml theme={null}
version: 0.1
inputs:
  query: str

outputs:
  response: str

nodes:
  search:
    type: SearchUnstructuredDataStep
    input_mapping:
      query: __inputs__#query

  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query
      retrievals: search#retrievals

  __outputs__:
    type: output
    input_mapping:
      response: generate#response
```

This minimal example:

* Accepts a `query` string as input
* Searches the datastore for relevant documents
* Generates a response based on the query and retrieved documents
* Returns the response as output

## Related

* [YAML Format Reference](/reference/ac-yaml-format)
* [Input Mapping](/reference/ac-input-mapping)
* [Agentic Workflows](/reference/ac-agentic-workflows)
* [Step Reference Catalog](/how-to-guides/ac-yaml-reference)


# Subgraphs
Source: https://docs.contextual.ai/reference/ac-subgraphs

Reusable workflow components in Agent Composer

## Description

Subgraphs are reusable components that can be referenced in larger workflows. They allow you to define common patterns once and use them multiple times, improving maintainability and reducing duplication.

## Creating Subgraphs

Define subgraphs at the same level as the main graph with their own `inputs`, `outputs`, and `nodes`:

```yaml theme={null}
# Define a reusable retrieval subgraph
document_retrieval:
  inputs:
    query: str
    threshold: float
  outputs:
    documents: List[str]
    quality_score: float
  nodes:
    search:
      type: SearchUnstructuredDataStep
      input_mapping:
        query: __inputs__#query
    
    quality_check:
      type: QualityCheckStep
      config:
        threshold: 0.7
      input_mapping:
        results: search#retrievals
    
    __outputs__:
      type: output
      input_mapping:
        documents: search#retrievals
        quality_score: quality_check#score
```

## Using Subgraphs

Reference subgraphs using the `subgraph:` prefix in the type field:

```yaml theme={null}
# Main workflow using the subgraph
inputs:
  user_query: str

outputs:
  final_result: str

nodes:
  constant_threshold:
    type: ConstantStep
    config:
      value: 0.8

  retriever:
    type: subgraph:document_retrieval
    input_mapping:
      query: __inputs__#user_query
      threshold: constant_threshold#output

  __outputs__:
    type: output
    input_mapping:
      final_result: retriever#documents
```

## Subgraph Reference Syntax

```yaml theme={null}
node_name:
  type: subgraph:subgraph_name
  input_mapping:
    subgraph_input: source_node#output
```

## Features

| Feature           | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| **Nesting**       | Subgraphs can contain other subgraphs                          |
| **Reusability**   | One subgraph can be called multiple times in the same workflow |
| **Encapsulation** | Internal node names don't conflict with parent graph           |
| **Typed I/O**     | Subgraphs define their own typed inputs and outputs            |

## Example: Multiple Subgraph Calls

```yaml theme={null}
# Subgraph definition
search_and_rerank:
  inputs:
    query: str
  outputs:
    retrievals: Retrievals
  nodes:
    search:
      type: SearchUnstructuredDataStep
      input_mapping:
        query: __inputs__#query
    rerank:
      type: RerankRetrievalsStep
      input_mapping:
        query: __inputs__#query
        retrievals: search#retrievals
    __outputs__:
      type: output
      input_mapping:
        retrievals: rerank#retrievals

# Main workflow calling the subgraph twice
inputs:
  query: str

outputs:
  response: str

nodes:
  # First call with original query
  primary_search:
    type: subgraph:search_and_rerank
    input_mapping:
      query: __inputs__#query

  # Second call with expanded query
  expanded_search:
    type: subgraph:search_and_rerank
    input_mapping:
      query: query_expansion#expanded_query

  # Merge results
  merge:
    type: MergeRetrievalsStep
    input_mapping:
      retrievals1: primary_search#retrievals
      retrievals2: expanded_search#retrievals
```

## Related

* [YAML Format](/reference/ac-yaml-format)
* [Conditional Nodes](/reference/ac-conditional-nodes)


# Tools Configuration
Source: https://docs.contextual.ai/reference/ac-tools-config

Configure tools for agentic workflows in Agent Composer

## Description

Tools configuration defines the tools available to an `AgenticResearchStep`. Each tool requires a name, description, and either `step_config` (for simple tools) or `graph_config` (for complex multi-step tools).

## Tool Definition

Each tool in `tools_config` requires:

| Field          | Description                                       |
| -------------- | ------------------------------------------------- |
| `name`         | Unique identifier for the tool                    |
| `description`  | Description shown to the LLM for tool selection   |
| `step_config`  | Single-step tool configuration                    |
| `graph_config` | Multi-step tool configuration (for complex tools) |

## Using step\_config (Simple Tools)

For tools that map to a single step:

```yaml theme={null}
tools_config:
  - name: search_docs
    description: Search the document datastore for relevant information.
    step_config:
      type: SearchUnstructuredDataStep
      config:
        top_k: 50
        lexical_alpha: 0.1
        semantic_alpha: 0.9
        reranker: "ctxl-rerank-v2-instruct-multilingual-FP8"
        rerank_top_k: 12
        reranker_score_filter_threshold: 0.2
```

## Using graph\_config (Complex Tools)

For tools that require multiple steps:

```yaml theme={null}
tools_config:
  - name: search_and_summarize
    description: Search documents and summarize the results.
    graph_config:
      version: 0.1
      inputs:
        query: str
      outputs:
        summary: str
      nodes:
        search:
          type: SearchUnstructuredDataStep
          config:
            top_k: 20
          input_mapping:
            query: __inputs__#query
        
        summarize:
          type: LanguageModelStep
          config:
            prompt_template: |
              Summarize these search results for the query "{query}":
              {retrievals}
            model_id: "vertex_ai/gemini-2.0-flash"
          input_mapping:
            query: __inputs__#query
            retrievals: search#retrievals
        
        __outputs__:
          type: output
          input_mapping:
            summary: summarize#response
```

## Multiple Tools

You can configure multiple tools for an agent to choose from:

```yaml theme={null}
tools_config:
  - name: search_docs
    description: |
      Search internal documentation. Use for questions about 
      company policies, procedures, and technical guides.
    step_config:
      type: SearchUnstructuredDataStep
      config:
        top_k: 50

  - name: search_web
    description: |
      Search the web for current information. Use for questions
      about external topics, news, or publicly available data.
    step_config:
      type: WebSearchStep
      config:
        model: "gemini-2.5-flash"

  - name: query_database
    description: |
      Query the structured database. Use for questions about
      metrics, statistics, or tabular data.
    step_config:
      type: QueryStructuredDatastoreStep
```

## Tool Descriptions Best Practices

Good tool descriptions help the LLM choose the right tool:

```yaml theme={null}
# Good: Specific about when to use
description: |
  Search the HR policy database. Use this tool for questions about:
  - Employee benefits and compensation
  - Time off and leave policies  
  - Performance review processes
  - Hiring and onboarding procedures

# Bad: Too vague
description: Search for HR stuff.
```

## Recommended Search Config

For `SearchUnstructuredDataStep` tools, these settings provide good baseline performance:

```yaml theme={null}
step_config:
  type: SearchUnstructuredDataStep
  config:
    top_k: 50
    lexical_alpha: 0.1
    semantic_alpha: 0.9
    reranker: "ctxl-rerank-v2-instruct-multilingual-FP8"
    rerank_top_k: 12
    reranker_score_filter_threshold: 0.2
```

## MCP Tools

You can also configure MCP (Model Context Protocol) server tools:

```yaml theme={null}
tools_config:
  - name: crm_search
    description: Search customer records in the CRM system.
    step_config:
      type: MCPClientStep
      config:
        server_url: "https://mcp-server.example.com"
        tool_name: "search_customers"
        tool_args: '{"query": "$query"}'
        auth_headers:
          Authorization: "Bearer ${CRM_API_TOKEN}"
```

## Related

* [Agentic Workflows](/reference/ac-agentic-workflows)
* [Step Reference Catalog](/how-to-guides/ac-yaml-reference)


# UI Stream Types
Source: https://docs.contextual.ai/reference/ac-ui-stream-types

Control what data streams to the UI in Agent Composer

## Description

UI stream types configure which data a node streams to the user interface during execution. This controls what users see in real-time as the agent processes their query.

## Syntax

Configure UI streaming via `ui_stream_types` on a node:

```yaml theme={null}
generate_response:
  type: ResponseGenerationStep
  ui_stream_types:
    generation: true
    retrievals: true
  input_mapping:
    retrievals: search#retrievals
    query: __inputs__#query
```

## Supported Stream Types

| Stream Type           | Description                                   |
| --------------------- | --------------------------------------------- |
| `RETRIEVALS`          | Search results and citations                  |
| `GENERATION`          | LLM response text (streams as it's generated) |
| `QUERY_REFORMULATION` | Query transformations and expansions          |
| `ATTRIBUTION`         | Citation attribution data                     |
| `GROUNDEDNESS`        | Groundedness scores for the response          |

## Example: Full Response Pipeline

```yaml theme={null}
nodes:
  search:
    type: SearchUnstructuredDataStep
    ui_stream_types:
      retrievals: true
      query_reformulation: true
    input_mapping:
      query: __inputs__#query

  generate:
    type: ResponseGenerationStep
    ui_stream_types:
      generation: true
      attribution: true
      groundedness: true
    input_mapping:
      retrievals: search#retrievals
      query: __inputs__#query
```

## Multiple Nodes with Same Stream Type

Multiple nodes can have the same UI streaming type. Events stream sequentially in execution order:

```yaml theme={null}
nodes:
  research:
    type: AgenticResearchStep
    ui_stream_types:
      retrievals: true
    # ... config

  generate:
    type: GenerateFromResearchStep
    ui_stream_types:
      generation: true
    # ... config
```

## Multi-Output Workflows

For workflows with multiple outputs, use `ui_output` at the root level to designate which output displays in the UI:

```yaml theme={null}
outputs:
  response: str
  metadata: Dict[str, Any]
  debug_info: str

ui_output: response
```

## Default Behavior

Each step type has default UI stream types. Check the [Step Reference Catalog](/how-to-guides/ac-yaml-reference) for defaults. Common defaults:

| Step Type                    | Default Streams                                           |
| ---------------------------- | --------------------------------------------------------- |
| `SearchUnstructuredDataStep` | `QUERY_REFORMULATION`                                     |
| `ResponseGenerationStep`     | `RETRIEVALS`, `GENERATION`, `ATTRIBUTION`, `GROUNDEDNESS` |
| `AgenticResearchStep`        | `RETRIEVALS`                                              |
| `GenerateFromResearchStep`   | `GENERATION`                                              |

## Related

* [YAML Format](/reference/ac-yaml-format)
* [Step Reference Catalog](/how-to-guides/ac-yaml-reference)


# Webhooks
Source: https://docs.contextual.ai/reference/ac-webhooks

Execute HTTP webhook calls in Agent Composer workflows

## Description

`WebhookStep` enables your agents to make HTTP calls to external APIs and services. Use webhooks to trigger actions, send notifications, update external systems, or retrieve data from REST APIs.

## WebhookStep

```yaml theme={null}
webhook:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/endpoint"
    method: POST
    auth_token: "${API_TOKEN}"
    timeout: 30
  input_mapping:
    context_data: data_node#output
```

## Configuration Parameters

| Parameter        | Type         | Required | Default          | Description                                 |
| ---------------- | ------------ | -------- | ---------------- | ------------------------------------------- |
| `webhook_url`    | `str`        | Yes      | -                | The URL to call                             |
| `method`         | `HttpMethod` | No       | `POST`           | HTTP method (GET, POST, PUT, DELETE, PATCH) |
| `auth_token`     | `str`        | No       | -                | Bearer token for authentication             |
| `timeout`        | `int`        | No       | `30`             | Request timeout in seconds                  |
| `retries`        | `int`        | No       | `2`              | Number of retry attempts                    |
| `static_headers` | `Dict`       | No       | -                | Additional HTTP headers                     |
| `webhook_name`   | `str`        | No       | `"webhook-step"` | Identifier for logging                      |

## HTTP Methods

```yaml theme={null}
# GET request
get_data:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/users/${user_id}"
    method: GET
    auth_token: "${API_TOKEN}"

# POST request
create_ticket:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/tickets"
    method: POST
    auth_token: "${API_TOKEN}"
  input_mapping:
    context_data: ticket_data#output

# PUT request
update_record:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/records/${record_id}"
    method: PUT
    auth_token: "${API_TOKEN}"
  input_mapping:
    context_data: updated_data#output
```

## Authentication

### Bearer Token

```yaml theme={null}
config:
  auth_token: "${API_TOKEN}"
```

### Custom Headers

```yaml theme={null}
config:
  static_headers:
    Authorization: "Basic ${ENCODED_CREDENTIALS}"
    X-API-Key: "${API_KEY}"
    Content-Type: "application/json"
```

## Input Data

The `context_data` input is sent as the request body for POST/PUT/PATCH requests:

```yaml theme={null}
nodes:
  # Prepare the data to send
  prepare_data:
    type: JSONCreatorStep
    config:
      schema: '{"customer_id": $customer_id, "message": $message, "priority": "high"}'
    input_mapping:
      customer_id: extract#customer_id
      message: generate#response

  # Send via webhook
  send_notification:
    type: WebhookStep
    config:
      webhook_url: "https://api.example.com/notifications"
      method: POST
      auth_token: "${API_TOKEN}"
    input_mapping:
      context_data: prepare_data#json
```

## Outputs

| Output           | Type                       | Description                        |
| ---------------- | -------------------------- | ---------------------------------- |
| `webhook_result` | `Optional[Dict[str, Any]]` | The JSON response from the webhook |

## Example: Trigger External Action

```yaml theme={null}
nodes:
  # Generate a response
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query
      retrievals: search#retrievals

  # Log the interaction to an external system
  log_interaction:
    type: WebhookStep
    config:
      webhook_url: "https://analytics.example.com/log"
      method: POST
      auth_token: "${ANALYTICS_TOKEN}"
      static_headers:
        X-Source: "contextual-agent"
    input_mapping:
      context_data: interaction_data#json

  __outputs__:
    type: output
    input_mapping:
      response: generate#response
```

## Example: Fetch External Data

```yaml theme={null}
nodes:
  # Get real-time data from external API
  fetch_prices:
    type: WebhookStep
    config:
      webhook_url: "https://api.pricing.example.com/current"
      method: GET
      auth_token: "${PRICING_TOKEN}"
      timeout: 10

  # Use the data in generation
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query
      retrievals: search#retrievals
      pricing_data: fetch_prices#webhook_result
```

## Error Handling

WebhookStep includes automatic retry logic. Configure retries and timeout:

```yaml theme={null}
config:
  webhook_url: "https://api.example.com/endpoint"
  timeout: 60        # Wait up to 60 seconds
  retries: 3         # Retry up to 3 times on failure
```

## Related

* [MCP Integration](/reference/ac-mcp-integration)
* [Code Execution](/reference/ac-code-execution)
* [Tools Configuration](/reference/ac-tools-config)


# YAML Format
Source: https://docs.contextual.ai/reference/ac-yaml-format

Root-level fields and node structure for Agent Composer YAML

## Description

Agent Composer uses a YAML-based configuration format to define workflow graphs. This page describes the root-level fields and basic node structure.

## Root-Level Fields

At the root level, the Agent Composer YAML format accepts four main fields:

### `inputs`

Lists the inputs of the graph mapped to their accepted types. Type annotations should conform to Python typing syntax.

```yaml theme={null}
inputs:
  query: str
```

<Note>
  The main graph currently only accepts a single `str` input named `query`, unless used as a subgraph.
</Note>

### `outputs`

Lists the outputs of the graph mapped to their types. A graph can have arbitrarily many outputs, as long as their types are JSON-serializable.

```yaml theme={null}
outputs:
  response: str
  groundedness_scores: List[Dict[str, float]]
```

### `nodes`

Lists the nodes in the graph and specifies how they are connected.

```yaml theme={null}
nodes:
  preprocess:
    type: PreprocessNode
    input_mapping:
      input: __inputs__#query

  finalize:
    type: FinalizationNode
    input_mapping:
      query: __inputs__#query
      processed_query: preprocess#output
```

### `ui_output`

Specifies exactly one of the fields listed under `outputs` as the UI output. Required when there are multiple outputs; optional for single-output graphs.

```yaml theme={null}
ui_output: response
```

## Node Format

Nodes represent basic operations in the graph. A typical node definition:

```yaml theme={null}
example_node:
  type: PreprocessNode
  config:
    threshold: 0.2
    process_type: standard
  input_mapping:
    preprocessing_input: earlier_node#output_key
```

### Core Node Arguments

| Field              | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| `type`             | The step type (must be registered in the component registry) |
| `config`           | Configuration arguments passed to the step constructor       |
| `input_mapping`    | Describes how nodes connect to each other                    |
| `config_overrides` | Dynamic configuration determined at runtime                  |
| `ui_stream_types`  | Controls what data streams to the UI                         |

### Config Parameters

Config parameters are passed as keyword arguments to the step constructor. Nested configurations are supported:

```yaml theme={null}
my_node:
  type: CustomProcessorStep
  config:
    threshold: 0.85
    mode: "strict"
    options:
      enable_caching: true
      timeout_seconds: 30
  input_mapping:
    data: previous_node#output
```

<Note>
  If a config field is not specified, the platform agent configuration setting is used as the default.
</Note>

## Input and Output Nodes

Every graph has an implicit input node named `__inputs__`. Access inputs via:

```yaml theme={null}
input_mapping:
  current_node_input: __inputs__#query
```

The output node must be explicitly added:

```yaml theme={null}
__outputs__:
  type: output
  input_mapping:
    graph_output: final_node#node_output
```

## Related

* [Input Mapping](/reference/ac-input-mapping)
* [Config Overrides](/reference/ac-config-overrides)
* [UI Stream Types](/reference/ac-ui-stream-types)


# Settings & Parameters
Source: https://docs.contextual.ai/reference/agent-config-overview

Learn how to configure and optimize Contextual AI

Here you’ll find the main parameters used to configure RAG agents on the Contextual AI platform. Each parameter includes a sensible default, which you can modify to optimize performance for your specific data and query patterns.

This reference is organized into the following sections:

## [Standard Parameters](/reference/datastores)

Core configuration options that apply to Contextual AI agents, such as model selection, default behaviors, and key runtime settings. Use these parameters as your baseline before layering on more advanced controls.

## [System Prompts](/reference/core-system-prompt)

Instruct the agent on how to respond to users’ queries given the retrieved knowledge. The appropriate prompt is passed, along with the user query and relevant retrievals, to the Generator Model at generation-time.

## [Query Understanding](/reference/enable-multi-turn)

These settings affect if and how user queries are modified to improve retrieval performance and response generation.

## [Query Reformulation](/reference/enable-query-expansion)

These settings allow you to modify the original user query prior to retrieval and generation. These strategies can help improve retrieval accuracy or completeness.

## [Retrieval](/reference/number-of-retrieved-chunks)

These settings determine how the agent performs the initial retrieval from linked unstructured datastores.

## [Rerank & Filter](/reference/enable-reranking)

These settings affect how the agent reranks and filters chunks before passing them to the generator model.

## [Generate](/reference/max-new-tokens)

These settings affect how the generator model produces responses.

## [Miscellaneous](/reference/suggested-queries)

Additional controls for refining edge cases and improving overall user experience.


# Check Retrieval Need
Source: https://docs.contextual.ai/reference/check-retrieval-need

`should_check_retrieval_need`

## Description

Enables a check for whether the user query is general chit-chat or an addressable question. If the query is general chit-chat, the intermediate retrieval steps are skipped and the generator is called using the `no_retrieval_system_prompt`. If it is an addressable question, the RAG pipeline as configured is executed.


# Chunking Configurations
Source: https://docs.contextual.ai/reference/chunking

Chunking modes to support different document types

## Overview

Chunking is the process of breaking large documents into smaller, semantically meaningful pieces so AI models can understand, retrieve, and reason over them more effectively. Instead of forcing a model to process an entire report, slide deck, or knowledge base at once, chunking creates manageable units, each with its own context, that improve search accuracy, reduce hallucinations, and make RAG workflows far more reliable.

## Contextual AI Chunking Modes

Contextual AI offers four distinct chunking modes to support a wide range of document types and use cases:

### Hierarchy Depth

Chunks are created using the document’s structural depth (for example, section, subsection, and subsubsection). This is our default and most robust method, since it treats a document as an intricately layered structure. It works especially well on structured documents like academic papers or technical manuals.

### Hierarchy Heading

This strategy makes chunks based on section headings, but without enforcing strict structural depth. It's useful when the document doesn’t have a strong or helpful hierarchy (for instance, flat formats like chat logs or contracts, where hierarchical chunking might even be counterproductive).

### Static Length

Chunks are created by cutting the document at fixed token intervals. We include this mostly as a baseline; it’s not the strategy we recommend for most real-world use cases.

### Page Level

This splits the document one chunk per page. It makes sense for content like slide decks or executive summary reports — where each page is semantically distinct, and we don’t want a single chunk crossing between slides or sections.

### Additional controls include:

* **Max Chunk Length** sets the upper token limit per chunk.
* **Min Chunk Length** sets the lower bound (ignored if using `Page Level`).

These settings let users fine-tune chunk size and structure to match the semantics of their documents, whether it's a flat contract, a dense academic paper, or a multi-page SEC filing.


# Core System Prompt
Source: https://docs.contextual.ai/reference/core-system-prompt

`(system_prompt)`

## Description

The System Prompts instruct the agent on how to respond to users’ queries given the retrieved knowledge. The appropriate prompt is passed, along with the user query and relevant retrievals, to the Generator Model at generation-time.

<Note>
  **Note on Adherence:** Contextual has built agents to faithfully follow instructions. However, in some cases complete adherence cannot be guaranteed, especially where instructions are unclear, under-specified, or in conflict with other instructions you have given or our guardrails.
</Note>

The `system_prompt` setting defined how the agent interprets queries and generates responses. You can provide instructions about the agent’s persona and style, and the desired content and structure of the responses.

## Default System Prompt

```
You are a helpful AI assistant created by Contextual AI to answer questions about relevant documentation provided to you. Your responses should be precise, accurate, and sourced exclusively from the provided information. Please follow these guidelines:
* Only use information from the provided documentation. Avoid opinions, speculation, or assumptions.
* Use the exact terminology and descriptions found in the provided content.
* Keep answers concise and relevant to the user’s question.
* Use acronyms and abbreviations exactly as they appear in the documentation or query.
* Apply markdown if your response includes lists, tables, or code.
* Directly answer the question, then STOP. Avoid additional explanations unless specifically relevant.
* If the information is irrelevant, simply respond that you don’t have relevant documentation and do not provide additional comments or suggestions. Ignore anything that cannot be used to directly answer this query.
```


# Datastores
Source: https://docs.contextual.ai/reference/datastores

`(datastore_ids)`

## Description

Datastores are the knowledgebases that your agent can access when answering queries. Files uploaded into a datastore are processed using Contextual’s multi-modal document understanding pipeline, which prepares documents in ways optimized for end-to-end RAG performance.

<Note>
  You must link at least one datastore to your agent, but you can specify more. If no `datastore_id` is provided, Contextual AI will automatically create an empty `Datastore` and configure your new `Agent` to use it.
</Note>

## Example

The following API call creates a specialized `Agent` and links it to the `Datastore` with the `datastore_id` of `3c90c3cc-0d44-4b50-8888-8dd25736052a`:

```shell theme={null}
curl --request POST \
  --url https://api.contextual.ai/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "system_prompt": "<string>",
  "no_retrieval_system_prompt": "<string>",
  "multiturn_system_prompt": "<string>",
  "filter_prompt": "<string>",
  "suggested_queries": [
    "<string>"
  ],
  "name": "<string>",
  "description": "",
  "template_name": "default",
  "datastore_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}'
```

Contextual AI will return the new agent's `id` and its `datastore_ids`:

```json theme={null}
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "datastore_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
```


# Disable Commentary
Source: https://docs.contextual.ai/reference/disable-commentary

`(avoid_commentary)`

## Description

Flag that indicates whether the Agent should only output strictly factual information grounded in the retrieved knowledge, instead of the complete response (which can include commentary, analysis, etc.).


# Enable Filtering
Source: https://docs.contextual.ai/reference/enable-filtering

`(enable_filter)`

## Description

Allows the agent to perform a final filtering step prior to generation. When enabled, chunks are checked against the filter prompt and irrelevant chunks are filtered out. This acts like a final quality control checkpoint, helping to ensure that only relevant chunks are passed to the generator. This filter can improve response accuracy and relevance, but also increase the false refusal rate if the configuration is too strict.


# Enable Groundedness Score
Source: https://docs.contextual.ai/reference/enable-groundedness-score

`(calculate_groundedness)`

## Description

Enables the agent to provide groundedness scores as part of its response. When enabled, the agent identifies distinct claims in the response and assesses whether each one is grounded in the retrieved document chunks. Claims that are not grounded are shown in yellow in the UI. Defaults to `off`.


# Enable Multi-turn
Source: https://docs.contextual.ai/reference/enable-multi-turn

`enable_multi_turn`

## Description

`enable_multi_turn` allows the agent to remember and reference previous parts of the conversation, making interactions feel more natural and continuous. When enabled, the user’s query will automatically be reformulated based on prior turns to resolve ambiguities. The conversation history is prepended to the query at generation-time.


# Enable Query Decomposition
Source: https://docs.contextual.ai/reference/enable-query-decomposition

`(enable_query_decomposition)`

## Description

Toggles the query decomposition module `on` or `off`. When enabled, the module will break down complex and compound queries into a series of simpler queries. Each sub-query will have individual retrievals, which are then intelligently combined prior to any subsequent reranking, filtering, or generation steps. Simple queries, as judged by the model, will not be decomposed.


# Enable Query Expansion
Source: https://docs.contextual.ai/reference/enable-query-expansion

`enable_query_expansion`

## Description

An optional parameter that specifies how queries should be reformulated. Toggles the query expansion module `on` or `off`; when enabled, the user’s original query will be rewritten according to the instructions set out in the prompt, guided by any provided examples. If no prompt or examples are given, the default prompt is used.

## Default Query Reformulation Prompt

The following illustrates a few shot examples of how queries should be reformulated based on the provided instructions.

```
Instructions: Reformulate the query so that it is more detailed and includes relevant terminology or topics that will be helpful in maximizing the quality of the information retrieved to answer the query.

Example 1:
Original query: What are JPMorgan’s results this quarter?
Expanded query: Can you provide the latest financial results for JPMorgan, including revenue, earnings per share, and key metrics for the most recent quarter?

Example 2:
Original query: What is data cleaning?
Expanded query: Could you explain the concept of data cleaning, including common techniques used, typical challenges faced, and its role in the data preprocessing pipeline for machine learning models?

Example 3:
Original query: What are the results of Apple this quarter?
Expanded query: Can you provide the latest financial results for Apple, including revenue, earnings per share, and key metrics for the most recent quarter?
```


# Enable Reranking
Source: https://docs.contextual.ai/reference/enable-reranking

`(enable_rerank)`

# Description

Allows the agent to take the initially retrieved document chunks and rerank them based on the provided instructions and user query. The top reranked chunks are passed on for filtering and final response generation.


# FAQ
Source: https://docs.contextual.ai/reference/faq

Answers to the most common questions about Contextual AI

***

## Platform, Agents & Technology

#### What is the Contextual AI platform?

The Contextual AI platform is a context layer for enterprise AI. You build **agents** that are grounded in your data and can retrieve information, reason over it, and take actions. **Retrieval** (search over your datastores, with citation) is a core capability of these agents, but they can also use **tools** (APIs, MCP, code execution), run **multi-step workflows**, and produce structured outputs. You build agents with **Agent Composer** (templates or custom workflows), connect data via **datastores** and **connectors**, and query via the UI or API.

#### How does it differ from generic chatbots or LLM APIs?

Unlike generic LLMs, Contextual AI agents are wired to your private knowledge and can act on it. They retrieve relevant content from your datastores, cite sources, and—depending on the workflow—can call tools, run multi-step research, or execute tasks. That keeps responses accurate and aligned with your docs and policies while enabling agents to do more than single-turn Q\&A. Agent Composer lets you control the full path: retrieval, reranking, tools, and generation.

#### What are the core capabilities?

* **Agents & Agent Composer** — Build agents from templates (Basic Search, Agentic Search) or custom YAML/visual workflows. Agents combine retrieval (RAG) with multi-step reasoning, tool use (search, APIs, MCP), and cited or structured generation.
* **Datastores & connectors** — Ingest and sync content from local upload, GitHub, Confluence, Google Drive, SharePoint, Box, and more; incremental sync and published-content filtering where applicable.
* **Parsing & chunking** — State-of-the-art parsing for PDF, HTML, Markdown, and other formats; configurable chunking so agents can retrieve and reason over your content effectively.
* **APIs & SDKs** — Create agents, ingest documents, run queries, and manage evaluation/tuning via REST API and Python/Node SDKs.
* **Security & governance** — RBAC, audit trails, model armor, and compliance documentation (SOC 2, HIPAA, GDPR, etc.).

#### What does “context engineering” mean?

Context engineering is the practice of selecting, structuring, and delivering the right information to LLMs so that agent responses are accurate and grounded. On Contextual AI this includes: **retrieval** (search, rerank, filter over your datastores—a key part of every agent), **orchestration** (Agent Composer workflows, tools, conditional logic, multi-step actions), and **prompt/config** (system prompts, generation settings).

***

## Use Cases & Industries

#### Which industries are best suited for Contextual AI?

Contextual AI fits industries with large knowledge bases, complex documents (e.g. PDFs, specs, manuals, logs), and/or strong compliance needs. Typical fits include:

* **Engineering and manufacturing** — Technical support agents, root cause analysis over device or process logs, and agents over manuals and specifications.
* **Technical support** — Documentation and support agents that answer from product docs, wikis, and runbooks with citations.
* **R\&D** — Research agents over patents, trials, and internal knowledge; structured extraction and reporting.
* **Financial services** — Policy, research, and compliance-oriented agents over internal docs and regulations.
* **Legal and professional services** — Research and contract/document agents with citations and source control.

For when and why to use Contextual AI and how these map to workflows and templates, see [Why Contextual AI](/quickstarts/why-contextual-ai).

#### What are typical use cases?

* **Documentation & support agents** — Q\&A over product docs, internal wikis, or policy; agents retrieve and cite sources so users can verify and share.
* **Device log & root cause analysis** — Multi-step agents that ingest logs, correlate with specs and process history, and produce investigation reports with ranked hypotheses (enterprise templates).
* **Research and internal knowledge** — Agents over Confluence, Drive, or SharePoint for onboarding, planning, and decision support; multi-step retrieval and synthesis.
* **Task execution & planning** — Agents that predict failures, recommend maintenance, or produce plans with structured outputs (enterprise).
* **Structured extraction** — Compliance evidence collection, incident and postmortem analysis, and other extraction workflows with defined output schemas (enterprise).
* **Custom workflows** — Agent Composer for domain-specific retrieval, tool use (APIs, MCP), and cited or structured generation.

For the full set of workflows, template availability (self-serve vs. enterprise), and example use cases per workflow, see [Why Contextual AI](/quickstarts/why-contextual-ai).

#### How quickly can we go from concept to production?

Self-serve users can create a Basic Search or Agentic Search agent and connect a datastore in minutes. Enterprises using connectors and custom workflows have reached production in weeks (e.g. on the order of 30 days for initial deployments). The platform is built for production: scale, observability, and security are included.

***

## Data

#### What data sources can I connect?

You can ingest content via **connectors** (Confluence, Google Drive, Microsoft SharePoint, OneDrive, Box), **local file upload**, or the **documents API**. Supported content includes PDFs, Word, HTML, Markdown, and (for enterprise workflows) logs and structured data. Sync is incremental where supported so your agents stay up to date.

#### Does it scale to enterprise?

Yes. The platform supports large deployments: thousands of users, millions of pages ingested, and multiple use cases on one workspace. Datastores and agents scale with your data and query volume.

#### Do you train your models on our data?

No. We never use your documents, data, or interactions to train or fine-tune our underlying models. Your data remains isolated and is used only to power the AI agents you create within your own workspace.

#### How is our data used by the platform?

Your data is processed solely for retrieval, reasoning, and real-time inference by your agents. It is not stored for model improvement, shared with other customers, or used outside your environment.

#### Who owns the AI agents we build on the platform?

You do. Any agents you develop—including their configurations, behaviors, and outputs—are entirely your intellectual property.

#### Does the platform have any rights to our agents or data?

No. We do not claim ownership over your agents or your data. You retain full rights to everything you create and upload.

#### Is our data shared with other customers?

Never. Each customer environment is isolated, and your data is not accessible to or used by any other organization.

***

## Security & Governance

#### How is customer data handled and protected?

Customer data is processed in accordance with the customer's agreement, and our Platform Services processes data for the benefit of the customer and their authorized users. We publish a [Privacy Policy](https://contextual.ai/legal/privacy-policy) detailing how we collect, use, and share personal information.

#### Do you support enterprise governance and access control?

Yes. The platform supports [role-based access control (RBAC)](/admin-setup/rbac), audit trails, enterprise authentication, and model armor to reduce misuse. Entitlements can be enforced at query time.

#### Does Contextual AI adhere to major security and privacy frameworks?

Yes, we design with security and privacy in mind (data residency, encryption at rest/in transit, access control) and provide documentation to support enterprise compliance needs. We comply with major data protection standards, including HIPAA, SOC 2, CCPA, and GDPR, with specific certifications varying by region and customer requirements. For more information, visit the [Contextual AI Trust Center](https://trust.contextual.ai/).

***

## Getting Started & Pricing

#### How do I get started?

For a guided experience, [request a demo](https://contextual.ai/request-a-demo). For self-serve, follow the [getting started](/quickstarts/getting-started) and [platform (GUI)](/quickstarts/platform-gui) guides to create a datastore and agent (e.g. Agentic Search template) and run your first query.

#### Is there a free trial or credits?

Yes. New signups receive \$25 in free credits (\$50 with a work email) to build and query agents.

#### How is pricing structured?

Pricing is usage-based (queries, ingestion, compute, SLA). See the [Contextual AI pricing page](https://contextual.ai/pricing) for plans, feature comparison, and component API pricing, or contact [sales@contextual.ai](mailto:sales@contextual.ai) for your usage profile and enterprise options.

#### What support do you offer?

We provide documentation, SDKs, APIs, onboarding guidance, and enterprise support SLAs. Professional services are available for production deployments.

***

## Technical & Integrations

#### What languages and SDKs are supported?

You can use the REST API from any language (cURL, Python, JavaScript, Go, etc.). We offer official **Python** and **Node.js** SDKs. Agent Composer workflows are defined in YAML or built in the visual builder.

#### Can I deploy on-premises or in my private cloud?

Yes, our architecture supports flexible and secure deployment options, including fully managed cloud, private cloud, or customer VPC.

#### How does the Contextual AI platform scale for high-volume/real-time queries?

The Contextual AI platform is designed for production-grade reliability: auto-scaling compute for agents, vector store indexing, caching layers, and optimized retrieval pipelines to support high query volumes with low latency.

***

## Company & Trust

#### Who founded Contextual AI and where are you based?

Contextual AI was founded in 2023 by Douwe Kiela and Amanpreet Singh and is headquartered in Mountain View, California, USA.

#### Who are some of Contextual AI's clients or reference customers?

Contextual AI has enterprise clients across various sectors, including technology, financial services, and professional services. Some notable customers include Qualcomm, Advantest, NVIDIA, Comply, HSBC, ShipBob, Element Solutions, IGS, Sevii, and others.

#### What is Contextual AI’s mission?

Our mission is to replace the DIY complexity of building enterprise AI by providing a unified "context layer" so that AI is accurate, secure, scalable, and specialized to business knowledge and workflows.

#### How do you stay ahead in AI and maintain the trustworthiness of your agents?

We invest in research, model development (including grounded language models, rerankers), enterprise-grade engineering, and alignment to ensure the agents' outputs are fact-based, cite sources when appropriate, and support audit and traceability.


# Filter Prompt
Source: https://docs.contextual.ai/reference/filter-prompt

`(filter_prompt)`

## Description

Natural language instructions that describes the criteria for relevant and irrelevant chunks. It can be used in tandem with, or as an alternative to, the reranker score-based filtering.


# Frequency Penalty
Source: https://docs.contextual.ai/reference/frequency-penalty

`(frequency_penalty)`

## Description

Helps prevent repetition in responses by making the agent less likely to use words it has already used frequently. This helps ensure more natural, varied language. Defaults to `0`.


# Generation Model
Source: https://docs.contextual.ai/reference/generation-model

Selecting Your Generation Model

## Description

Determines which generation model powers your agent. You can use either our default Grounded Language Model (GLM) or a version that has been specifically tuned to your use case.

<Note>
  Tuned models can only be used with the agents on which they were tuned.
</Note>

## Usage

You can configure the generation model either during agent creation or by modifying an existing agent.

1. In the agent's configuration settings, click **Generation** from the left-hand pane to access **Generation Settings**.
2. Under **Generation Model**, select the desired model from the drop-down list.
3. Click the **Save** button.

<img alt="" />


# Glossary
Source: https://docs.contextual.ai/reference/glossary

Essential definitions for understanding and using Contextual AI

## Agent

An **Agent** is a queryable AI application that retrieves relevant data from connected **datastores** and generates responses grounded in that data. Agents are built in the Contextual AI app using **Agent Composer**: you choose a template (e.g. Basic Search, Agentic Search) or design a custom workflow with nodes and steps. Agents can do multi-step retrieval, use tools (search, APIs, MCP), and produce cited answers. You create and manage agents [via the API](/api-reference/agents/create-agent) or the [platform UI](/quickstarts/platform-gui).

## Agent Composer

**Agent Composer** is the framework for building agents on Contextual AI. You compose workflows from building blocks (search steps, generation steps, tools, conditional logic) either by editing **YAML** or using the visual workflow builder. Self-serve users can use **Basic Search** and **Agentic Search** templates; enterprise users get access to the full builder and additional templates. See [Agent Composer overview](/reference/ac-overview) and [Agent Composer templates](/how-to-guides/agent-composer-templates).

## Attributions / Citations

**Attributions** (citations) are in-line references that credit the sources used to generate a response. When you query an agent, attributions appear for factual claims (e.g. \[1], \[2]) and link to the retrieved documents. You can view them in the API response or in the UI. Agents built with Agent Composer can be configured to enforce citation format (e.g. [number]() with a References section). See [core system prompt](/reference/core-system-prompt) and [disable commentary](/reference/disable-commentary).

## Chunking

**Chunking** is the process of splitting documents into smaller, semantically meaningful pieces so the agent can retrieve and reason over them. Contextual AI supports multiple chunking modes to suit different document types. See [Chunking configurations](/reference/chunking).

## Connector

A **connector** links an external data source (e.g. Confluence, Google Drive, SharePoint, Box) to Contextual AI. Content is synced into one or more **datastores** and kept up to date. See [Connectors overview](/connectors/overview).

## Datastore

A **datastore** is a repository of ingested content (documents, chunks) that an **agent** searches when answering queries. You connect datastores to an agent when building the agent; one agent can use multiple datastores, and one datastore can serve multiple agents. Content is added via [connectors](/connectors/overview), [local upload](/connectors/local-file-upload), or the [documents API](/api-reference/datastores-documents/ingest-document). See [Datastores reference](/reference/datastores).

## Document

A **document** is a single unit of content (e.g. PDF, HTML, Markdown) ingested into a **datastore**. After ingestion, documents are parsed, chunked, and indexed for retrieval. You ingest documents [via the API](/api-reference/datastores-documents/ingest-document) or via connectors.

## Knowledge (retrievals)

**Knowledge** (or **retrievals**) is the set of chunks and sources the agent retrieved from its **datastores** to generate a response. In Agent Composer workflows, search steps output retrievals that are passed to generation steps. Responses can include **attributions** pointing to these sources.

## LMUnit

**LMUnit** is an evaluation method that uses natural-language unit tests to check specific qualities of an agent’s response (e.g. “Is the response succinct?” or “Is the complexity appropriate for the audience?”). You define and run these tests [via the LMUnit API](/api-reference/lmunit/lmunit). See also [LMUnit overview](https://contextual.ai/blog/lmunit/).

## Node

In **Agent Composer**, a **node** is a single step in the workflow graph (e.g. a search step, a generation step, a tool call). Nodes are connected by **input mapping** from outputs of one node to inputs of another. See [YAML format](/reference/ac-yaml-format) and [node reference](/how-to-guides/ac-node-reference).

## Query / Prompt

The **query** (or **prompt**) is the user’s question or instruction sent to an **agent**. You submit queries [via the query API](/api-reference/agents-query/query) or through the platform UI. The agent uses this input to drive retrieval and generation.

## RAG

**Retrieval Augmented Generation (RAG)** is a technique that grounds LLM outputs in retrieved knowledge. Contextual AI agents use RAG: they search your **datastores**, then generate responses from the retrieved chunks, with **citations**. Agent Composer lets you configure retrieval (e.g. search steps, reranking, filters) and generation (e.g. system prompts, model choice) in one workflow.

## Response

The **response** is the agent’s answer to a **query**. It is generated from **retrievals** and can include **attributions** and a References section. Response behavior is controlled by the agent’s workflow and generation config (e.g. [max tokens](/reference/max-new-tokens), [temperature](/reference/temperature)).

## System Prompt

The **system prompt** (and, when no retrieval is used, the **no-retrieval system prompt**) defines the agent’s behavior and how it should use retrieved content. You set these when building an agent in Agent Composer. See [Core system prompt](/reference/core-system-prompt) and [No-retrieval system prompt](/reference/no-retrieval-system-prompt).

## Template

A **template** is a pre-built Agent Composer workflow. **Basic Search** and **Agentic Search** are available for self-serve users; additional templates (e.g. Device Log Analysis, domain-specific templates) are available for enterprise. See [Agent Composer templates](/how-to-guides/agent-composer-templates) and [Template catalog](/examples/templates-catalog).

## Workspace

A **workspace** is the top-level container for your **agents**, **datastores**, API keys, and other resources. Access and billing are managed at the workspace level.


# Lexical Search Weight
Source: https://docs.contextual.ai/reference/lexical-search-weight

`(lexical_alpha)`

## Description

When chunks are scored during retrieval (based on their relevance to the user query), this controls how much weight the scoring gives to exact keyword matches. A higher value means the agent will prioritize finding exact word matches, while a lower value allows for more flexible, meaning-based matching.

The value ranges from `0` to `1`, and Contextual AI defaults to `0.1`. You can increase this weight if exact terminology, specific entities, or specialized vocabulary is important for your use case.


# Max New Tokens
Source: https://docs.contextual.ai/reference/max-new-tokens

`(max_new_tokens)`

## Description

Controls the maximum length of the agent’s response. Defaults to `2,048` tokens.


# No Retrieval System Prompt
Source: https://docs.contextual.ai/reference/no-retrieval-system-prompt

`(no_retrieval_system_prompt)`

## Description

Defines the agent’s behavior if, after the retrieval, reranking, and filter steps, no relevant knowledge has been identified. You can use this prompt to define boilerplate refusals, offer help and guidance, provide information about the document store, and specify other contextually-appropriate ways that the agent should respond.

## Default No Retrieval System Prompt

```
You are an AI RAG agent created by Contextual to help answer questions and complete tasks posed by users. Your capabilities include accurately retrieving/reranking information from linked datastores and using these retrievals to generate factual, grounded responses. You are powered by leading document parsing, retrieval, reranking, and grounded generation models. Users can impact the information you have access to by uploading files into your linked datastores. Full documentation, API specs, and guides on how to use Contextual, including agents like yourself, can you found at docs.contextual.ai.
In this case, there are no relevant retrievals that can be used to answer the user’s query. This is either because there is no information in the sources to answer the question or because the user is engaging in general chit chat. Respond according to the following guidelines:
If the user is engaging in general pleasantries (“hi”, “how goes it”, etc.), you can respond in kind. But limit this to only a brief greeting or general acknowledgement
Your response should center on describing your capabilities and encouraging the user to ask a question that is relevant to the sources you have access to. You can also encourage them to upload relevant documents and files to your linked datastore(s).
DO NOT answer, muse about, or follow-up on any general questions or asks. DO NOT assume that you have knowledge about any particular topic. DO NOT assume access to any particular source of information.
DO NOT engage in character play. You must maintain a friendly, professional, and neutral tone at all times
```


# Number of Reranked Chunks
Source: https://docs.contextual.ai/reference/number-of-reranked-chunks

`(top_k_reranked_chunks)`

## Description

The number of top reranked chunks that are passed on for generation.


# Number of Retrieved Chunks
Source: https://docs.contextual.ai/reference/number-of-retrieved-chunks

`(top_k_retrieved_chunks)`

## Description

The maximum number of chunks that should be retrieved from the linked datastore(s). For example, if set to `10`, the agent will retrieve at most 10 relevant chunks to generate its response. The value ranges from `1` to `200`, and the default value is `100`.


# Random Seed
Source: https://docs.contextual.ai/reference/random-seed

`(seed)`

## Description

Controls randomness in how the agent selects the next tokens during text generation. Allows for reproducible results, which can be useful for testing.


# Rerank Instructions
Source: https://docs.contextual.ai/reference/rerank-instructions

`(rerank_instructions)`

## Description

Natural language instructions that describe your preferences for the ranking of chunks, such as prioritizing chunks from particular sources or time periods. Chunks will be rescored based on these instructions and the user query.

If no instruction is given, the rerank scores are based only on relevance of chunks to the query.


# Reranker Score Filter
Source: https://docs.contextual.ai/reference/reranker-score-filter

`(reranker_score_filter_threshold)`

## Description

If the value is set to greater than `0`, chunks with relevance scores below the set value will not be passed on. Input must be between `0` and `1`.


# Semantic Search Weight
Source: https://docs.contextual.ai/reference/semantic-search-weight

`(semantic_alpha)`

## Description

When chunks are scored during retrieval (based on their relevance to the user query), this controls how much weight the scoring gives to semantic similarity. Semantic searching looks for text that conveys similar meaning and concepts, rather than just matching exact keywords or phrases.

The value ranges from `0` to `1`, and Contextual AI defaults to `0.9`. The value of the semantic search weight and lexical search weight must sum to `1`.


# Suggested Queries
Source: https://docs.contextual.ai/reference/suggested-queries

`(suggested_queries)`

## Description

Example queries that appear in the user interface when first interacting with the agent. You can provide both simple and complex examples to help users understand the full range of questions your agent can handle. This helps set user expectations and guides them toward effective interactions with the agent.


# Temperature
Source: https://docs.contextual.ai/reference/temperature

`(temperature)`

## Description

Controls how creative the agent’s responses are. A higher temperature means more creative and varied responses, while a lower temperature results in more consistent, predictable answers. Ranges from `0` to `1`, defaults to `0`.


# Top P
Source: https://docs.contextual.ai/reference/top-p

`(top_p)`

## Description

Similar to temperature, this parameter also controls response variety. It determines how many different word choices the agent considers when generating its response. Defaults to `0.9`.


# 2025 Release Updates
Source: https://docs.contextual.ai/release-notes/2025

Product Highlights & Release Information

***

## December

### 12/11/2025

**Higher Page & File Size Limits for PDF, DOCX, & PPTX Ingestion**<br />
Document ingestion now supports files up to 2,000 pages and 400MB.

<Accordion>
  <p>
    We've significantly expanded our document ingestion capabilities to support much larger files. The platform can now process documents up to **2,000 pages** and **400MB in size**, a substantial increase from the previous limits of **400 pages** and **100MB**. This enhancement allows users to work with more comprehensive documents without needing to manually split them into smaller parts.
  </p>

  <p>
    For existing tenants, adoption of the new limits requires a manual update to the feature flags. To enable the expanded capacity, set:

    * `MAX_PDF_PAGES_PER_FILE_ALLOWED` to `2000`

    * `MAX_BYTE_SIZE_FILE_ALLOWED` to `400000000`

    Please note that processing performance may still slow down for documents exceeding 400 pages. Organizations with strict latency requirements should continue to divide large documents into smaller segments to maintain optimal processing speed.
  </p>
</Accordion>

### 12/8/2025

**Oryx v0.1.0 Now Available**<br />
Oryx by Contextual AI allows you to seamlessly integrate your application with Contextual AI agents, from interface to proxy, with a fully customizable and unbranded user experience.

<Accordion>
  <p>
    Oryx by Contextual AI is now officially live, enabling teams to seamlessly integrate Contextual AI agents directly into their applications with a fully customizable, unbranded, and developer-friendly experience. Built to support enterprise engineering teams, Oryx abstracts away the complexity of connection handling, agent logic, and data flow so you can focus entirely on crafting exceptional user experiences.
  </p>

  <p>
    <b>Key Features</b>

    <ul>
      <li>Seamless integration of Contextual AI agents into any product's interface or backend</li>
      <li>Fully customizable, unopinionated UI that allows teams complete control over branding and user experience</li>
      <li>Enterprise-grade connection and data flow management, handled automatically by Oryx</li>
      <li>Optimized developer experience, offering intuitive APIs and configurable components</li>
      <li>React support via `@contextualai/oryx-react` for building rich, responsive front-end agent interactions</li>
      <li>Secure backend connectivity via `@contextualai/oryx-proxy-node`, usable in any JavaScript runtime environment</li>
      <li>[Curated styling guide](https://oryx.contextual.ai/styling) with example code and a sample repository to accelerate production-ready deployments</li>
    </ul>
  </p>

  <p>
    <b>Availability</b><br />
    Oryx is now available as `v0.1.0`. Explore the docs and examples at [https://oryx.contextual.ai/](https://oryx.contextual.ai/)
  </p>
</Accordion>

**Login & Signup Page Redesign**<br />
The Contextual AI platform login and sign-up pages have been redesigned, bringing greater visual consistency with our company's corporate website experience.

<Accordion>
  <p>
    We've refreshed the Contextual AI platform login and sign-up experience with the newly introduced Möbius imagery from our corporate website, continuing our broader effort to unify the platform's look and feel under our evolving brand identity. This update enhances visual consistency across surfaces and reflects the modernized aesthetic we're rolling out throughout the product.
  </p>
</Accordion>

### 12/4/2025

**Monitoring Page with Analytics & Insights**<br />
Contextual AI now provides a **Monitoring** page with searchable, exportable analytics across agent activity, user engagement, and knowledge-base operations through interactive charts and key usage metrics.

<Accordion>
  <p>
    The new Monitoring Page gives teams deeper visibility into how their agents and knowledge bases are performing. With built-in analytics, filters, and exportable charts, you can quickly understand usage patterns, identify issues, and track adoption across your organization.
  </p>

  <p>
    <b>Key Features</b>

    <ul>
      <li>Agent performance metrics including daily active users, total queries, feedback/thumbs-up rates, and retry rates</li>
      <li>Knowledge-base activity insights such as document upload volume and datastore creation trends</li>
      <li>Searchable filters for agents and users, with intuitive **Apply** and **Clear** controls for fast exploration</li>
      <li>Interactive charts that allow drill-down analysis and CSV export for reporting or offline review</li>
    </ul>
  </p>

  <p>
    <b>How To Enable</b><br />
    Set the feature flag `ENABLE_MONITORING_PAGE` to `on` (default: `off`). Once enabled, the **Monitoring Page** will appear under **Observability** in the sidebar.
  </p>
</Accordion>

### 12/1/2025

**Custom RBAC with Groups**<br />
You can now create custom, fine-grained roles and groups with scoped permissions for tighter, more precise access control.

<Accordion>
  <p>
    Admins can now define custom roles with tailored permission bundles across key objects (e.g., Agents, Datastores, Billing, and other admin features). Permissions can be scoped to specific Agents or Datastores, enabling finer-grained governance by ensuring each team member has the right level of access for their responsibilities. You can also create Groups to simplify role management.
  </p>

  <p>
    Contact your Contextual AI account manager to enable this feature.
  </p>
</Accordion>

***

## November

### 11/5/2025

**Data Connectors Now Support Sync History**<br />
Data connectors now include full sync history, giving teams visibility into every sync event and the ability to inspect individual document failures.

<Accordion>
  <p>
    You can now review a complete record of all sync activity across your data connectors. Each sync includes drill-down details so you can see exactly which documents failed and why. This makes troubleshooting faster and provides clearer operational insight into connector performance.
  </p>

  <p>
    How to enable: Default on.
  </p>
</Accordion>

**Configurable Feedback Options**<br />
Agent developers can now customize the end-user feedback workflow, including mandatory feedback and personalized issue labels.

<Accordion>
  <p>
    We've added new configuration controls that let agent developers tailor how users provide feedback. You can require feedback for every query, define your own issue labels, and adapt the workflow to match your team's QA process. These options give you more flexibility in how feedback is collected and managed.
  </p>

  <p>
    How to enable: Default on. Go to **Agent Config → User Experience**.
  </p>
</Accordion>

**Three New Connectors: OneDrive, Box, Confluence**<br />
OneDrive, Box, and Confluence are now supported as third-party connectors for datastores.

<Accordion>
  <p>
    We've expanded our integration ecosystem with three widely requested connectors. You can now ingest and manage documents from OneDrive, Box, and Confluence directly through your datastore, extending your retrieval pipeline with more enterprise content sources.
  </p>

  <p>How to enable: **Create Datastore → Third-Party Connection**.</p>
</Accordion>

**Feedback Annotation Module**<br />
A new annotation module allows admins to label, annotate, visualize, and export feedback directly within the platform.

<Accordion>
  <p>
    The platform now supports end-to-end feedback annotation. Admins can define annotation labels, tag feedback within the UI, generate basic visualizations, and export annotated data as CSV. This gives enterprise teams a centralized place to manage QA workflows, reduce tool switching, and streamline evaluation processes.
  </p>

  <p>
    How to enable: Default on for all tenants. Access via **Agent Config → Feedback Annotation**.
  </p>
</Accordion>

***

## September

### 9/17/2025

**Billing API Endpoint Available**<br />
A new Billing API endpoint provides programmatic access to usage and consumption data.

<Accordion>
  <p>
    Teams can now integrate their billing and consumption data into their internal tools or dashboards using the new Billing API. This enables easier reporting, monitoring, and automation around usage.
    Endpoint: [https://docs.contextual.ai/api-reference/billing/get-billing-metadata](https://docs.contextual.ai/api-reference/billing/get-billing-metadata)
  </p>
</Accordion>

**Ingestion Config Override (API Only)**<br />
You can now override default datastore configurations per document via API to fine-tune ingestion behavior.

<Accordion>
  <p>
    This API-only feature lets you apply document-specific ingestion settings without modifying the global datastore configuration.
  </p>

  <p>This feature is useful for documents that require customized handling—such as specialized chunking, parsing, or classification. The update affects the Ingest and List Documents endpoints.</p>
</Accordion>

### 9/15/2025

**Chunk Viewer UI Improvements**<br />
The Chunk Viewer received multiple UX enhancements, including shareable URLs, clearer file context, improved previews, and easier text editing.

<Accordion>
  <p>
    We've refreshed the Chunk Viewer to simplify navigation and collaboration. You can now share direct links to specific documents and chunks, see the file name at the top of the page, and see a formatted "Preview" as the default view. We've also improved visibility for image captioning and added an Edit button to update chunk text more easily.
  </p>
</Accordion>

***

## August

### 8/27/2025

**Support for Templates**<br />
Teams can now create and apply templates when building new agents.

<Accordion>
  <p>
    Template support is now live. You can select from existing templates or save an agent's configuration as a reusable template for future agents. This accelerates setup, ensures consistency across deployments, and simplifies onboarding for new team members.
  </p>
</Accordion>

### 8/22/2025

**Datastore Updates**<br />
Datastore management has been enhanced with new filtering tools, improved search, and expanded model options for document processing.

<Accordion>
  <p>
    We've added several usability improvements to streamline datastore operations. You can now filter documents by status with one click (Processed, Processing, Failed), search by filename (prefix search), and customize filters or sort by creation date, status, or name.
  </p>

  <p>
    We've also introduced new swappable models—layout, image captioning, hierarchy, and document-naming models—to improve processing accuracy and support a wider variety of document types. These settings are available in datastore configuration and help optimize ingestion pipelines.
  </p>
</Accordion>

### 8/20/2025

**GPT-5 available as a Generation Model**<br />
Agents can now use GPT-5 as their generation model for production workloads.

<Accordion>
  <p>
    We've added GPT-5 as an option for all agents, giving teams access to the latest generation capabilities for reasoning, summarization, and content generation. This upgrade improves accuracy and output quality across a wide range of use cases.
  </p>
</Accordion>

***

## June

### 6/30/2025

**Page-level Chunking in Datastore Configuration Options**\
Contextual AI now supports a new page-level chunking mode that preserves slide and page boundaries for more accurate, context-aware retrieval in RAG workflows.

<Accordion>
  <p>
    Page-level chunking mode optimizes parsing for page-boundary-sensitive
    documents. Instead of splitting content purely by size or heading structure,
    this mode ensures each page becomes its own retrieval-preserving chunk
    unless the maximum chunk size is exceeded.
  </p>

  <p>
    This is particularly effective for slide decks, reports, and other
    page-oriented content, where the meaning is closely tied to individual
    pages.
  </p>

  <p>
    Page-level chunking joins existing segmentation options including
    <strong>heading-depth</strong>, <strong>heading-greedy</strong>, and
    <strong>simple-length</strong>.
  </p>

  <p>
    To enable, set `chunking_mode = "page"` when configuring a
    datastore via the ingest document API or via the UI.
  </p>
</Accordion>

### 6/2/2025

**Query Reformulation & Decomposition**\
Contextual AI now supports query reformulation and decomposition, enabling agents to rewrite, clarify, and break down complex or ambiguous user queries.

<Accordion>
  <p>
    Query reformulation allows agents to rewrite or expand user queries to
    better match the vocabulary and structure of your corpus. This is essential
    when user queries are ambiguous, underspecified, or contain terminology not
    aligned with the domain.
  </p>

  <p>
    Decomposition automatically determines whether a query should be split into
    smaller sub-queries. Each sub-query undergoes its own retrieval step before
    results are merged into a final ranked set.
  </p>

  <p>Common reformulation use cases include:</p>

  <ul>
    <li>Aligning queries with domain-specific terminology</li>
    <li>Making implicit references explicit</li>
    <li>Adding metadata or contextual tags to guide retrieval</li>
  </ul>

  <p>
    Enable these features via <strong>Query Reformulation</strong> in the agent
    settings UI, or via the Agent API.
  </p>
</Accordion>

***

## May

### 5/29/2025

**Optimize parsing and chunking strategies via Datastore configuration**\
Contextual AI has released new advanced datastore configuration options that let developers fine-tune parsing, chunking, and document processing workflows to produce highly optimized, use-case-specific RAG-ready outputs.

<Accordion>
  <p>
    Today, Contextual AI announces the release of advanced datastore
    configuration options, enabling developers to optimize document processing
    for RAG-ready outputs tailored to their specific use cases and document
    types.
  </p>

  <p>
    Clients can now customize parsing and chunking workflows to maximize RAG
    performance. Configure heading-depth chunking for granular hierarchy
    context, use custom prompts for domain-specific image captioning, enable
    table splitting for complex structured documents, and set precise token
    limits to optimize retrieval quality.
  </p>

  <p>
    These configuration options ensure your documents are processed optimally
    for your RAG system – whether you're working with technical manuals
    requiring detailed hierarchical context, visual-heavy documents needing
    specialized image descriptions, or structured reports with complex tables.
  </p>

  <p>
    To get started, simply use our updated Agent API and datastore UI with the
    new configuration parameters to customize parsing and chunking behavior for
    your specific documents and use cases.
  </p>
</Accordion>

### 5/20/2025

**Chunk viewer for document inspection**\
Contextual AI introduces the Chunk Inspector, a visual debugging tool that lets developers inspect and validate document parsing and chunking results to ensure their content is fully RAG-ready.

<Accordion>
  <p>
    Today, Contextual AI announces the release of the Chunk Inspector, a visual
    debugging tool that allows developers to examine and validate document
    parsing and chunking results.
  </p>

  <p>
    Clients can now inspect how their documents are processed through our
    extraction pipeline, viewing rendered metadata, extracted text, tables or
    image captioning results for each chunk. This transparency enables
    developers to diagnose extraction issues, optimize chunking configurations,
    and ensure their documents are properly RAG-ready before deployment.
  </p>

  <p>
    The Chunk Inspector provides immediate visibility into how your datastore
    configuration affects document processing, making it easier to fine-tune
    parsing and chunking settings for optimal retrieval performance.
  </p>

  <p>
    To get started, simply navigate to the Chunk Inspector in your datastore UI
    after ingesting a document to review the extraction and chunking results.
  </p>
</Accordion>

### 5/13/2025

**Document Parser for RAG now Generally Available**\
Contextual AI has launched a new Document Parser for RAG, a powerful /parse API that delivers highly accurate, hierarchy-aware understanding of large enterprise documents—dramatically improving retrieval quality across complex text, tables, and diagrams.

<Accordion>
  <p>
    Today, Contextual AI announces the Document Parser for RAG with our
    separate /parse component API, enabling enterprise AI agents to navigate and
    understand large and complex documents with superior accuracy and context
    awareness.
  </p>

  <p>
    The document parser excels at handling enterprise documents through three
    key innovations: document-level understanding that captures section
    hierarchies across hundreds of pages, minimized hallucinations with
    confidence levels for table extraction, and superior handling of complex
    modalities such as technical diagrams, charts, and large tables. In testing
    with SEC filings, including document hierarchy metadata in chunks increased
    the equivalence score from 69.2% to 84.0%, demonstrating significant
    improvements in end-to-end RAG performance.
  </p>

  <p>
    Get started today for free by creating a Contextual AI account. Visit the
    Components tab to use the Parse UI playground, or get an API key and call
    the API directly. We provide credits for the first 500+ pages in Standard
    mode (for complex documents that require VLMs and OCR), and you can buy
    additional credits as your needs grow. To request custom rate limits and
    pricing, please contact us. If you have any feedback or need support, please
    email [parse-feedback@contextual.ai](mailto:parse-feedback@contextual.ai).
  </p>
</Accordion>

***

## March

### 3/24/2025

**Groundedness scoring of model responses now Generally Available**\
Contextual AI now offers groundedness scoring, a feature that evaluates how well each part of an agent's response is supported by retrieved knowledge, helping developers detect and manage ungrounded or potentially hallucinated claims with precision.

<Accordion>
  <p>Today, Contextual AI launched groundedness scoring for model responses.</p>

  <p>
    Ensuring that agent responses are supported by retrieved knowledge is
    essential for RAG applications. While Contextual's Grounded Language Models
    already produce highly grounded responses, groundedness scoring adds an
    extra layer of defense against hallucinations and factual errors.
  </p>

  <p>
    When users query an agent with groundedness scores enabled, a specialized
    model automatically evaluates how well claims made in the response are
    supported by the knowledge. Scores are reported for individual text spans
    allowing for precise detection of unsupported claims. In the platform
    interface, the score for each text span is viewable upon hover and
    ungrounded claims are visually distinguished from grounded ones. Scores are
    also returned in the API, enabling developers to build powerful
    functionality with ease, like hiding ungrounded claims or adding caveats to
    specific sections of a response.
  </p>

  <p>
    To get started, simply toggle "Enable Groundedness Scores" for an agent in
    the "Generation" section of the agent configuration page, or through the
    agent creation or edit API. Groundedness scores will automatically be
    generated and displayed in the UI, and returned as part of responses to
    `/agent/{agent_id}/query` requests.
  </p>
</Accordion>

### 3/21/2025

**Metadata ingestion & document filtering**\
Contextual AI now supports document-level metadata ingestion and metadata-based filtering, enabling developers to target queries by attributes like author, date, department, or custom fields for more precise and relevant retrieval.

<Accordion>
  <p>
    Today, Contextual AI announces the release of document metadata ingestion
    and allows for metadata-based filtering during queries.
  </p>

  <p>
    Clients can now narrow search results using document properties like author,
    date, department, or any custom metadata fields, delivering more precise and
    contextually relevant responses.
  </p>

  <p>
    To get started, simply use our ingest document and update document metadata
    APIs to add metadata to documents. Once done, use our document filter in the
    query API to filter down results.
  </p>
</Accordion>

· · ·

**Document format support expansion: DOC(X) and PPT(X)**\
Contextual AI now supports ingesting DOC(X) and PPT(X) files, allowing RAG agents to seamlessly use Microsoft Office documents as part of their retrieval corpus.

<Accordion>
  <p>
    Today, Contextual AI announces the release of the support of DOC(X) and
    PPT(X) files for ingestion into datastore.
  </p>

  <p>
    This enables clients to leverage Microsoft Office documents directly in
    their RAG agents, expanding the range of content they can seamlessly
    incorporate.
  </p>

  <p>To get started, use our document API or our user interface to ingest new files.</p>
</Accordion>

### 3/17/2025

**Filtering by reranker relevance score now Generally Available**\
Contextual AI now allows users to filter retrieved chunks by reranker relevance score, giving them more precise control over which chunks are used during response generation via a new `reranker_score_filter_threshold` setting in the Agent APIs and UI.

<Accordion>
  <p>
    Today, Contextual AI announces support for filtering retrieved chunks based
    on the relevance score assigned by the reranker.
  </p>

  <p>
    The ability to filter chunks based on relevance score gives users more
    precision and control in ensuring that only the most relevant chunks are
    considered during response generation. It is an effective alternative or
    complement to using the filter\_prompt for a separate filtering LLM.
  </p>

  <p>
    To get started, use the `reranker_score_filter_threshold parameter` in the
    Create/Edit Agent APIs and in the UI.
  </p>
</Accordion>

### 3/11/2025

**Instruction-following reranker now Generally Available**\
Contextual AI has released the world's first instruction-following reranker—a state-of-the-art model that lets users provide natural-language ranking instructions to improve retrieval relevance and response accuracy, now available

<Accordion>
  <p>
    Today, Contextual AI announces the world's first instruction-following
    reranker, available in both agents and as a separate /rerank component API.
  </p>

  <p>
    The instruction-following reranker enables users to specify natural language
    instructions about how the reranker should rank retrievals, which improves
    accuracy in reranking and response generation. The reranker ranks documents
    according to their relevance to the query first and your custom instructions
    secondarily. We evaluated the model on instructions for recency, document
    type, source, and metadata, and it can generalize to other instructions as
    well. For instructions related to recency and timeframe, specify the
    timeframe (e.g., instead of saying "this year") because the reranker doesn't
    know the current date. The reranker is state-of-the-art on the
    industry-standard BEIR benchmark, as well as our internal benchmarks.
  </p>

  <p>
    To get started for free with the `/rerank` component API, create a Contextual
    AI account, visit the Getting Started tab, and either get an API key for the
    `/rerank API` or use the `/rerank UI` playground. We provide credits for the
    first 50M tokens, and you can buy additional credits as your needs grow. To
    request custom rate limits and pricing, please contact us. If you have any
    feedback or need support, please email [reranker-feedback@contextual.ai](mailto:reranker-feedback@contextual.ai).
  </p>

  <p>
    This reranker is the default for new agents created with the Contextual AI
    platform. To specify instructions, use the reranker\_instruction parameter in
    the Create/Edit Agent APIs and in the UI. See blog post for more details.
  </p>
</Accordion>

### 3/4/2025

**Grounded Language Model now Generally Available**\
Contextual AI has introduced the Grounded Language Model (GLM), a highly faithful RAG-optimized LLM that prioritizes retrieved knowledge over parametric knowledge, supports optional commentary control, and is now available both as the default agent model and through a standalone `/generate` API.

<Accordion>
  <p>
    Today, Contextual AI announces the Grounded Language Model (GLM), the most
    grounded language model in the world, available in both agents and as a
    separate /generate component API.
  </p>

  <p>
    The GLM is an LLM that is engineered specifically to prioritize faithfulness
    to the retrieved knowledge over parametric knowledge to reduce
    hallucinations in Retrieval-Augmented Generation. Uniquely, the model
    distinguishes between facts and commentary that it generates, and users can
    toggle an avoid\_commentary flag to determine whether the model can include
    commentary in its response or not.
  </p>

  <p>
    To get started for free with the /generate component API, create a
    Contextual AI account, visit the Getting Started tab, and either get an API
    key the /generate standalone API or use the /generate UI playground. We
    provide credits for the first 1M input and 1M output tokens, and you can buy
    additional credits as your needs grow. To request custom rate limits and
    pricing, please contact us here. If you have any feedback or need support,
    please email [glm-feedback@contextual.ai](mailto:glm-feedback@contextual.ai).
  </p>

  <p>
    The GLM is already the default model in new agents created with the
    Contextual AI platform. See blog post for more details.
  </p>
</Accordion>

### 3/3/2025

**Advanced parameters now Generally Available**\
Contextual AI now offers advanced agent configuration parameters that let you fine-tune retrieval, reranking, filtering, and generation behaviors, giving you precise control over how your RAG agents search, select, filter, and generate responses for your specific use cases.

<Accordion>
  <p>
    Today, Contextual AI announces the availability of advanced parameters in
    agent creation and editing.
  </p>

  <p>
    With these parameters, you can control more granular aspects of your
    specialized RAG agent across retrieval, reranking, filtering and generation.
    In particular, you can:
  </p>

  <ul>
    <li>
      Fine-tune retrieval relevance by adjusting lexical and semantic search
      weightings, helping you balance keyword precision with conceptual matching
    </li>

    <li>
      Optimize chunk selection by configuring both the number of retrieved
      chunks and reranked chunks, allowing you to maximize relevance while
      managing context window usage
    </li>

    <li>
      Customize filtering criteria with your own custom filter prompt, enabling
      you to implement domain-specific relevance rules
    </li>

    <li>
      Control response generation with precise temperature, top\_p, and frequency
      penalty settings, giving you the flexibility to balance consistency and
      creativity in answers
    </li>
  </ul>

  <p>
    These controls empower you to optimize your agent according to use
    case-specific requirements with much greater precision, ultimately
    delivering more accurate and relevant responses to your users' queries.
  </p>

  <p>
    To get started, use the `agent_configs` object in the Create/Edit Agent APIs.
    You can also change these parameters by editing the agent in the UI. They
    are subject to change.
  </p>
</Accordion>

***

## February

### 2/10/2025

**Agent-level entitlements now Generally Available**\
Contextual AI now supports agent-level entitlements, allowing administrators to assign per-user access rights and define fine-grained permission policies for agents directly from the platform's Permissions page.

<Accordion>
  <p>Today, Contextual AI announced support for Agent-level entitlements.</p>

  <p>
    With this release, customers can now configure access rights per-user to
    agents. Using the Permissions page on our platform UI, administrators can
    define access policies for their entire tenant or grant individual access to
    specific agents to specific users.
  </p>
</Accordion>

· · ·

**Users API now Generally Available**\
Contextual AI has introduced a new Users API that allows administrators to programmatically create, view, update, and remove end-user accounts, complementing existing user management in the platform UI.

<Accordion>
  <p>
    Today, Contextual AI announces the release of our new Users API to help
    customers manage their end-users on the platform.
  </p>

  <p>
    Administrators can now programmatically manage user accounts through the
    Users API. This includes creating new users, describing users, updating user
    information, and removing users. In addition to the Users API, customers can
    also manage their end-users through the platform UI.
  </p>

  <p>To get started, use the Users API today on the platform. Learn more here.</p>
</Accordion>

· · ·

**Metrics API now Generally Available**\
Contextual AI has launched a new Metrics API that gives developers programmatic access to agent query and feedback data, enabling automated analysis, reporting, and alerting based on real user interactions.

<Accordion>
  <p>
    Today, Contextual AI announces the release of our new Metrics API. This
    endpoint provides programmatic access to an agent's query and feedback data
    from end-users.
  </p>

  <p>
    With the Metrics API, developers can analyze usage and feedback, automate
    reporting, and set up alerts. The Metrics API returns data such as user and
    message information, query, response, feedback, and user-submitted details
    or issues with generated responses.
  </p>

  <p>To get started, use the Metrics API today on the platform. Learn more here.</p>
</Accordion>

· · ·

**Multi-turn conversations now available in Private Preview**\
Contextual AI now supports multi-turn chat, enabling agents to use prior conversation history and retrieved knowledge to interpret follow-up questions, resolve ambiguities, and generate more contextually grounded answers.

<Accordion>
  <p>Today, Contextual AI announced support for multi-turn chat conversations.</p>

  <p>
    With this release, agents can rely on prior conversational history and
    retrieved knowledge. When users ask follow-up questions, agents can
    automatically use information from prior turns in the conversation to
    resolve ambiguities in the query, fetch the appropriate retrievals, and
    generate the final answer.
  </p>

  <p>This feature is currently available in private preview. Contact us to get access.</p>
</Accordion>

· · ·

**Many-to-many mapping between agents and datastores now Generally Available**\
Contextual AI now supports many-to–many connections between agents and datastores, allowing multiple agents to access multiple datastores for more flexible, efficient, and scalable RAG workflows.

<Accordion>
  <p>
    Today, Contextual AI announced support for many-to-many mapping between
    agents and datastores. Multiple datastores can now connect to multiple
    agents, enabling more flexible and efficient ways to build specialized RAG
    agents.
  </p>

  <p>
    With many-to-many mapping, you can now connect multiple agents to multiple
    datastores, eliminating data silos allowing for cross-datastore access. As
    your system grows, agents can interact with any datastore without manual
    duplication or re-uploading, ensuring faster access and better efficiency.
  </p>

  <p>
    To get started, build your first datastore today on the platform. Learn more
    here.
  </p>
</Accordion>

· · ·

**Support for multimodal data**\
Contextual AI can now extract and reason over charts, graphs, and other visual elements within PDFs, enabling agents to answer questions based on both text and image content.

<Accordion>
  <p>Today, Contextual AI announced support for reasoning over images in unstructured data.</p>

  <p>
    Our document understanding engine can now extract and reason over charts,
    graphs, and other visual elements within PDF files. In addition to text,
    your agents can now answer queries based on the content of images in PDF
    files.
  </p>
</Accordion>


# 2026 Release Updates
Source: https://docs.contextual.ai/release-notes/2026

Product Highlights & Release Information

***

## February

### 2/10/2026

**Global Datastores Now Available**<br />
Pre-built, read-only datastores are now available to all users so you can test agents, run demos, or explore the platform without uploading your own documents.

<Accordion>
  <p>
    Contextual AI now provides **global datastores**—curated knowledge bases that are available to every account by default. Use them to try out the platform, demo agents to stakeholders, or prototype workflows before connecting your own data. Available collections include Materials Science Research Papers, Star Wars Wookiepedia, Rocket Science, RFC Library, and Raspberry Pi Docs.
  </p>

  <p>
    <b>How to use</b><br />
    In the platform, go to **Datastores** in the left navigation. Global datastores are marked with a **Demo** badge. When creating an agent, select any global datastore from the dropdown. In Agent Composer YAML, reference a global datastore by its ID.
  </p>

  <p>
    <a href="/connectors/global-datastores">Global Datastores documentation</a>
  </p>
</Accordion>

### 2/2/2026

**Web Search Attributions in Responses**<br />
Agents can now surface attributions in the final response using information from web search, and those attributions can be rendered directly in your application.

<Accordion>
  <p>
    When an agent uses web search, the platform can now generate **attributions** in the response—clear references to the sources that informed the answer. These attributions are available in the API and can be rendered inline in your application so users can see where information came from and follow links to the original content.
  </p>

  <p>
    <b>How to enable</b><br />
    No action required. This feature is enabled by default and is Generally Available for all new production tenants.
  </p>

  <p>
    <b>Note</b><br />
    Some source pages do not allow their content to be displayed inline. In those cases, users can use the **Source documents** button to view the content.
  </p>
</Accordion>

***

## January

### 1/27/2026

**Agent Composer Now Available in Public Preview**<br />
Contextual AI's Agent Composer is now available in public preview, enabling users to build customized agent workflows with visual and programmatic tools.

<Accordion>
  <p>
    We're excited to announce that **Agent Composer** is now available in public preview. Agent Composer is Contextual AI's framework for building customized query workflows by assembling pre-made components such as search tools, third-party API/MCP integrations, and various LLMs.
  </p>

  <p>
    **Self-serve users** can start with pre-built templates (Basic Search and Agentic Search) that cover most Q\&A and multi-step retrieval use cases. **Enterprise users** can access full Agent Composer capabilities, including:
  </p>

  <p>
    <b>Key Features</b>

    <ul>
      <li><b>Pre-built templates</b> — Start with Basic Search or Agentic Search (self-serve) or use specialized templates for Root Cause Analysis, Deep Research, Task Execution, and Structured Extraction (enterprise)</li>
      <li><b>Visual workflow builder</b> — Drag-and-drop interface for customizing agent behavior, adding tools, and defining multi-step workflows</li>
      <li><b>Custom YAML workflows</b> — Build fully customized agent workflows programmatically </li>
      <li><b>Prompt-based generator</b> — Describe your use case in natural language and let the system generate an agent configuration</li>
    </ul>
  </p>

  <p>
    <b>Documentation</b>

    <ul>
      <li><a href="/quickstarts/agent-composer">Agent Composer Quickstart Guide</a> — Get started building custom agent workflows</li>
      <li><a href="/how-to-guides/agent-composer-gui">Agent Composer GUI How-to Guide</a> — Learn to use the visual workflow builder</li>
      <li><a href="/how-to-guides/agent-composer-yaml">Agent Composer YAML How-to Guide</a> — Build workflows programmatically with YAML</li>
      <li><a href="/how-to-guides/ac-yaml-reference">Agent Composer YAML Reference Catalog</a> — Complete step type reference</li>
      <li><a href="/how-to-guides/ac-yaml-cheatsheet">Agent Composer YAML Cheat Sheet</a> — Quick reference for YAML syntax</li>
      <li><a href="https://contextual.ai/blog/introducing-agent-composer">Blog: Introducing Agent Composer</a> — Read the full launch announcement</li>
    </ul>
  </p>
</Accordion>

***


# Node.js SDK
Source: https://docs.contextual.ai/sdks/node





# Python SDK
Source: https://docs.contextual.ai/sdks/python