optimistic-gold•2mo ago

Agent Step Still not Showing CardV2

My Agent step calls a function that return cardV2 but the agent is unable to display the card trace elements.

1 Reply

Here’s what usually causes a CardV2 not to appear when it’s generated from a Function inside an Agent step, and how to fix it.
1. Make sure the Function returns a trace array
The Dialog Manager only renders elements that are delivered through the top-level trace property. Returning the raw object (or a property called traces) will be ignored.

export default async function main(args) {
  return {
    trace: [                          // ✅ this MUST be an array called "trace"
      {
        type: 'cardV2',               // ✅ case-sensitive
        payload: {
          imageUrl: 'https://picsum.photos/300',
          title:    'My sample card',
          description: { text: 'Hello from the Agent function!' },
          buttons: [
            {
              name: 'Open docs',
              payload: {
                actions: [ { type: 'open_url', url: 'https://docs.voiceflow.com' } ]
              }
            }
          ]
        }
      }
    ],
    next: { path: 'next' }            // or omit if the Agent step should end here
  };
}

export default async function main(args) {
  return {
    trace: [                          // ✅ this MUST be an array called "trace"
      {
        type: 'cardV2',               // ✅ case-sensitive
        payload: {
          imageUrl: 'https://picsum.photos/300',
          title:    'My sample card',
          description: { text: 'Hello from the Agent function!' },
          buttons: [
            {
              name: 'Open docs',
              payload: {
                actions: [ { type: 'open_url', url: 'https://docs.voiceflow.com' } ]
              }
            }
          ]
        }
      }
    ],
    next: { path: 'next' }            // or omit if the Agent step should end here
  };
}

2. Use the exact CardV2 payload shape
At minimum you need one of: title, description.text, or imageUrl. Buttons are optional but, if present, must follow the structure in the example above. 3. Keep the type string exact
The trace type must be cardV2 (all lower-case “v2”). 4. Publish & test in the chat widget
After updating the function, re-publish the project and open the Test Tool / Web Chat. The card should now render immediately after the Agent step runs. If the object you return matches the snippet above and you still don’t see anything, open the DevTools network tab while testing; the /interact response should contain a type:"cardV2" trace. If it’s there, the widget will render it—if it isn’t, the function isn’t returning it in the right place. Reference: Trace specification → CardV2 https://docs.voiceflow.com/reference/trace-types

Agent Step Still not Showing CardV2

Did you find this page helpful?