Managing foundational agents | GitLab Docs
/ Managing foundational agents This guide covers foundational agents . For foundational flows , see the foundational flows guide . To understand the difference between agents and flows, see the glossary . Foundational agents are specialized agents that are created and maintained by GitLab, providing more accurate responses for specific use cases. These agents are available by default on any place chat and GitLab Duo chat are available, including groups, and are supported on GitLab Duo Self-Hosted.
Create a foundational agent There are two ways of creating a foundational agent, using the AI Catalog or GitLab Duo Workflow Service. AI Catalog provides a user-friendly interface, and it is the preferred approach, but writing a definition on GitLab Duo Workflow Service provides more flexibility for complex cases. Using the AI catalog Create your agent on the AI Catalog , and note its ID. Make sure the agent is set to public.
Example: Planner Agent has ID 348. Agents created on the AI Catalog need to be bundled into GitLab Duo Workflow Service, so they can be available to self-hosted setups that do not have access to our SaaS. To achieve this, open an MR to GitLab Duo Workflow Service adding the ID of the agent: diff # https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/Dockerfile - RUN poetry run fetch-foundational-agents "https://gitlab.com" "$GITLAB_TOKEN" "348" \ + RUN poetry run fetch-foundational-agents "https://gitlab.com" "$GITLAB_TOKEN" "duo_planner:348,<agent-reference>:<agent-catalog-id>" \ The command above can also be executed locally for testing purposes.
Agent reference must be lowercase without spaces (example: ’test_agent’). To make the agent be selectable, add it to the FoundationalChatAgentsDefinitions.rb . Use the reference used in the Dockerfile: ruby { id : 3 , reference : '<agent-reference>' , version : 'v1' , name : 'Test Agent' , description : "An agent for testing" } Add suggested questions for the agent, as described in Suggested questions . Update user facing documentation .
Using GitLab Duo Workflow Service Create a flow configuration file in /duo_workflow_service/agent_platform/v1/flows/configs/ (located either on your GDK under PATH-TO-YOUR-GDK/gdk/gitlab-ai-gateway or on the ai-assist repository ): File: /duo_workflow_service/agent_platform/v1/flows/configs/foundational_pirate_agent/1.0.0.yml yaml version : "v1" environment : chat-partial components : - name : "foundational_pirate_agent" type : AgentComponent prompt_id : "foundational_pirate_agent_prompt" inputs : - from : "context:goal" as : "goal" - from : "context:project_id" as : "project_id" toolset : [] ui_log_events : [] prompts : - name : Foundational Pirate Agent prompt_id : "foundational_pirate_agent_prompt" model : params : model_class_provider : anthropic max_tokens : 2_000 prompt_template : system : | You are a seasoned pirate from the Golden Age of Piracy.
You speak exclusively in pirate dialect, using nautical terms, pirate slang, and colorful seafaring expressions. Transform any input into authentic pirate speak while maintaining the original meaning. Use terms like 'ahoy', 'matey', 'ye', 'aye', 'landlubber', 'scallywag', 'doubloons', 'plunder', etc. Add pirate exclamations like 'Arrr!', 'Shiver me timbers!', and 'Yo ho ho!' where appropriate. Refer to yourself in the first person as a pirate would. user : | {{goal}} placeholder : history routers : [] flow : entry_point : "foundational_pirate_agent" Add your agent definition to FoundationalChatAgentsDefinitions.rb : ruby # frozen_string_literal: true module Ai module FoundationalChatAgentsDefinitions extend ActiveSupport :: Concern ITEMS = [ { id : 1 , reference : 'chat' , version : '' , name : 'GitLab Duo Agent' , description : "GitLab Duo is your general development assistant" }, { id : 2 , reference : 'foundational_pirate_agent' , version : 'v1' , name : 'Foundational Pirate Agent' , description : "A most important agent that speaks like a pirate" } ]. freeze end end Add suggested questions for the agent, as described in Suggested questions .
Update user facing documentation . Tips: You can use the AI Catalog to test foundational agents, even before you add them to the codebase. Create a new private agent in the AI Catalog with the same prompt and same tools, and enable it on your test project. Once results reach desired levels, add to GitLab Duo Workflow Service. Add prompts to the GitLab Duo Workflow Service to enable testing the agent in your local GDK.
The version field of an agent in FoundationalChatAgentsDefinitions.rb should be v1 , regardless of whether the agent is defined in AI Catalog or GitLab Duo Workflow Service. Update a foundational agent Use this process when you change an existing foundational agent’s prompt, toolset, or flow configuration: Develop and test locally. Make the change in your GDK’s gitlab-ai-gateway checkout, restart the service with gdk restart duo-workflow-service , and iterate on the agent in chat until it behaves as intended.
This step is exploratory and shapes the change. See Developing foundational agents locally . Propose the change. Open a merge request to the ai-assist repository that updates the flow configuration. Bump the flow version according to the versioning guidance : patch for bug fixes, minor for backwards-compatible additions, major for breaking changes. Evaluate the change. Unlike exploratory local testing, this step produces objective evidence that the change does not regress the agent.
Where the agent has a benchmark or integration test suite, run it, compare the scores against the previous baseline, and record the results in the merge request. See Integration testing foundational agents . Validate the change in at least one full chat session before merging. Merge the change. The change follows the ai-assist code review process . If the change is a major version, or changes the agent’s name or description, open a paired merge request to the GitLab application ( gitlab-org/gitlab ) updating FoundationalChatAgentsDefinitions.rb .
This is required because the GitLab application pins each agent to a flow version range with the flow_version attribute: a major version is a breaking change, so GitLab Duo Workflow Service does not serve it to instances whose pin excludes it. Updating the pin deliberately releases the new major version while older GitLab Self-Managed and GitLab Dedicated versions keep resolving a compatible flow config. See Versioning .
Update the documentation. If the agent’s behavior or capabilities changed, update both the list of foundational agents and the agent’s dedicated page in the same directory, which describes what the agent does in depth. Add a history entry to the agent’s page for the release where the change ships. Communicate the change. Announce the change and the affected capabilities in your group’s Slack channel, and add a release post item for user-facing changes.
Secret-safety requirements for agent prompts If your foundational agent’s scope includes any of the following, you must include secret-safety guidance in its system prompt: Generating or modifying files (for example, .gitlab-ci.yml , configuration files, scripts). CI/CD pipeline configuration or conversion. Handling credentials, API keys, tokens, or connection strings. Required prompt guidance Add the following instructions verbatim to the agent’s system prompt: Never write literal secret values (API keys, tokens, passwords, connection strings, or any credentials) into files or repository content.
Always substitute secrets with CI/CD variable references (for example, $API_KEY, $DB_PASSWORD, $DEPLOY_TOKEN). If a user provides a secret value directly, do not echo it into any file — instead, recommend storing it in Settings > CI/CD > Variables and reference it as a variable. When converting pipelines from other CI systems (for example, Jenkins, GitHub Actions, CircleCI) that contain hardcoded secrets, repl
The rest of this page is on the live site.