How to access and parse forwardedProps in MAF request context

[Aimee-min-code]

Description:
Hi team,

I’m currently working with MAF and trying to understand how to properly access and parse the forwardedProps field from the incoming request.

In my use case, the request payload looks like this:

{
  "threadId": "894ee3aa-bc48-452f-a0ad-21175ab1a1c1",
  "runId": "aa9af314-5e1e-40c2-b0c6-d3f0aa5d128d",
  "tools": [],
  "context": [],
  "forwardedProps": {
    "data": {
      "document_ids": [
        "general_information_sample"
      ],
      "extraction_spec": {
        "name": "contact_form_v1",
        "description": "Extract structured data for a simple contact form including name, email, company, and description.",
        "json_schema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": ["string", "null"],
              "description": "Full name of the person."
            },
            "email": {
              "type": ["string", "null"],
              "description": "Email address of the person."
            },
            "company": {
              "type": ["string", "null"],
              "description": "Company name provided by the person."
            },
            "description": {
              "type": ["string", "null"],
              "description": "Free text description or message provided in the form."
            }
          },
          "required": ["name", "email", "company", "description"]
        }
      },
      "prefilled_data": {
        "name": "copilotKit"
      }
    },
    "source": "main"
  },
  "state": {},
  "messages": [
    {
      "id": "8a673d30-9729-4f96-ada5-83c59a3587d2",
      "role": "user",
      "content": "{\"type\":\"form\",\"data\":{...}}"
    }
  ]
}

Questions:

1.Where exactly is forwardedProps exposed within the MAF execution lifecycle (e.g., middleware, workflow, tool context)?
2.What is the recommended way to access it?
Should it be read from context, session, or another abstraction?
3.Is there a built-in or standard way to parse the nested data field (e.g., into a typed object)?
4.Are there any best practices for handling forwardedProps when passing data between frontend (CopilotKit) and backend (MAF)?

Additional Context:

The request is sent from CopilotKit with structured form data.
I want to reliably extract fields like document_ids, extraction_spec, and prefilled_data inside my backend logic (e.g., in tools or workflow nodes).

Any guidance or examples would be greatly appreciated.

Thanks! 🙏

[moonbox3]

Hi @Aimee-min-code,

How forwardedProps works in MAF today:

forwardedProps is parsed by the AG-UI layer (AGUIRequest model) but is currently only consumed for resume/interrupt flows, specifically forwardedProps.command.resume. Custom data like your document_ids, extraction_spec, and prefilled_data won't automatically surface in your agent, tools, or workflow context.

Recommended approaches for your use case:

1. Use state instead of forwardedProps: this is the best fit. When you configure a state_schema on your endpoint, MAF automatically injects the current state into the agent's conversation context. Your agent can then reason over document_ids, extraction_spec, etc. directly. On the CopilotKit side, pass your data via state instead of forwardedProps.
2. Use context: the AG-UI context field (populated via CopilotKit's useCopilotReadable) is designed for passing structured context to the agent.
3. Encode in messages: you're already partially doing this. The agent receives your user message content and can parse the structured JSON from it.

For your structured extraction scenario specifically, state gives you the most framework-level support (schema defaults, state snapshots, predictive state updates).

[Aimee-min-code]

Hi, thanks a lot for your detailed explanation — it really helped clarify how forwardedProps is handled in MAF. I appreciate it!

I have a follow-up question regarding my use case:

My agent interacts with a main page, and there are two ways to trigger the agent:

Manually from the main page via copilotKit.runAgent()
Automatically through the chat input box

I initially tried using forwardedProps to include a custom flag (e.g., indicating the request source), so I could distinguish whether a request originated from the main page or from the chat input. The goal is to control how messages are stored in history:

Messages triggered from the main page should NOT be stored in chat history
Messages sent from the chat input should be stored

However, based on your explanation, it seems that relying on forwardedProps may not be a reliable approach for this purpose.

So my question is:

What would be a better or recommended way to distinguish the source of a request (main page vs. chat input), and conditionally control whether the message should be persisted in the conversation history?

Any best practices or suggested patterns for handling this kind of scenario would be greatly appreciated.

Thanks again! 🙏

[moonbox3]

This is outside MAF's scope. The AG-UI protocol is a transport layer between your frontend and agent backend. Chat history persistence is a frontend/client concern, not something the agent framework controls.

By the time a request reaches your MAF endpoint, it's just messages + state + tools. MAF processes and responds - it has no opinion on whether the frontend persists that exchange in chat history.

I'd recommend raising this in the https://github.com/CopilotKit/CopilotKit repo as they own the runAgent() API and the chat history management. Specifically, you'd want to ask about:

• How runAgent() interacts with chat history persistence
• Whether there's a way to conditionally exclude messages based on invocation source

If you do need the backend to behave differently based on source (for example, different system prompts or tools), passing a flag via state as described above would work, but the persist/don't-persist decision itself belongs on the CopilotKit side.

[Aimee-min-code]

thanks for the suggestion — I understand that adding a custom flag inside forwardedProps is a valid approach on the frontend side.

I’m now trying to make this work end-to-end, but I’m running into an issue on the backend.

My goal is to read this custom flag from forwardedProps so that I can decide whether or not to persist a message into the database (for example, skipping persistence for requests triggered via runAgent()).

However, the problem I’m facing is:

I’m not sure at which stage in the backend (within the MAF framework / AG-UI protocol flow) I can reliably access and parse the values inside forwardedProps.

So far, it seems that forwardedProps is not directly exposed in AgentContext, session, or tool inputs, which makes it unclear how to access and propagate this information during execution.

Questions:

At what point in the backend request lifecycle should I expect to access forwardedProps?
Is there a recommended way to make forwardedProps available inside MAF (e.g., injecting it into state, metadata, or another structure)?
Are there any best practices or examples for passing frontend metadata (such as invocation source) through AG-UI into backend logic?

Any guidance would be greatly appreciated.
Thanks again! 🙏

[moonbox3]

As I mentioned in my previous reply, MAF does not expose forwardedProps to your agent, tools, session, or any backend execution context. The only thing MAF reads from forwardedProps is the resume key for interrupt/resume flows. Everything else in forwardedProps is ignored.

This means there is no stage in the MAF request lifecycle where you can "access and parse" arbitrary forwardedProps values. forwardedProps is a CopilotKit concept for client-to-server metadata, and MAF simply doesn't consume it beyond resume handling.

If you need request-level metadata to drive backend logic (like your DB persistence flag), you'll need to write your own FastAPI endpoint instead of using add_agent_framework_fastapi_endpoint(). The AGUIRequest Pydantic model parses forwardedProps for you - you just need to read it yourself before handing input_data to the protocol runner:

@app.post("/api/agent")                                                         
async def my_endpoint(request_body: AGUIRequest):
    # forwardedProps is parsed here, read whatever you need                                                                                                                                                                                                                            
    skip_persist = (request_body.forwarded_props or {}).get("skip_persist", False)
                                                                                                                                                                                                                                                                                        
    # Then run the agent as normal                                              
    input_data = request_body.model_dump(exclude_none=True)
    async for event in protocol_runner.run(input_data):                                                                                                                                                                                                                                 
        ...

The other option is to pass the information via state as I mentioned, as state is propagated into session.metadata["current_state"] and injected into the agent's conversation context, so it would be accessible within your agent and tool logic.

I'll file an issue to add support for forwardedProps so you don't need to do this workaround. But, as of today, you'll either need your own FastAPI wrapper, or use state.

[moonbox3]

Tracking in #5239.