Add an Existing Guild.ai Agent as an Agent User (Manual Setup)

Connect a Guild.ai agent to BasicOps so it can work as an Agent User: a dedicated AI team member that can receive BasicOps messages, respond in context, and take action from inside your workspace.

Which setup should you use?

There are two ways to connect a Guild agent to BasicOps.

BasicOps creates the agent for you. Give BasicOps a Guild API key and a name, and it creates the agent in your Guild account, connects both sides, and has it introduce itself. It takes about a minute, and you can rotate both of its keys from BasicOps later. Use this unless you already have an agent you want to keep. See Add a Managed Guild.ai Agent as an Agent User.

You connect the agent yourself. What this article covers. Use it when the agent already exists in Guild, particularly one someone else built, because BasicOps cannot set the credentials of an agent it did not create.

This article will show you how to:

1. Create an Agent User and API key in BasicOps
2. Connect BasicOps to Guild
3. If you do not have an agent yet: fork the BasicOps template
4. If you already have a Guild agent
5. Create and activate the Guild trigger
6. Register the webhook connection with BasicOps
7. Use the agent in BasicOps

Before you start

Make sure you have:

• A BasicOps account. If you do not have one, sign up at https://app.basicops.com/signup?agents.
• A Guild account. Go to https://www.guild.ai/, select Sign in, and create a new account if needed.
• Access to the BasicOps connect to BasicOps as Agent User template in Guild: https://app.guild.ai/hub/agents/basicops~connect-to-basicops-as-agent-user

Create the Agent User and API key in BasicOps

First, create a dedicated Agent User in BasicOps. This gives the Guild agent its own identity and API key.

1. In BasicOps, select Settings in the left sidebar.
2. Select Users.
3. Open the Agents tab.
4. Click Add Agent.
5. Enter the name you want to use for the agent.
6. Click Add Agent.
7. When the Add API Key dialog appears, enter a key name, such as the agent name.
8. Click Add API Key.
9. Copy the API key shown in the next dialog and store it somewhere safe. You will need it when connecting Guild to BasicOps.

Connect BasicOps in Guild

Next, connect Guild to BasicOps using the agent API key you created.

1. In Guild, open the BasicOps integration page: https://app.guild.ai/hub/integrations/basicops~basicops.
2. Click Connect.
3. Paste the BasicOps agent API key into the API Key field.
4. Click Connect to save the integration.

If you do not have an agent yet: fork the BasicOps template

After the integration is connected, add the BasicOps team member agent template to your Guild workspace.

1. Open the BasicOps connect to BasicOps as Agent User template in Guild: https://app.guild.ai/hub/agents/basicops~connect-to-basicops-as-agent-user
2. Click the menu icon next to the agent name.
3. Select Fork agent.
4. Click Continue.
5. Update the Agent Name.
6. Select a category.
7. Click Continue.
8. Click Open Editor.
9. After the build finishes, click Publish in the top right.
10. Click Next.
11. Click Add next to the workspace where you want to add the agent.
12. Click Next, then click Done.

If you already have a Guild agent

The steps above fork the BasicOps template, which creates a new agent. To connect an agent you already have, including one someone else built, keep your agent and give it the two things the template provides.

1. In Guild, open your agent in the editor.
2. In the right sidebar, under Skills, select + Skill, then Add Existing Skill. Search for basicops-webhook and select it. This is what lets the agent handle incoming BasicOps events.
3. Extend the agent's AI Instructions with the BasicOps section of the system prompt. Your existing instructions stay as they are, with the BasicOps rules added below them. See System Prompt for an External Agent.
4. Publish the agent and add it to the workspace you want to use it in.

Then continue with Create the Guild trigger below. The rest of the setup is the same.

Letting the agent set itself up

Your agent can also walk you through the remaining steps in chat. Add the basicops-connect-agent skill to it the same way, then ask it to connect itself to BasicOps. It will take you through the trigger, the credentials and the webhook secret one step at a time.

Create the Guild trigger

Create an event trigger so Guild can send BasicOps events to the agent.

1. In Guild, open your workspace from the left sidebar.
2. Select the Triggers tab.
3. Click Add Trigger.
4. Choose Event.
5. For Service, select basicops.
6. For Event Type, select push.
7. For Agent, select your agent.
8. Click Create Trigger.

Copy the Guild webhook URL

The webhook URL is the endpoint BasicOps will use to send messages to the Guild agent.

1. In the same Guild workspace, select the Credentials tab.
2. Click Manage Credentials in the top right.
3. In the credentials list, click the settings icon for basicops.
4. Enable webhooks.
5. Copy the webhook URL that appears.
6. Leave the Webhook Secret field empty for now and keep this tab open. Do not save yet.

Generate the webhook secret

Use your agent to register the webhook and generate a signing secret.

1. Open a second browser tab and return to your Guild workspace.
2. Select the Agents tab.
3. Find your agent's row.
4. Click the menu icon at the far right.
5. Select Test agent.
6. In the chat box, paste the message below. Replace [PASTE YOUR WEBHOOK HERE] with the webhook URL you copied. Leave [signature] and [payload-id] exactly as written.

Call connect_agent with webhook set to [PASTE YOUR WEBHOOK HERE], set kind to guild, set headers to: {"X-Guild-Webhook-Signature":"[signature]","X-Guild-Webhook-ID":"[payload-id]"}, set Signing to "generate", then show the generated secret.

7. Copy the secret returned by the agent.

Save and activate the trigger

After the webhook secret is generated, save it in Guild and activate the trigger.

1. Return to the first Guild tab where the webhook credential is open.
2. Paste the generated secret into the Webhook Secret field.
3. Click Save.
4. Return to the Triggers tab.
5. Find the BasicOps trigger row.
6. Click the menu icon at the far right.
7. Select Activate.

Use the agent in BasicOps

Once the trigger is active, the Guild agent can receive BasicOps messages.

• In BasicOps, @mention the Agent User in any message to ask it to help.
• To use the agent in a project, first add it to the project team.
• In a direct chat with the agent, @mentioning is not required.

Troubleshooting

If the agent does not respond in BasicOps, check the following:

• The BasicOps integration in Guild is connected with the correct Agent User API key.
• The Guild trigger is active.
• The webhook URL and webhook secret are saved in Guild.
• The Agent User has access to the BasicOps channel, task, project, or direct chat where you are messaging it.