Add a Managed Guild.ai Agent as an Agent User

Give BasicOps a Guild.ai API key and a name, and it will create the agent in your own Guild.ai account and connect it back, so it becomes an Agent User you can assign tasks to and talk to in chats, channels and task discussions.

Which setup should you use?

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

BasicOps creates the agent for you. What this article covers. It takes about a minute, and you can rotate both of the agent's keys from BasicOps later. Use this unless you already have an agent you want to keep.

You connect the agent yourself. Use this 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. It takes around ten steps across Guild and BasicOps, including a webhook and a signing secret. See Add an Existing Guild.ai Agent as an Agent User (Manual Setup).

This article covers:

• Before you start
• Create a Guild API key
• Add the agent
• What BasicOps creates in Guild
• Talking to your agent
• The two keys an agent runs on
• Rotating the Guild API key
• Rotating the BasicOps API key
• If something goes wrong

Before you start

You will need:

• A BasicOps account. If you do not have one, sign up at app.basicops.com/signup.
• A Guild.ai account. Go to guild.ai, select Sign in, and create an account if you need one.
• Permission to manage users in your BasicOps workspace, since you will be adding one.

Create a Guild API key

BasicOps uses this key to do the setup work inside your Guild account. Create it first, then come back to BasicOps.

1. Go to app.guild.ai.
2. Select your organization at the top of the left sidebar.
3. Select More, then Settings.
4. Select API Keys in the left sidebar.
5. Enter a name for the key, for example BasicOps Agent.
6. Set every permission to Read & Write. Setup creates an agent, publishes a version of it, creates a workspace, installs the agent into that workspace and stores a credential for it, so it needs write access across the board.
7. Select Create Key.
8. Guild shows the key once. Copy it and keep it somewhere safe. You will paste it into BasicOps in a moment.

How BasicOps holds the key

Once Guild has accepted the key, BasicOps stores it encrypted and only ever shows you its last few characters. It is never displayed again in full, and never sent back to your browser.

Add the agent

In BasicOps, select Settings in the left sidebar, then Users, then the Agents tab. Select the chevron menu next to Add Agent, then select Add Guild Agent.

The Add Guild Agent dialog opens.

Enter a name for your agent and paste your Guild key into New Guild API Key. Two fields are optional: Key Name is a label for the key itself, and you can give the agent an avatar.

Adding a second agent

The same Guild key can provision every agent in that Guild account, so from the second agent onwards the the key you already stored appears in a dropdown. Pick it instead of pasting anything. Key Name is how you tell keys apart in that list, which is worth filling in if you expect to use more than one.

Choosing a name

Guild names are identifiers: lowercase letters, digits, hyphens, underscores and periods, up to 100 characters. BasicOps converts your agent's name for you, so Support Bot becomes support-bot in Guild, in a workspace called basicops-support-bot. The name must be unique within your Guild account. If Guild already has an agent by that name, setup stops and you can try again with a different one.

Setting up

Select Add Agent. BasicOps starts provisioning the agent in Guild and shows its progress.

This usually takes under a minute. Leave the dialog open until it finishes.

When setup is done you can add the agent to your projects, which is what gives it access to them. You can also do this later by adding the agent to a project team, exactly as you would add anyone else.

The agent then opens a direct chat with you and introduces itself. It will say it is ready and give an example or two of what you can ask it to do.

What BasicOps creates in Guild

Everything is created in your own Guild account, owned by the account your API key belongs to. If you go looking in Guild afterwards, this is what you will find:

Agent

Named after your agent, converted to a Guild name.

Published version

Carries the agent's system prompt and the list of BasicOps tools it may call.

Workspace

Called basicops- plus the agent's Guild name. Its conversations live here.

Install

The agent, installed into that workspace.

Credential

A BasicOps API key the agent calls BasicOps back with. It is written into Guild once and never shown again, here or there.

Talking to your agent

In a direct chat with the agent, just write. There is no need to mention it by name.

In a project, channel or task discussion, @-mention the agent to ask it something.

To use the agent in a project, add it to that project's team first.

For more information, see Agent Users: Put Your AI Agents to Work With Your Team.

The two keys an agent runs on

A managed Guild agent depends on two keys pointing in opposite directions. Either can be rotated without disturbing the other.

Both are rotated from the same place: on the Agents tab, select the pencil icon on the agent's row to edit it.

Both rotations below work only for agents BasicOps set up for you. An agent you connected yourself holds credentials BasicOps never issued, so it will refuse to rotate them. To change the keys on an agent like that, update them in Guild directly.

Rotating the Guild API key

This affects every agent using the key

The Guild key is stored once and shared by all the agents it set up, so rotating it switches all of them over at the same time. The Guild API Key section tells you how many agents that is before you start.

Rotate the existing key in Guild rather than creating a new one

Guild only lets an admin, or the very key that installed an agent, change that agent's credentials. If you replace the stored key with a different key from the same account, your agents keep working, but you will no longer be able to rotate their BasicOps keys, and nothing will warn you at the time. Use Guild's rotate action on the key you already have, as below.

First, in Guild:

1. Open the API Keys view and find the key you are using.
2. Select the rotate icon near the end of its row.
3. Copy the new key Guild shows you.

Then, back in BasicOps, with the agent open for editing:

1. Select Rotate in the Guild API Key section.
2. Paste the new key. You can rename the key here at the same time.
3. Select Verify and Rotate.

BasicOps checks the new key against Guild before it replaces the stored one, by asking Guild for each affected agent's install, which is the one thing every agent needs that key to reach. A key that was mistyped, revoked, or created in a different Guild account fails that check and is not stored, so it cannot silence a working agent.

Rotating the BasicOps API key

This one needs no input from you. With the agent open for editing, select Rotate in the BasicOps API Key section.

BasicOps then:

• Creates a new key
• Updates authorization in Guild
• Revokes the previous key

The order matters: the new key is proved to work, and Guild is holding it, before the old one is revoked. If any step fails, the agent carries on running on the key it already had and nothing is lost.

If something goes wrong

Setup fails with a key error

The key was mistyped, has been revoked, or belongs to a different Guild account. Nothing is stored and no half-made agent is left behind. Check the key in Guild and try again.

Setup fails on the name

Guild already has an agent with that name. Try again with a different one.

No introduction chat arrives

The greeting is a convenience, not the proof. If the agent appears on the Agents tab, it is set up. Open a direct chat and write to it.

The BasicOps key won't rotate

If the Guild key was previously replaced with a different key rather than rotated in Guild, Guild will not let BasicOps change the agent's credentials. Rotate back to a key with that authority, or set the agent up again.