> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/tutorials/building-a-link-manager-sub-agent.md). # Extending Your General Assistant with a Link Manager Sub-Agent Extend your organisation's General Assistant with URL-shortening and link-management capabilities by delegating to a dedicated Rebrandly-powered sub-agent. | **Time to complete** | \~30 minutes | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Who this is for** | Marketing team members and Content Editors who already use the Assistant day-to-day and want it to shorten and manage links in chat. | ## What You Will Build By the end of this tutorial your organisation's **General Assistant** - the same assistant your team already opens from the **Ask AI** button - will be able to shorten, tag, and look up links using [Rebrandly](https://www.rebrandly.com), without you adding any link-shortening logic to the Assistant itself. Instead, you will build a small, focused **Link Manager** sub-agent and delegate link-related requests to it. Your teammates will be able to open the Assistant from anywhere in the platform and ask things like: * *"Shorten this link for our newsletter: "* * *"Create a tagged short link for our Black Friday campaign pointing to "* * *"What does the short link acme.co/launch point to?"* ...and get the answer back in the same conversation, while the Assistant's own instructions stay short and unrelated to the mechanics of any single tool. ## Step 1: Understand Agent Delegation Before building anything, it helps to understand *why* this tutorial asks you to create a separate sub-agent instead of just adding Rebrandly as a tool directly on the Assistant. ### 1.1 - Why delegate instead of adding tools directly? * **Limited context window** - every tool and instruction you add to the Assistant is loaded on *every* run, even when the user is asking about something unrelated to links. Keeping the Assistant's own instructions short and general keeps it fast, cheap, and focused. * **Divide and conquer** - a small, single-purpose agent with a handful of tools and a narrow job is easier to write good instructions for, easier to test, and easier to reason about than one giant agent that tries to do everything. This is the same principle behind the classic [divide-and-conquer](https://en.wikipedia.org/wiki/Divide-and-conquer_algorithm) approach to solving problems: break a large, general problem into smaller, specialised ones, solve each independently, and combine the results. * **Least privilege** - the Assistant itself never needs direct access to your Rebrandly API key. Only the Link Manager sub-agent does, which limits how many places that credential is wired into. * **Maintainability** - if Rebrandly changes its tools, or you later switch to a different link-shortening provider, you only need to update the Link Manager sub-agent. The Assistant's instructions and every other sub-agent are untouched. > **Note on cost:** Delegating a task still runs an additional agent (and therefore consumes credits for that sub-agent's own model calls), on top of the Assistant's own run. For an occasional, well-scoped task like link shortening this overhead is small, but it is worth being aware of if your organisation tracks Budget closely - see [Budget](/manual/organisation/budget.md). ### 1.2 - How delegation works on the platform Three pieces make delegation possible - all covered in more depth in [Agent Delegation](/manual/agents/agent-delegation.md): * **Sub-agents** - any agent can be marked **"Can be sub-agent"** in its General Properties, making it eligible to be called by other agents. * **The Agents MCP Server** - a built-in server (`internal://agents`) that lets a parent agent list, inspect, and run its linked sub-agents. See [Agents MCP Server](/manual/organisation/built-in-mcp-servers/agents-mcp-server.md). * **The `@identifier` invoke syntax** - in a conversation or in an agent's instructions, `@link-manager` refers to the sub-agent with the identifier `link-manager`, helping the parent agent (or a user) address the right specialist. ### 1.3 - Prerequisites Before you start, make sure the following are in place: * Your organisation already has a **General Assistant** (or another agent set as the **Default Assistant Agent** - see [Organisation Settings](/manual/organisation/organisation-settings.md)) that your team uses via the **Ask AI** button. See [Assistant](/manual/assistant.md). * You are the **creator** of that Assistant agent, or you have **Owner**/**Administrator** permissions - editing an existing agent's Sub-Agents and instructions requires one of these. * The built-in **Agents MCP Server** (`internal://agents`) is **Enabled**. Go to **Organisation → MCP Servers** and confirm. * At least one **AI model** has been connected and enabled for your organisation. * A [Rebrandly](https://www.rebrandly.com) account. The free tier is enough to complete this tutorial. > ⚠️ **Safety note:** The Assistant you are about to edit may already be used by your whole organisation. Changes to its instructions and sub-agents take effect immediately for everyone. Consider doing this tutorial first on a test/staging agent if your organisation has one, and always re-test a few unrelated prompts (e.g. *"Hi, what can you do?"*) after making changes to confirm you haven't broken its existing behaviour. ## Step 2: Add Rebrandly as an MCP Server {% hint style="info" %} Adding or editing an MCP Server requires **Owner** or **Administrator** permissions for your organisation. If you don't have access, ask your organisation's Owner or Administrator to complete this step for you, or to grant you the required permissions. See [MCP Servers](/manual/organisation/mcp-servers.md#before-you-begin). {% endhint %} ### 2.1 - About Rebrandly Rebrandly is a URL-shortening and link-management service. It lets you create branded short links (with a custom "slashtag" - the back half of the link), tag and organise them into workspaces, and later look up which destination a short link points to or pull click analytics. In this tutorial you will connect its hosted MCP server to the platform so an agent can call it as a tool. See Rebrandly's own [Quick start for MCP](https://developers.rebrandly.com/docs/quick-start-for-mcp) and [MCP tools reference](https://developers.rebrandly.com/docs/mcp-tools-reference) for background. {% hint style="info" %} This tutorial uses **Rebrandly** purely as a **worked example** of a link-shortening service with an MCP server. Ibexa is not affiliated with, endorsed by, or sponsored by Rebrandly. Feel free to substitute any other URL-shortening provider your organisation prefers (e.g. short.io, Bitly, Dub) - the same pattern of connecting it as an MCP Server and delegating to a dedicated sub-agent still applies. {% endhint %} ### 2.2 - Create a Rebrandly account (optional) If you don't already have one: 1. Go to and select **Start for free**. 2. Create an account with your email address, or sign in with the identity provider of your choice. 3. Confirm your email address if prompted. Rebrandly's free plan is sufficient for this tutorial and for light, ongoing use - check your plan's monthly link and click limits if you expect heavy usage. ### 2.3 - Generate an API key 1. Once logged in, go directly to (or navigate to **Settings → API Keys** from the Rebrandly app). 2. Select **New API key**, give it a recognisable name (e.g. `agent-platform`), and create it. 3. Select the **copy** icon to copy the generated key. **Keep this key safe.** Treat it like a password - do not share it publicly or paste it into a chat or email. You will enter it into the platform in the next step using a secure, masked field.
The Rebrandly Settings > API Keys page, showing the New API key button and a list of existing keys

