ContextQMD
Back to Gitlabhq

Development of GitLab Duo Agent Platform

doc/development/duo_agent_platform/_index.md

19.2.06.6 KB
Original Source

{{< history >}}

  • Name changed from Workflow to Agent Platform in GitLab 18.2.

{{< /history >}}

How to set up the local development environment to run GitLab Duo Agent Platform.

Prerequisites

  • GitLab Ultimate license
  • Vertex access: You need access to the ai-enablement-dev-69497ba7 project in GCP because GDK by default uses Anthropic hosted on Vertex. Access to this project should be available to all engineers at GitLab.
    • If you do not have Vertex access for any reason, you should unset DUO_WORKFLOW__VERTEX_PROJECT_ID in the GitLab Duo Agent Platform Service and set ANTHROPIC_API_KEY to a regular Anthropic API key
  • Various settings and feature flags, which are enabled for you by the GDK setup script

Set up local development for Agent Platform

Agent Platform consists of four separate services:

  1. GitLab instance
  2. GitLab Duo Agent Platform Service, which is part of GitLab AI Gateway
  3. GitLab Duo CLI (Node/TypeScript executor from gitlab-lsp)
  4. GitLab Duo Agent Platform Webview

Development Setup for Backend Components

You should set up GitLab Duo Agent Platform with the GitLab Development Kit (GDK) to run local versions of GitLab and the GitLab Duo Agent Platform Service.

This setup can be used as-is with the publicly available version of the VS Code Extension or GitLab Duo CLI.

Testing Agentic GitLab Duo Chat in Web UI

To test Agentic GitLab Duo Chat in the Web UI of your local GitLab instance, follow these additional setup steps:

  1. Enable NGINX for your GDK. A loopback interface and HTTPS are not required, only the basic NGINX configuration.
  2. Access your GDK at http://gdk.test:8080. Your GDK is still available at port 3000 but accessing it at port 8080 accesses the application through NGINX, which is required for Agentic GitLab Duo Chat to work on the web. If you access the application at port 3000 and try Agentic GitLab Duo Chat, you see an error message: Error: Unable to connect to workflow service. Please try again..

Development Setup for Frontend Components

There is no need to set up the backend components of the Agent Platform to test changes for the Agent Platform UI in the IDE.

A local build of the UI is required if you are making GitLab Duo Agent Platform UI changes that you need to view locally. A local build is also required if you want to use a version of the UI that has not been released yet.

Refer to the GitLab Duo Agent Platform README file in the Language Server project to get started with local development of GitLab Duo Agent Platform UI in the IDE.

Development settings

Each of these settings can be turned on in your user settings in VS Code.

Change view type

Enable the GitLab Duo Agent Platform as a sidepanel instead of fullview. This is going to be the default for public beta.

"gitlab.featureFlags.duoWorkflowPanel": true,

Tool approval

Allow users to get access to tools that require approval such as running terminal commands.

"gitlab.duo.workflow.toolApproval": true

Trace API requests to a workflow session

Requests that originate from a GitLab Duo workflow carry the X-Gitlab-Duo-Workflow-Id header. The Rails middleware Gitlab::Middleware::DuoWorkflowId reads the header into Gitlab::ApplicationContext. The workflow ID is then available in application code and in structured request logs for the duration of the request.

Two paths set the header automatically:

  • Tool API calls. When an agent calls a tool that hits the GitLab API, Workhorse proxies the call and attaches the header.
  • glab calls from a runner running an agent. The runner exports DUO_WORKFLOW_WORKFLOW_ID, and the glab CLI sets the header on every API call it makes.

Read the value from application code:

ruby
Gitlab::ApplicationContext.current_context_attribute(:duo_workflow_id)

In structured logs, Grape exposes the value as meta.duo_workflow_id (in api_json.log and graphql_json.log) and Lograge exposes it at the top level as duo_workflow_id (in development_json.log and production_json.log).

Filter logs by workflow ID

Filter API and GraphQL logs by meta.duo_workflow_id, or Lograge logs by duo_workflow_id, to see every request a session produced. Use this approach when debugging a misbehaving session. For example:

shell
jq 'select(."meta.duo_workflow_id" == "<workflow_id>")' log/api_json.log

Read the workflow ID inside a service that creates or modifies a resource, and persist it alongside the resource. The resource can then be traced back to the session that produced it.

ruby
class CreateService
  def execute
    issue = Issue.create!(params)

    if workflow_id = Gitlab::ApplicationContext.current_context_attribute(:duo_workflow_id)
      # Persist workflow_id alongside the issue.
    end

    issue
  end
end

The value is request-scoped and not propagated to Sidekiq jobs. :duo_workflow_id belongs to Gitlab::ApplicationContext::WEB_ONLY_KEYS, so background jobs do not inherit it. To use the value in a job, pass it as an explicit argument.

Evaluate flow

Running evals

To evaluate your local setup, please refer to GitLab Duo Agent Platform Tests repo.

Comparing results

Once you finish a evaluation and have a experiment ID from LangSmith, compare results using this notebook from the GitLab Duo Agent Platform Notebooks repo.