Managing foundational agents

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 duo chat are available, including groups, and are supported on Duo Self-hosted.

Create a foundational agent

There are two ways of creating a foundational agent, using the AI Catalog or Duo Workflow Service. AI Catalog provides a user-friendly interface, and it is the preferred approach, but writing a definition on 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: Duo Planner has ID 356.
Agents created on the AI Catalog need to be bundled into 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 Duo Workflow Service adding the ID of the agent:
```
# 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,356" \
+ RUN poetry run fetch-foundational-agents "https://gitlab.com" "$GITLAB_TOKEN" "348,356,<your-id-here>" \
```
The command above can also be executed locally for testing purposes.
To make the agent be selectable, add it to the FoundationalChatAgentsDefinitions.rb. The reference field must be the name of the agent lowercased and underscored, version must be v1. For example, a definition for an agent named Test Agent would be:
```
{
  id: 3,
  reference: 'test_agent',
  version: 'v1',
  name: 'Test Agent',
  description: "An agent for testing"
}
```

Using 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.yml

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:

# frozen_string_literal: true

module Ai
  module FoundationalChatAgentsDefinitions
    extend ActiveSupport::Concern

    ITEMS = [
      {
        id: 1,
        reference: 'chat',
        version: '',
        name: 'GitLab Duo Agent',
        description: "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

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 Duo Workflow Service.
Add prompts to the Duo Workflow Service to enable testing the agent in your local GDK.

Use feature flags for releasing chat agents

Control the release of new foundational agents with feature flags:

# ee/app/graphql/resolvers/ai/foundational_chat_agents_resolver.rb

  def resolve(*, project_id: nil, namespace_id: nil)
    project = GitlabSchema.find_by_gid(project_id)

    filtered_agents = []
    filtered_agents << 'foundational_pirate_agent' if Feature.disabled?(:my_feature_flag, project)
    # filtered_agents << 'foundational_pirate_agent' if Feature.disabled?(:my_feature_flag, current_user)

    ::Ai::FoundationalChatAgent
 .select {|agent| filtered_agents.exclude?(agent.reference) }
      .sort_by(&:id)
  end

This also allows making a foundational agent available to a specific tier.

Scoping

Not every agent is useful in every area. For example, some agents operate in projects, while others are more useful or have more capabilities in groups. Scoping is not supported. See issue 577395.

Triggers

Triggers are not supported for foundational chat agents by default, but if they are defined on AI Catalog, users can still add it to their project at which point they can be used through triggers.

Versioning

Versioning of agents is not yet supported. Consider potential breaking changes to older GitLab versions before doing changes to an agent.