feat(sdk): add flags support and x-agenta-flags OpenAPI extension for chat detection

[mmabrouk]

Summary

This PR implements Phase 1 and Phase 1b of the Chat Interface RFC, enabling custom workflows to explicitly declare themselves as chat applications via a flags parameter.

Changes

Legacy System (serving.py):

• Add flags: Optional[Dict[str, Any]] parameter to @ag.route, @ag.entrypoint, and create_app()'s isolated_route
• Emit x-agenta-flags on /run and /test OpenAPI operations
• Update builtin chat service to set flags={"is_chat": True}

New Workflow System (routing.py):

• Add flags: Optional[dict] parameter to @ag.route
• Propagate flags to auto_workflow() so they flow to /inspect response

Models:

• Add is_chat: bool = False to WorkflowFlags in SDK (sdk/agenta/sdk/models/workflows.py)
• Add is_chat: bool = False to WorkflowFlags in API (api/oss/src/core/workflows/dtos.py)

Design Docs:

• Add docs/design/chat-interface-rfc/ with research, plan, and status

Usage

# Legacy system (user-facing custom workflows)
@ag.route("/", config_schema=Config, flags={"is_chat": True})
async def chat_handler(messages: List[ag.Message]) -> ag.Message:
    ...

# New workflow system
@ag.route("/", flags={"is_chat": True})
def my_chat_workflow(messages):
    ...

OpenAPI Output

paths:
  /run:
    post:
      x-agenta-flags:
        is_chat: true

Testing

• Manually tested deployment at http://144.76.237.122:8180
• Verified x-agenta-flags.is_chat: true appears in /services/chat/openapi.json

Next Steps (Phase 2)

Frontend changes to read x-agenta-flags.is_chat for chat detection (with heuristics fallback).

---

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Feb 3, 2026 7:01pm

[devin-ai-integration]

Devin Review found 1 potential issue.

View issue and 5 additional flags in Devin Review.

[devin-ai-integration]

🟡 Flags parameter ignored when auto_workflow receives an existing Workflow object

When auto_workflow is called with an object that is already a workflow, the flags parameter is silently ignored.

Click to expand

Root Cause

In sdk/agenta/sdk/decorators/running.py:460-468, the auto_workflow function has early return paths that don't use the **kwargs (which includes flags):

def auto_workflow(obj: Any, **kwargs) -> Workflow:
    if is_workflow(obj):
        return obj  # kwargs ignored!
    if isinstance(obj, workflow):
        return obj()  # kwargs ignored!
    if isinstance(getattr(obj, "workflow", None), workflow):
        return obj  # kwargs ignored!

    return workflow(**kwargs)(obj)  # Only this path uses kwargs

How It Gets Triggered

When using the new @ag.route decorator from routing.py with an already-decorated workflow:

@ag.route("/", flags={"is_chat": True})
@ag.workflow()  # Creates a workflow first
def my_handler():
    ...

The flags={"is_chat": True} from @ag.route will be silently ignored because my_handler is already a workflow when auto_workflow(foo, flags=self.flags) is called at routing.py:226.

Actual vs Expected

• Actual: Flags are ignored, /inspect response won't include is_chat: true
• Expected: Flags from @ag.route should be merged with or override the workflow's existing flags

Impact

Users combining @ag.route(flags=...) with @ag.workflow() decorators won't get their flags applied, leading to incorrect chat detection in the frontend.

Recommendation: Modify auto_workflow to merge flags when the object is already a workflow, or document that @ag.route(flags=...) should not be combined with @ag.workflow(). Alternatively, the route class could check if foo is already a workflow and update its flags directly before calling auto_workflow.

---

Was this helpful? React with 👍 or 👎 to provide feedback.