Create an Integration

You can build a custom Guild integration for any HTTP-accessible service. You don’t need to be a Guild engineer or wait for first-party support — if your service has an API, you can connect it. Create a custom integration when:

You need an integration for a private or internal service (e.g., an internal deployment platform, a self-hosted tool)
A first-party integration doesn’t exist yet for a public service you use
You want to customize how agents interact with a service beyond what a first-party integration offers

How it works

A custom integration is a versioned package that tells the Guild runtime how to proxy HTTP requests to your service on behalf of agents. You define the endpoints, authentication method, and request/response schemas. Once published, agents can call your integration’s tools exactly like any first-party integration.

Agent → Guild runtime → Integration proxy → Your service API
                ↓
        Handles auth, rate limiting,
        credential injection

The runtime injects credentials automatically, so agents never see raw API keys or tokens.

Creating an integration

You can create integrations from the Guild UI or entirely from the CLI.

1. Create the integration

guild integration create my-service \
  --base-url https://api.example.com \
  --auth-scheme api-key \
  --description "Connect to the Acme API"

For OAuth services, provide the OAuth configuration:

guild integration create my-oauth-service \
  --base-url https://api.example.com \
  --auth-scheme oauth \
  --install-url https://example.com/oauth/authorize \
  --token-url https://example.com/oauth/token \
  --client-id <id> --client-secret <secret> \
  --scopes "read,write"

Use --public to make the integration visible to all users. By default it is private to your account.The command also creates a draft version automatically.

2. Define operations

Add operations (endpoints) to your draft version. Each operation becomes a tool that agents can call.Add operations manually:

guild integration operation create myorg~my-service \
  --operation list_users \
  --method GET \
  --path /users \
  --summary "List all users"

guild integration operation create myorg~my-service \
  --operation get_user \
  --method GET \
  --path /users/{id} \
  --summary "Get a user by ID"

Or import from an OpenAPI spec:

guild integration operation create myorg~my-service --openapi ./openapi.yaml

You can optionally provide JSON schema files for request and response bodies:

guild integration operation create myorg~my-service \
  --operation create_user \
  --method POST \
  --path /users \
  --summary "Create a new user" \
  --input-body-schema ./create-user-input.json \
  --output-body-schema ./create-user-output.json

3. Build and publish

# Build (validate) and assign a version number
guild integration version build myorg~my-service --version-number 1.0.0

# Publish the built version
guild integration version publish myorg~my-service --version-number 1.0.0

Version numbers must be strictly increasing — you cannot publish 1.0.0 after 1.1.0.

4. Test

Test an operation against the live API:

guild integration version test myorg~my-service \
  --operation list_users \
  --account my-account \
  --input-query '{"limit": 10}'

Pass path parameters, query parameters, and request bodies as JSON:

guild integration version test myorg~my-service \
  --operation get_user \
  --account my-account \
  --input-path '{"id": "user-123"}'

5. Connect credentials

guild integration connect myorg~my-service --token <api-key>

Omit --token for an interactive prompt. Use --owner to connect credentials for an organization account.

6. Configure webhooks (optional)

Pass webhook event definitions as JSON when creating or updating the integration:

guild integration create my-service \
  --base-url https://api.example.com \
  --auth-scheme api-key \
  --webhook-events '[{"event": "push"}, {"event": "pull_request", "actions": ["opened", "closed"]}]'

Or update an existing integration:

guild integration update myorg~my-service \
  --webhook-events '[{"event": "deploy", "actions": ["started", "completed", "failed"]}]'

See Webhook format below for delivery requirements.

1. Create the integration

Go to the Integration Hub in the Guild UI and click Create Integration. Provide:

Name — a unique identifier for your integration
Description — what the integration connects to and what it does
Protocol — choose REST or MCP:
- REST — the base URL of the target API. Optionally set Extra headers (a map of header names to values) to include additional static headers on every proxied request.
- MCP — the MCP server URL. Optionally set Extra headers (a map of header names to values) to include additional static headers on every proxied request.
Authentication — how the target service authenticates requests

Authentication types:

Type	Use for
API key	Services that authenticate with a static token or API key
OAuth	Services that use OAuth 2.0 flows (Guild manages the token lifecycle)

2. Create a version

Creating the integration automatically creates a draft version 1. Each integration can have multiple versions that follow semantic versioning.

3. Define endpoints

Each endpoint maps to an operation on the target service. An endpoint definition includes:

