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.
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
Creating an integration
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 — REST (with the base URL for the target API)
- 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
Each integration has one or more versions that follow semantic versioning. Create a new version to start defining endpoints.
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 |
- 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.
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. 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.
How the secret key is established
When a user connects the integration and wants to receive webhook events, Guild provides a webhook URL for them to register on the integration. During that registration, the integration typically reveals a secret key; the user copies that secret into Guild. Guild then uses it to verify the signature on every incoming delivery.
Defining events
Click Add event to define the events your service can emit. 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.