The API Keys page in Rebrandly's Settings, where you create and manage your API keys.

### 2.4 - Add and verify the Rebrandly MCP Server Rebrandly exposes a hosted MCP endpoint that accepts your API key as a header - no separate account linking is required. 1. Go to **Organisation → MCP Servers** in the main navigation menu. 2. Select **Add MCP Server** to open the **MCP Browser**. 3. Search the catalog for **Rebrandly**. * **If a Rebrandly entry exists in your organisation's catalog**, select it and select **Add MCP Server** on its card. The dialog is pre-filled with the server's **Name** and **URL** - you only need to fill in the **Authentication** section. * **If no matching entry appears**, select **Add custom MCP Server** instead and fill in: | Field | Value | | -------- | ---------------------------------- | | **Name** | `Rebrandly` | | **URL** | `https://mcp.rebrandly.com/v1/mcp` | 4. Under **Authentication**, choose **API Key** and fill in: | Field | Value | | ----------------- | ---------------------------------- | | **Name** | `REBRANDLY_API_KEY` | | **API Key value** | The API key you copied in Step 2.3 | | **Location** | **Header** | 5. Select **Save** (or **Add MCP Server**). You are taken to the server's detail page. 6. Verify MCP Server. A success message confirms the server is reachable and lists the tools it exposes (for example, creating a link, listing links, retrieving link details, and querying click metrics). If verification fails, double-check that the API key was copied correctly and has not been revoked or regenerated since. > See [MCP Servers](/manual/organisation/mcp-servers.md) for the full reference on catalog vs. custom servers, headers, and authentication schemes. ## Step 3: Create the "Link Manager" Sub-Agent With Rebrandly connected, build the specialist agent that will actually do the link-shortening work. ### 3.1 - Open the Agents page Select **Agents** in the main navigation menu, then select **Add Agent**. In the **Agents Browser**, select **Add Custom Agent** to go straight to the creation wizard. ### 3.2 - Step 1 of 6: Instructions Enter instructions that keep this agent narrowly focused on link management - it should not try to answer unrelated questions: ``` You are a Link Manager agent. Your only job is to create, tag, and look up short links using Rebrandly. When asked to shorten a link: 1. Use the Rebrandly "create link" tool to create a short link for the exact destination URL provided. 2. If the request specifies a custom slashtag (the back half of the link), use it; otherwise let Rebrandly generate one. 3. If the request mentions a campaign, channel, or purpose (e.g. "newsletter", "Black Friday"), add it as a tag on the link so it can be found later. 4. Return the resulting short link clearly, along with any tags or slashtag you applied. When asked what a short link points to, or to list/count existing links: 1. Use the appropriate Rebrandly tool ("get link details", "list links", or "count links") to look up the information. 2. Report the destination URL, tags, and click count if available. When asked about link performance or clicks: 1. Use the Rebrandly "query metric" tool to answer questions about clicks (e.g. total clicks, by country, over a date range). 2. Report the figures plainly, noting the date range used. Rules: - Only act on links and destinations explicitly given to you. Do not invent URLs. - If a request is not about creating, tagging, looking up, or reporting on a link, say this is outside your role and that the request should be handled by the general Assistant instead. - Keep responses short and factual - a link (or list of links), any tags applied, or the requested metrics, nothing else. ``` > **Why these instructions?** Because this agent will only ever be reached through delegation, its instructions can stay narrow and mechanical - there's no need to teach it how to make small talk or handle unrelated topics. The explicit "outside your role" rule also gives the parent Assistant a clean signal if it ever routes something here by mistake. Select **Next**. ### 3.3 - Step 2 of 6: Triggers Even though this agent will only ever be started via delegation, the platform still requires at least one trigger. 1. Select **Add trigger**. 2. Choose **Run Now** from the trigger type list. 3. Leave all settings at their defaults. Select **Next**. ### 3.4 - Step 3 of 6: Tools 1. Select **Select tools**. 2. Find the **Rebrandly** server you added in Step 2. 3. Tick the tools this agent needs - at minimum **Create a link**, **Get link details**, **List links**, and **Query metric** (for click analytics). Add **Update a link**, **Count links**, and **Delete a link** if you want the agent to handle those cases too. See the [MCP tools reference](https://developers.rebrandly.com/docs/mcp-tools-reference) for the full list. 4. Confirm your selection and return to the wizard. Select **Next**. ### 3.5 - Step 4 of 6: Knowledge Base | Field | What to select | | ---------- | ------------------------------------------------------------------- | | **Access** | **None** - this agent only needs Rebrandly, not internal documents. | Select **Next**. ### 3.6 - Step 5 of 6: Quality Metrics Leave this step empty for now - you can configure quality monitoring later from the agent's **Edit** page. Select **Next**. ### 3.7 - Step 6 of 6: General Properties | Field | What to enter | | --------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Name** | `Link Manager` | | **Identifier** | `link-manager` *(auto-filled from the name - leave as is)* | | **Description** | `Creates, tags, and looks up short links using Rebrandly.` | | **Model** | Choose the AI model your organisation uses. A smaller/cheaper model is usually sufficient for this narrow task. | | **Can be sub-agent** | ✅ **Check this** - required so other agents (including the Assistant) can delegate to it. | | **Maximum number of steps** | Leave at the default (**25**) - link shortening is a simple task and won't need many steps. | Select **Submit**. You are taken to the new agent's detail page. ## Step 4: Test the Link Manager in Isolation Before wiring the Link Manager into your Assistant, confirm it works correctly on its own. This makes it much easier to tell tool/authentication problems apart from delegation problems later. 1. From the **Link Manager** agent's detail page, open the actions menu and select **Run test**. 2. Try a few messages directly in the test chat: * *"Shorten this link for our newsletter: "* * *"What does point to once shortened?"* (an off-format question - see how it responds) 3. Confirm the agent returns a working short link and applies a sensible tag. If it fails, see [Troubleshooting](#troubleshooting) below before continuing. ## Step 5: Link the Sub-Agent to Your General Assistant Now connect the Link Manager to the Assistant your team already uses. ### 5.1 - Open your Assistant agent Go to **Agents**, find your **General Assistant** (or whichever agent is set as your organisation's **Default Assistant Agent**), and open its detail page. ### 5.2 - Link the sub-agent 1. Select **Edit**. 2. In the **Sub-Agents** section, select **Add sub-agent**. 3. Choose **Link Manager** (`link-manager`) from the list of available sub-agents. An agent can only call sub-agents explicitly linked here. ### 5.3 - Update the Assistant's instructions (optional) Still in **Edit** mode, add a short pointer to the Assistant's existing instructions so it knows when to delegate. For example, append: ``` When a user asks you to shorten a URL, create a tracked/tagged link, or look up what an existing short link points to, delegate the task to @link-manager and return its response to the user. ``` Select **Submit** to save your changes. > ⚠️ Refer back to the safety note in [Step 1.3](#13---prerequisites): re-test a couple of unrelated prompts against the Assistant after saving, to confirm its general behaviour is unaffected. ## Step 6: Test via the Assistant Panel 1. Open the **Ask AI** panel from the top bar (see [Assistant](/manual/assistant.md)). 2. Send: *"Shorten this link for our newsletter: "* 3. Watch the Assistant delegate the request - it should return a short link (and mention any tag applied) within a few seconds. 4. Try a follow-up unrelated question (e.g. *"What can you help me with?"*) to confirm the Assistant still behaves normally outside of link-related requests. ## Troubleshooting | Issue | Likely cause | Fix | | ------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Rebrandly server verification fails | API key is missing, incorrect, or revoked | Go to **Organisation → MCP Servers → Rebrandly → Edit** and re-enter the API key from . | | Link Manager agent can't be found when adding a sub-agent | The agent's **"Can be sub-agent"** checkbox is unchecked | Edit the Link Manager agent's General Properties and check **Can be sub-agent**. | | Assistant answers link questions itself instead of delegating | Assistant instructions don't clearly mention `@link-manager` | Make the delegation instruction in [5.3](#53---update-the-assistants-instructions-optional) more explicit and specific. | | Assistant says it has no sub-agent named `link-manager` | The sub-agent isn't linked, or its identifier doesn't match | Confirm the identifier in the Link Manager's **General Properties** is exactly `link-manager` and that it's linked in [5.2](#52---link-the-sub-agent). | | Link Manager returns an error when creating a link | Rebrandly tool call failed (bad URL, rate limit, or invalid auth) | Test the Link Manager in isolation ([Step 4](#step-4-test-the-link-manager-in-isolation)) to confirm the tool works before blaming delegation. | | Assistant's unrelated answers changed after this tutorial | Editing shared instructions affected other behaviour | Review your instruction edit for unintended side effects; consider keeping the added instruction as short and scoped as shown in [5.3](#53---update-the-assistants-instructions-optional). | ## Summary You've extended your organisation's Assistant with a new capability without bloating its own instructions: 1. ✅ Learned why and how agent delegation works on the platform. 2. ✅ Connected Rebrandly as an MCP Server with secure API key authentication. 3. ✅ Built a focused Link Manager sub-agent and marked it available for delegation. 4. ✅ Tested the sub-agent in isolation before wiring it up. 5. ✅ Linked it to your General Assistant and confirmed delegation works end to end. ## Next Steps * **Add UTM tagging** - update the Link Manager's instructions to automatically append UTM parameters (source, medium, campaign) based on the channel mentioned in the request. * **Route links to the right workspace or branded domain** - extend the Link Manager's instructions and tool selection to pick a workspace or domain automatically based on the campaign or brand mentioned in the request. * **Reuse the pattern** - the same divide-and-conquer approach works for any other narrow, tool-heavy task you don't want baked into your General Assistant's own instructions. ## Resources * [Agent Delegation](/manual/agents/agent-delegation.md) * [Agents MCP Server](/manual/organisation/built-in-mcp-servers/agents-mcp-server.md) * [MCP Servers](/manual/organisation/mcp-servers.md) * [Rebrandly - Quick start for MCP](https://developers.rebrandly.com/docs/quick-start-for-mcp) * [Rebrandly - MCP tools reference](https://developers.rebrandly.com/docs/mcp-tools-reference) * [Divide-and-conquer algorithm - Wikipedia](https://en.wikipedia.org/wiki/Divide-and-conquer_algorithm)