feat(headless): integration of ag-ui client to generate head and follow up answers

[mmitiche]

SFINT-6610

Summary

This PR introduce the @ag-ui/client library in Headless which is now used to interact with the KGAS to support generating head answers and follow up answer.

Answer generation is now structured around explicit AG-UI agents, with clear separation between:

• Transport (HTTP + endpoint configuration)
• Streaming event handling
• Lifecycle management
• Redux state projection

The goal is to keep the integration simple, explicit, and maintainable while establishing a clean architectural foundation for future enhancements.

---

Structure

A new agents folder has been introduced under: src/api/answer-generation/

It contains two submodules:

• answer-agent
• follow-up-agent

Each submodule encapsulates everything required for its respective agent.

---

Head Answer Flow

The answer-agent module is organized into three clear responsibilities:

1. Agent

• Defines the AnswerAgent
• Configures the /answer endpoint
• Handles streaming transport details

2. Strategy

• Translates AG-UI streaming events into Redux state updates
• Isolates event handling logic from transport and lifecycle

3. Runner

• Manages the lifecycle of the agent (run / abort)
• Ensures only one head answer generation runs at a time
• Delegates transport and streaming to the agent and strategy

Integration

The AnswerRunner is used inside the generated answer listener middleware:

1. A search is executed.
2. The listener validates feature flags and query state.
3. The runner executes the AG-UI agent.
4. The strategy projects streaming events into Redux.

---

Follow-Up Flow

The follow-up-agent module contains:

1. FollowUpAgent

• Configures the /follow-up endpoint
• Handles streaming transport for follow-up answers

2. FollowUpStrategy

• Handles streaming events
• Updates follow-up state in Redux

Integration

The follow-up agent is used by the GeneratedAnswerWithFollowUps controller.

When askFollowUp is called:

1. A follow-up answer entry is created in state.
2. The FollowUpAgent runs against the /follow-up endpoint.
3. The strategy streams updates into Redux.

[Copilot]

Pull request overview

This PR integrates the @ag-ui/client library (version 0.0.45) to handle answer generation for both head answers and follow-up answers using the KGAS (Knowledge Graph Answer Service). The implementation establishes a clean architectural pattern with explicit AG-UI agents, separating transport, streaming event handling, and lifecycle management.

Changes:

• Introduces @ag-ui/client dependency and creates a new agents folder structure for answer generation
• Refactors the generate answer listener middleware to use an AnswerRunner instead of dispatching Redux actions directly
• Implements FollowUpAgent and associated strategy for handling follow-up answer generation via the /follow-up endpoint

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Adds @ag-ui/client@0.0.45 and its dependencies
packages/headless/package.json	Declares @ag-ui/client dependency
packages/headless/src/features/configuration/configuration-selectors.ts	Adds selectors for accessToken, organizationId, and environment
packages/headless/src/features/configuration/configuration-selectors.test.ts	Tests for new configuration selectors
packages/headless/src/app/listener-middleware/generate-answer-listener-middleware.ts	Refactors to use AnswerRunner instead of dispatching generateHeadAnswer action
packages/headless/src/app/listener-middleware/generate-answer-listener-middleware.test.ts	Updates tests for refactored listener middleware
packages/headless/src/app/engine.ts	Updates middleware creation to pass NavigatorContext provider to listener
packages/headless/src/api/knowledge/answer-generation/agents/endpoint-url-builder.ts	Creates URL builder for answer generation endpoints
packages/headless/src/api/knowledge/answer-generation/agents/endpoint-url-builder.test.ts	Tests for endpoint URL builder
packages/headless/src/api/knowledge/answer-generation/agents/answer-agent/answer-agent.ts	Implements custom HttpAgent for head answer requests
packages/headless/src/api/knowledge/answer-generation/agents/answer-agent/head-answer-strategy.ts	Implements AgentSubscriber for handling head answer streaming events
packages/headless/src/api/knowledge/answer-generation/agents/answer-agent/head-answer-strategy.test.ts	Tests for head answer strategy
packages/headless/src/api/knowledge/answer-generation/agents/answer-agent/answer-agent-runner.ts	Implements lifecycle management for AnswerAgent
packages/headless/src/api/knowledge/answer-generation/agents/answer-agent/answer-agent-runner.test.ts	Tests for answer agent runner
packages/headless/src/api/knowledge/answer-generation/agents/follow-up-agent/follow-up-agent.ts	Implements custom HttpAgent for follow-up answer requests
packages/headless/src/api/knowledge/answer-generation/agents/follow-up-agent/follow-up-answer-strategy.ts	Implements AgentSubscriber for handling follow-up answer streaming events
packages/headless/src/api/knowledge/answer-generation/agents/follow-up-agent/follow-up-answer-strategy.test.ts	Tests for follow-up answer strategy
packages/headless/src/controllers/knowledge/generated-answer/headless-generated-answer-with-follow-ups.ts	Integrates FollowUpAgent for askFollowUp method
packages/headless/src/controllers/knowledge/generated-answer/headless-generated-answer-with-follow-ups.test.ts	Updates tests for follow-up integration

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

packages/headless/src/api/knowledge/answer-generation/agents/follow-up-agent/follow-up-answer-strategy.ts:17

• The runId variable is declared but not initialized. If any event handler other than onRunStartedEvent is called first (e.g., onTextMessageContentEvent, onCustomEvent, onRunErrorEvent, or onRunFinishedEvent), the runId will be undefined when dispatching actions. While the AG-UI client likely guarantees that onRunStartedEvent is always called first, this creates a potential runtime error. Consider initializing runId to a default value or adding defensive checks in the other handlers to ensure runId is defined before using it.

  let runId: string;

[github-actions]

🔗 Scratch Orgs ready to test this PR:

• ✅ LWS Enabled: Open Org
• ✅ LWS Disabled: Open Org

[SimonMilord]

very nice, flow makes sense

[erocheleau]

Little comment, but consider it approved after