Bindings

A binding tells Hexel which connected account to use when an agent calls a toolkit. Without a binding, the agent can’t use the tools — it’s the link between “this agent” and “these credentials for this provider.” For example, binding your support agent to your team’s Gmail connected account lets it send replies on behalf of that mailbox. A binding connects an agent to a toolkit using a specific connected account’s credentials. Without a binding, an agent cannot use a toolkit’s tools.

Key concepts

Term	Meaning
Binding	A mapping: agent + toolkit + connected account.
Connected account	The credential the binding draws on.
Resolution	The gateway automatically selecting the right credential at execution time.

How it works

Connected account + Agent + Toolkit → Binding → Agent can execute the toolkit's tools

When an agent executes a tool, the gateway resolves credentials from the agent’s bindings. You control which toolkits each agent is bound to; the platform handles credential selection.

Getting started

# Create a binding
curl -X POST https://api.hexelstudio.com/tools/v1/bindings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "toolkit": "GMAIL",
    "connected_account_id": "YOUR_CONNECTED_ACCOUNT_ID"
  }'

# List bindings
curl https://api.hexelstudio.com/tools/v1/bindings \
  -H "Authorization: Bearer $TOKEN"

Errors

HTTP	`code`	When
`400`	`INVALID_REQUEST`	Missing `agent_id`, `toolkit`, or `connected_account_id`.
`404`	—	The agent, toolkit, or connected account doesn’t exist.
`403`	—	Not permitted to manage bindings in this workspace.

Security

Concern	Detail
Credential handling	At execution time the gateway resolves credentials from the binding automatically. Your code passes inputs, never secrets.
Scoping	Bindings are scoped to your organization, workspace, and environment.
Least privilege	Grant each agent only the toolkits it actively needs. Unused bindings expand the blast radius if an agent is compromised.

Common mistakes

Binding before connecting an account. Connect the provider account first.
Over-binding. Bind only the toolkits an agent actually needs.

Best practices

Give each agent the minimum set of toolkit bindings.
Reuse one connected account across multiple agents.
Review bindings when an agent’s scope changes.

Connected Accounts

The credentials a binding uses.

Executing Tools

Run tools an agent is bound to.

Workspace Groups

Limit which tools can be bound.

Tools (concept)

The model behind bindings.

Billing & Usage

Support

Key concepts

How it works

Getting started

Errors

Security

Common mistakes

Best practices

Connected Accounts

Executing Tools

Workspace Groups

Tools (concept)

​Key concepts

​How it works

​Getting started

​Errors

​Security

​Common mistakes

​Best practices

​Related pages

Connected Accounts

Executing Tools

Workspace Groups

Tools (concept)

Key concepts

How it works

Getting started

Errors

Security

Common mistakes

Best practices

Related pages