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

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Run and manage Hex projects from Guild agents

> Connect Guild agents to Hex to run notebooks, edit cells, manage data connections, groups, users, and agent threads with server-side credentials.

Integrations · Hex

A Guild agent can trigger Hex project runs, edit notebook cells, manage workspace resources, and drive Hex agent threads without leaving your automation workflow. Guild stores your Hex API key server-side so the key never appears in agent code, prompts, or logs. Credential policies let you restrict which operations each agent may call, and every request is auditable through Guild's credential proxy.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Hex.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Hex to your first agent.

## What the Hex integration exposes

The integration package `guildai~hex` provides tools covering Hex projects, notebook cells, project runs, data connections, collections, groups, users, and agent threads. Tools follow the `hex_` naming prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to load only the tools your agent needs rather than the full set.

## How it works

**1. Get a Hex API key**

In Hex, go to Settings > API keys and generate a key. A Team or Enterprise plan is required.

**2. Connect the credential in Guild**

In Guild, go to Access & setup > Credentials, click Connect, select hex, and paste the key into API Key. See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped options.

**3. Add HexTools to your agent**

Import `HexTools` from `@guildai-services/guildai~hex` and spread it into your agent's `tools` object. Guild sends the key as a bearer token in the Authorization header on every call.

## Why Hex access needs governing

The Hex integration can deactivate users, delete cells, update project sharing, and trigger runs against published notebooks. Without controls, any agent with the credential can make those changes across the entire workspace. Guild's [credential policies](https://docs.guild.ai/platform/credential-policies.md) let you write ALLOW and DENY rules that the credential proxy enforces before any request reaches Hex. You can restrict a credential to read-only operations, limit it to specific agents or workspaces, or block destructive tools such as `hex_deactivate_user` and `hex_delete_cell` by name or pattern.