Field	Description
Operation name	A unique identifier for this endpoint (becomes the tool name agents see)
HTTP method	`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
Path	The URL path on the target service (appended to the base URL)
Description	What the endpoint does — shown to LLMs when choosing tools

You can define endpoints in three ways:

Manually — add endpoints one at a time in the UI
From an OpenAPI specification — upload a spec and Guild generates endpoint definitions automatically
Copy from a previous version — carry forward endpoints from an earlier version and modify as needed

4. Build and publish

Once your endpoints are defined:

Build — Guild validates the configuration and assigns the semver you specified. Build status is tracked as a job.
Publish — the version becomes available for agents to use in workspaces.

Version numbers must be strictly increasing — you cannot publish 1.0.0 after 1.1.0.

5. Test

Use the Test page on a version to invoke endpoints interactively. You can set path parameters, query parameters, and a request body, then see the full response including status code, headers, and body.

6. Configure webhooks (optional)

If your service sends events to Guild, you can define which webhook events the integration supports. This is optional — skip this step if your integration is request-only. Once configured, workspace users can create webhook triggers that fire agents automatically when your service emits an event.Open the integration’s Configuration tab and click Configure webhooks in the Webhooks section. See Webhook format below for delivery requirements.

Webhook format

If your integration receives inbound webhooks, your service must send a JSON body matching this format:

{
  "event": "push",
  "action": "opened",
  "payload": { ... }
}

action is null for events that don’t have sub-actions. Each delivery must include these headers: X-Guild-Webhook-Signature A cryptographic signature that proves the delivery came from the integration and hasn’t been tampered with in transit. Guild rejects deliveries with a missing or invalid signature. Generate it as follows:

Take the raw request body as a string.
Hash it using HMAC-SHA256 with the webhook secret key.
Hex-encode the result and prefix it: sha256=<hex-encoded hash>
Set that as the value of the X-Guild-Webhook-Signature header.

X-Guild-Webhook-ID A unique identifier for each individual delivery (e.g., a UUID generated fresh per request). Guild uses this to detect and discard duplicate deliveries, which is important because many systems retry failed webhook requests. Content-Type Must be set to application/json. How the webhook URL is set up When a user connects the integration and wants to receive webhook events, Guild generates a unique webhook URL for that connection. The user registers this URL with the external service (usually on its webhook configuration page) so the service knows where to send deliveries. How the secret key is established During that same registration, the external service typically reveals a secret key. The user copies the secret back into Guild, which stores it with the connection and uses it to verify the X-Guild-Webhook-Signature on every incoming delivery. Deliveries with a missing or mismatched signature are rejected. Defining events Each event has a name and an optional list of actions. For example:

Event	Actions
`push`	(none)
`pull_request`	`opened`, `closed`, `merged`, `reopened`

Using your integration

Once published, your integration’s tools appear alongside first-party tools in the workspace. Agents import and use them the same way as any other service integration:

import { myServiceTools } from "@guildai-services/my-org~my-service";
import { llmAgent, guildTools } from "@guildai/agents-sdk";

export default llmAgent({
  description: "An agent that uses a custom integration.",
  tools: { ...myServiceTools, ...guildTools },
  systemPrompt: `You have access to the Acme API.
Use it to look up customer records when asked.`,
});

Connecting credentials

When a custom integration requires authentication, the workspace administrator configures credentials in Settings > Credentials at app.guild.ai, just like first-party integrations. If an agent invokes a tool from an unconfigured integration, Guild prompts the user to connect their account.

Webhooks

Custom integrations can also receive inbound webhooks from integrations. Configure a webhook URL in your integration, and external events will be routed to agents via triggers.

​How it works

​Creating an integration

​1. Create the integration

​2. Define operations

​3. Build and publish

​4. Test

​5. Connect credentials

​6. Configure webhooks (optional)

​1. Create the integration

​2. Create a version

​3. Define endpoints

​4. Build and publish

​5. Test

​6. Configure webhooks (optional)

​Webhook format

​Using your integration

​Connecting credentials

​Webhooks

How it works

Creating an integration

1. Create the integration

2. Define operations

3. Build and publish

4. Test

5. Connect credentials

6. Configure webhooks (optional)

1. Create the integration

2. Create a version

3. Define endpoints

4. Build and publish

5. Test

6. Configure webhooks (optional)

Webhook format

Using your integration

Connecting credentials

Webhooks