Document AI Catalog integration points with Duo Workflow service, websockets, and CI/CD pipelines

3. Runs a CI workload with the image/commands from the definition

4. Passes context through `AI_FLOW_*` environment variables

## Execution and Integration Points

### Execution Contexts

 Execution differs by item type. Agents are interactive, invoked by users through chat interfaces. Flows and External Agents are event-driven, triggered automatically when configured GitLab events occur. Some foundational flows can also be invoked directly from the GitLab Web UI.

| Item Type | Invoked From | Executes in |

| --------- | ------------- | ----------- |

| Agents | Web UI (Agentic Chat), IDE, Duo CLI | Duo Workflow Service |

| Flows | Flow Triggers, Web UI (foundational flows only) | Duo Workflow Service |

| External Agents | Flow Triggers | CI Pipeline (Docker workload) |

### Agent and flow integration with Duo Workflow Service

Duo Workflow Service is the execution engine for agents and flows. It is a Python-based service with a gRPC API, built on LangGraph.

**Integration paths from Rails:**

1. **Web UI (Agentic Chat)**: WebSocket connection [through Workhorse](../duo_workflow/_index.md#from-the-gitlab-web-ui-without-a-separate-executor), which proxies to Duo Workflow Service using gRPC. The `aiCatalogAgentFlowConfig` GraphQL query provides the flow configuration.

2. **IDE**: The [GitLab Language Server](https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp) includes a Duo Agent Platform client (a.k.a executor) that connects to Duo Workflow Service through Workhorse proxy and executes workflow actions locally.

3. **Flow Triggers**: `Ai::FlowTriggers::RunService` delegates to `Ai::Catalog::Flows::ExecuteService`, which uses `Ai::DuoWorkflows::StartWorkflowService` to orchestrate execution through CI pipeline.

For detailed architecture diagrams, see the [Duo Workflow Architecture documentation](../duo_workflow/_index.md#gitlabcom-architecture).

### External Agent Execution

External agents (third-party flows) do **not** use Duo Workflow Service. They execute directly as CI workloads:

1. `Ai::FlowTriggers::RunService` receives the trigger event

2. Flow definition (Docker image, commands) is read from `ItemVersion#definition`

3. `Ci::Workloads::RunWorkloadService` creates a CI job

4. Context is passed in `AI_FLOW_*` environment variables

## Agent identity

When flows and external agents execute on runners through [Flow Triggers](#flow-triggers), the permissions of an agent are granted through [composite identity](https://docs.gitlab.com/user/duo_agent_platform/composite_identity/).