Skip to main content
Bring Your Own Integration (BYOI) lets anyone build a 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. Use BYOI 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 BYOI 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

​
1. Create the integration

Go to Integrations 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:
TypeUse for
API keyServices that authenticate with a static token or API key
OAuthServices 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:
FieldDescription
Operation nameA unique identifier for this endpoint (becomes the tool name agents see)
HTTP methodGET, POST, PUT, PATCH, or DELETE
PathThe URL path on the target service (appended to the base URL)
DescriptionWhat 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:
  1. Build — Guild validates the configuration and assigns the semver you specified. Build status is tracked as a job.
  2. 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.

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

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