Custom Agents let you define your own AI agent inside Ardoq, with its own instructions, tools and behavior. Instead of re-typing the same detailed prompt every time, you write it once as an agent, and you and your colleagues can run it by name from the AI Assistant. Think of it as a custom GPT, Gem or Claude Project that knows your metamodel and your data.
Availability: Build your own Custom Agents is currently in Open Beta, but available to everyone with AI Assistant enabled.
What are Custom Agents
Custom Agents are saved sets of instructions that the AI follows. Agents perform tasks for you, ie. follow a step-by-step procedure, gather data from your Ardoq graph and produce a structured result, such as a report, a recommendation or a draft of new Ardoq data. They can also propose changes to your EA repository - with human in the loop approval.
Even though Agents are triggered via the AI Assistant, they change the behavior of the AI and follow a specific set of rules to solve your particular tasks, instead of the standard AI Assistant behavior.
Typical use cases:
Enterprise Architects: agents for architecture governance and review
Data stewards: agents for data quality checks and clean-up
IT managers: agents for operational insights
Anyone: agents that package your organization's own repeatable analysis, such as application rationalization or integration mapping
Ardoq also provides Out-of-the-box agents, see Ardoq Custom Agents.
Who can use it?
Running agents: any user with access to the Assistant and read access to the particular agent in question.
Creating and managing agents: Only Admins can create Agents currently
What are the Agents' Permissions?
An agent always runs with the permissions of the user running it. It can never show data that user is not allowed to see. In some cases agents can propose changes to Ardoq. These changes are not done directly in Ardoq, but are staged in a branch first. Merging changes into Ardoq requires correct write permissions. See more instructions on how to populate and update architecture data.
How to manage and create agents
Managing and creating agents is only available to Admins
Manage agents
Open Ardoq organization settings:
Choose the AI Settings tab and scroll down to Org-built Agents:
Here you can view and manage all agents that have been created in your Ardoq instance. You can:
Create new agents
Toggle agents on / off - ie. decide which ones should be accessible for use
Edit agents
Duplicate agents
Delete agents (this cannot be undone)
Admins can also choose what users that can access (ie. run) agents. This is done via the Access Overview under Access Control.
Please note that currently only Admins have access to editing Agents, so even though a non-admin user has Edit permission on an agent, they will only be able to see and run it, not change it.
Create agent
Click Create agent and fill in the form:
Name: The name shown on the agent's card, and the name you use to run it.
Description for Users: A short summary for people, shown on the card and shown to users if they ask what agents are installed.
Description for AI: Tells the Assistant what the agent does and when it should be used (like a skill description).
Instructions: The agent's prompt; its role, behavior and step-by-step task. See below.
Toolsets: Extra capabilities the agent may use, such as Web Search. This is optional as all core tools are always included See below.
Preferred model: Choose the type of model you want the agent to use. You can choose between Fast, Standard and Advanced. Standard is default. Use fast for smaller tasks and Advanced for the heaviest tasks.
Click Save when you are done.
Running an agent
Agents are run through the AI Assistant by asking the assistant to run a specific agent, for example:
Run the Component Overview agent
To get an overview over what agents are available, users can as the AI to list them:
List the custom agents
If the agent has variables without a default value, the Assistant asks you for them before it starts. It also tells you which values it will use before it runs. The result appears in the conversation, and you can ask follow-up questions about it.
How to write agents
To create agents that are useful, accurate and reusable you should follow some guidelines. It's also important to test and verify results agents give before they are published to the rest of the organization.
Write careful instructions
Instructions are the most important part of an agent. Be specific and describe step by step what the agent should do, what it should look at, and what the output should look like. For example, "list the applications in the workspace, check each one for a missing owner, and return a table of those without one" will give far more consistent results than "help me with data quality". Vague goals give inconsistent output.
Mention the relevant components, Viewpoints or Reports by name in the instructions if the agent should focus on them. This is how you scope an agent to specific data. This can also be done using variables.
Use variables
Add <<variable>> placeholders to your instructions for anything that changes between runs, such as <<component>>, <<component-type>> or <<workspace>>. One agent can then be reused across components, workspaces and metamodels without being rewritten.
When you run the agent, the Assistant asks you for a value for each variable. Give variables a default value where it makes sense, so the agent can run without extra input.
You can also supply values in your command, for example: "Run the Stakeholder Map agent for the Payments application."
Choose necessary toolsets
Every agent has access to core tools: reading your metamodel, traversing Viewpoints, searching components, and reading Reports and Dashboards. You don't need to select those. You can add further toolsets when the agent needs them:
Data Population: create and update Ardoq data. Changes are staged in a Scenario for review, not written straight to your live data.
Document Processing: Read and extract data from uploaded documents.
Web Search: Look up information on the web. Confirm availability. May require a separate opt-in for your organization.
Processes (ShiftX): Reason about ShiftX processes. Requires the Process Module.
Only enable the toolsets the agent really needs. It keeps behavior predictable and execution more efficient.
Testing and verification
Test the agent with a quick conversation before relying on it or sharing it. Testing includes verifying important findings against the source data as AI can make mistakes.
Security and privacy
Agents run with the permissions of the user running them and can never expose data that user cannot see.
Agents that write data stage their changes for review. Nothing is committed to your live model without approval.
Agents are built natively into Ardoq AI. No external setup or data export is required.
Agent instructions are checked by Ardoq's content safety guardrails.
Agents answer from your Ardoq data, not the AI model's training data. To use data outside Ardoq for reasoning, you must do it using either Web Search or Document attachments.
For more details about AI security, see the Ardoq AI Privacy FAQ.
Known limitations
AI can make mistakes, especially on complex multi-step tasks. Always verify important output.
An agent can only analyze data that exists in Ardoq. Missing fields, references or assets reduce quality.
If a toolset an agent depends on is unavailable for your organization (for example Web Search), the agent may fail to run instead of running in a reduced state.
While an agent is running, you cannot send further messages in that conversation.
Rules & Policies, sharing controls, scoping to selected assets, scheduled/automatic runs, and converting an existing chat into an agent are not available yet.
Agents installed from Ardoq bundles cannot currently be updated in place. A new version is installed alongside the old one, and you should delete the old version.
Frequently asked questions
Who can build a Custom Agent?
Organizations that have AI Assistant enabled
Users with the Admin role
Do agents change my data?
Only if you give them the Data Population toolset, and any changes are staged for human review.
Can I limit an agent to specific reports, Viewpoints or components?
Not through a setting yet. Name the relevant assets in the instructions.
Use variables to let the user calling the agent choose
What if an agent needs a variable I did not provide?
The Assistant asks you for it before running.
Can I control who runs an agent?
Agents are assets, so access can be managed via the Access overview.
How is this different from the agents Ardoq Out-of-the-box Agents?
Those are built and maintained by Ardoq and documented in here. This article covers building your own.