Run and manage Hex projects from Guild agents

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.

Book a demo

See how teams govern agents that use Hex.

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() to load only the tools your agent needs rather than the full set.

How it works

Get a Hex API key

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

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 for workspace, member, and agent-scoped options.

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 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 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

Connect Hex

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

See Credentials for workspace, member, and agent-scoped credentials.

Usage

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() to include only what your agent needs.

Tools

Tools in the latest published version of guildai~hex:

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

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.

How do I stop an agent from deactivating Hex users or deleting cells?

Write a DENY rule in the credential’s credential policy 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.

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.

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 and Credentials docs.

Put a governed agent on Hex this week

Book a demo

See how teams govern agents that use Hex.

Talk to sales

Get access to Guild, then connect Hex to your first agent.

Also runs on Guild: Airtable · BigQuery · Nexla · PostHog Read: Docs: Credential policies · Credentials · Tools in agents

Overview

Code & CI/CD

Communication

Customer support

Data

Design

Inference providers

Models

Monitoring & observability

Productivity

Project management

Recruiting

Sales & finance

Testing

Web & search

Run and manage Hex projects from Guild agents

Book a demo

Talk to sales

What the Hex integration exposes

How it works

Why Hex access needs governing

About the Hex integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Frequently asked questions

Put a governed agent on Hex this week

Book a demo

Talk to sales

Book a demo

Talk to sales

​What the Hex integration exposes

​How it works

​Why Hex access needs governing

​About the Hex integration

​Authentication

​Setup

​Usage

​Selecting specific tools

​Tools

​Frequently asked questions

​Put a governed agent on Hex this week

Book a demo

Talk to sales

​Related

What the Hex integration exposes

How it works

Why Hex access needs governing

About the Hex integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Frequently asked questions

Put a governed agent on Hex this week

Related