Guild stores the Hex API key server-side and injects it at the proxy layer, so agent code never sees the secret. You can scope a credential to one workspace, one member, or a single agent using the options on the [Credentials](https://docs.guild.ai/platform/credentials.md) page. A workspace can also be restricted to its own credentials, preventing shared account credentials from reaching it. Because all requests pass through the proxy, every call is logged there rather than left to individual agents to record.

## About the Hex integration

Agents can create, run, and manage Hex projects and notebooks, including editing cells and triggering project runs. They can manage workspace resources such as data connections, collections, groups, and users. Agents can also start and continue Hex agent threads and review context suggestions. The integration is `guildai~hex`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Connect Hex**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **hex**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { HexTools } from "@guildai-services/guildai~hex"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with Hex.",
  tools: { ...HexTools },
})
```

### Selecting specific tools

Tools are named with the `hex_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~hex`:

> [accordion] All 61 tools
>
> | Tool | What it does |
> | - | - |
> | `hex_batch_update_compute_profile` | Update the compute profile (kernel image and/or kernel size) on one or more projects in a single request. |
> | `hex_cancel_run` | Cancel a project run. |
> | `hex_continue_thread` | Continue an existing agent thread with a follow-up prompt. |
> | `hex_create_cell` | Create a new cell in the draft version of a project |
> | `hex_create_collection` | Create collection. |
> | `hex_create_data_connection` | Create data connection. |
> | `hex_create_group` | Create group. |
> | `hex_create_presigned_url` | Create an embedded url for a project |
> | `hex_create_project` | Create a new project in the workspace with the specified title, and optionally a description. |
> | `hex_create_thread` | Start an agent thread with a prompt. |
> | `hex_deactivate_user` | Deactivate a user |
> | `hex_delete_cell` | Delete a cell from the draft version of a project by ID |
> | `hex_delete_group` | Delete group. |
> | `hex_delete_guide_draft` | Delete guide draft. |
> | `hex_edit_collection` | Edit collection. |
> | `hex_edit_data_connection` | Edit data connection. |
> | `hex_edit_group` | Edit group. |
> | `hex_edit_project_sharing_collections` | Add a project to collections or remove it from collections. |
> | `hex_edit_project_sharing_groups` | Add groups to a project or update/remove their project sharing access. |
> | `hex_edit_project_sharing_org_and_public` | Update workspace or public-web sharing for a project. |
> | `hex_edit_project_sharing_users` | Add users to a project or update/remove their project sharing access. |
> | `hex_export_project` | Exports a Hex project in the \*.hex.yaml format. |
> | `hex_get_cell` | Get a single cell by ID |
> | `hex_get_cell_output` | Unstable: This endpoint is unstable API. |
> | `hex_get_chart_image_from_logic` | Get the rendered PNG image of a chart cell from the project's current notebook (draft) session. |
> | `hex_get_chart_image_from_run` | Get the rendered PNG image of a chart cell from a completed run by staticCellId. |
> | `hex_get_collection` | Get collection. |
> | `hex_get_data_connection` | Get a single data connection by its ID. |
> | `hex_get_group` | Get group. |
> | `hex_get_project` | Get metadata about a single project. |
> | `hex_get_project_runs` | Get the status of runs of a project. |
> | `hex_get_queried_tables` | Given a project ID, return the list of warehouse tables queried in the project. |
> | `hex_get_run_status` | Get the status of a project run. |
> | `hex_get_suggestion` | Get a single context suggestion by id, including its evidence sources and the proposed changes from its most recent review run. |
> | `hex_get_suggestion_v2` | Read a context suggestion and one page of evidence and proposed changes from its latest review. |
> | `hex_get_thread` | Get the response of an agent thread. |
> | `hex_get_thread_messages` | List the messages in an agent thread, rendered as a single flat list of text blocks. |
> | `hex_ingest_semantic_project` | Ingest a semantic project from a zip file. |
> | `hex_list_agent_usage` | List per-agent-run credit usage for the workspace, most recent run first. |
> | `hex_list_cells` | List cells from the draft version of a project. |
> | `hex_list_collections` | List collections. |
> | `hex_list_credit_grants` | List the workspace's credit grants, most recent first. |
> | `hex_list_data_connections` | List the workspace's data connections. |
> | `hex_list_draft_guides` | List draft guides |
> | `hex_list_groups` | List groups. |
> | `hex_list_projects` | List all viewable projects, sorted by most recently created first. |
> | `hex_list_suggestions` | List context suggestions for the workspace. |
> | `hex_list_threads` | List agent threads in the workspace, sorted by most recently created first. |
> | `hex_list_topics` | List thread topics in the workspace, sorted by name. |
> | `hex_list_users` | List all users in the workspace |
> | `hex_me` | Returns information about the current logged in user. |
> | `hex_publish_guide_drafts` | Publish all currently drafted guides. |
> | `hex_run_project` | Trigger a run of the latest published version of a project. |
> | `hex_trigger_suggestion_review` | Trigger a background review agent run for the given context suggestion. |
> | `hex_update_cell` | Update a cell's source and/or data connection. |
> | `hex_update_data_connection_schema` | Use this endpoint to add or remove a status (including endorsements) from databases, schemas, and tables within a data connection |
> | `hex_update_project` | Add or remove a status, including endorsements, from a project. |
> | `hex_update_semantic_project` | Use this endpoint to add or remove a status (including endorsements) from datasets and views within a semantic project |
> | `hex_update_suggestion` | Update the status of a context suggestion. |
> | `hex_update_suggestion_change` | Update the status of an individual proposed change within a context suggestion. |
> | `hex_upsert_guide_draft` | Update or create guide drafts by filePath. |

## Frequently asked questions

> [accordion] Can an agent react to events in Hex, like when a run finishes?
>
> No. The catalog entry for `guildai~hex` lists no webhook events, so the integration does not support event-triggered runs. Agents must poll run status using tools such as `hex_get_run_status` or `hex_get_project_runs`.

> [accordion] How do I stop an agent from deactivating Hex users or deleting cells?
>
> Write a DENY rule in the credential's [credential policy](https://docs.guild.ai/platform/credential-policies.md) targeting `hex_deactivate_user` and `hex_delete_cell` by name. DENY rules take precedence over any ALLOW rules, so those operations are blocked even if a wildcard ALLOW is also present.

> [accordion] Can I give one agent a different Hex account than the rest of my workspace?
>
> Yes. Connect a dedicated credential from the installed agent's page, or grant an existing credential to that agent alone. Guild's credential resolution checks agent-dedicated and granted credentials before falling back to workspace or account credentials, so that agent will always use its own key.

> [accordion] How does Guild keep my Hex API key out of agent code?
>
> Guild stores the key and injects it as a bearer token in the Authorization header inside its credential proxy. The key never enters the agent's code, container, prompt, or state, as described in the [security architecture](https://docs.guild.ai/platform/security-architecture.md) and [Credentials](https://docs.guild.ai/platform/credentials.md) docs.

## Put a governed agent on Hex this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Hex.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Hex to your first agent.

## Related

**Also runs on Guild:** [Airtable](https://docs.guild.ai/integrations/airtable.md) · [BigQuery](https://docs.guild.ai/integrations/bigquery.md) · [Nexla](https://docs.guild.ai/integrations/nexla.md) · [PostHog](https://docs.guild.ai/integrations/posthog.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)