Skip to main content

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

​
2. Create a version

guild integration version create myorg~my-service
This creates a new draft version. Each integration can have multiple versions following semantic versioning.

​
3. 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

​
4. 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.

​
5. 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"}'

​
6. 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.

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

​
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:
  1. Take the raw request body as a string.
  2. Hash it using HMAC-SHA256 with the webhook secret key.
  3. Hex-encode the result and prefix it: sha256=<hex-encoded hash>
  4. 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:
EventActions
push(none)
pull_requestopened, 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.