Agents SDK: API examples in skill references caused incorrect usage

[nev-offload]

Problem

When building the AI Chat page for the showcase app, the subagent made 3 API mistakes despite having the skill references available:

Bug 1: Wrong parameter name for createConversation

// ❌ What was written
base44.agents.createConversation({ agentName: 'showcase_assistant' })

// ✅ Correct
base44.agents.createConversation({ agent_name: 'showcase_assistant' })

Bug 2: Wrong subscribeToConversation signature

// ❌ What was written
base44.agents.subscribeToConversation({
  conversationId: conversation.id,
  onMessage: (message) => { ... }
})

// ✅ Correct
base44.agents.subscribeToConversation(conversation.id, (updatedConversation) => { ... })

Bug 3: Wrong addMessage signature

// ❌ What was written
base44.agents.addMessage({ conversationId, message: input })

// ✅ Correct
base44.agents.addMessage(conversation, { role: 'user', content: input })

Analysis

Looking at the base44-agents.md reference in the skill, the correct signatures ARE documented:

• createConversation(params) with example showing agent_name
• subscribeToConversation(id, onUpdate?) with positional params
• addMessage(conversation, message) with conversation object + message object

So the docs are correct, but the agent still hallucinated different patterns. This suggests:

1. The WRONG vs CORRECT table pattern used for other modules (auth, entities, integrations, functions) is missing for agents. The agents module doesn't have an explicit "don't hallucinate" table like the others do in SKILL.md.

2. Adding a WRONG vs CORRECT table for agents in the main SKILL.md (like exists for auth, functions, integrations, entities) would likely prevent these mistakes.

Suggested Fix

Add to the SKILL.md ⚠️ CRITICAL: Do Not Hallucinate APIs section:

### Agents - WRONG vs CORRECT

| ❌ WRONG (hallucinated) | ✅ CORRECT |
|------------------------|-----------|
| \`createConversation({ agentName })\` | \`createConversation({ agent_name })\` |
| \`subscribeToConversation({ conversationId, onMessage })\` | \`subscribeToConversation(id, onUpdateCallback)\` |
| \`addMessage({ conversationId, message })\` | \`addMessage(conversation, { role, content })\` |
| \`getConversation({ id })\` | \`getConversation(id)\` |

Origin

All 3 bugs found during QA of the Base44 showcase app's AI Chat page.

[nev-offload]

Update: Additional findings from QA

New issue: Tool call messages rendered as raw JSON

When the agent uses tools (e.g., reading entities via read_ShowcaseItem), the messages array includes intermediate messages where:

• content is empty string ("")
• tool_calls array contains the tool call data

The current skill docs describe the message structure in base44-agents.md but don't provide guidance on how to render tool_call messages in a chat UI. This led to the raw JSON being displayed as a regular chat bubble (see screenshot in original issue).

Suggested additions to the skill:

1. Add a 'Common Patterns > Chat Message Rendering' section that explains:

   • Messages with tool_calls and empty content are intermediate — hide them or render as a subtle indicator
   • Only display messages where content is truthy as regular chat bubbles
   • Example filter: messages.filter(m => m.content || m.role === 'user')

2. Add to WRONG vs CORRECT table:

   ❌ WRONG	✅ CORRECT
   Render all messages including tool_calls as chat bubbles	Filter out messages with empty content + tool_calls, or render them as collapsible tool indicators

Also: Missing guidance on conversation listing

The getConversations() and listConversations() methods are documented but there's no guidance in the skill about building a conversation history UI — a very common pattern. Should add a 'Conversation List Pattern' to common patterns.

Functions invoke() response format

From the Functions QA: base44.functions.invoke() returns an axios-like response with .data property. The frontend was using response directly instead of response.data. This isn't clearly documented in the skill — the functions.md says 'Returns: Whatever the function returns' but doesn't mention the wrapper object.

[nev-offload]

Update: listConversations filter format is wrong in docs

Bug found

The base44-agents.md reference shows:

const recent = await base44.agents.listConversations({
  q: { agent_name: 'support-agent' },  // ❌ WRONG
  sort: '-created_date',
  limit: 10,
});

But the actual API expects filters at the top level, NOT wrapped in q::

const recent = await base44.agents.listConversations({
  agent_name: 'showcase_assistant',  // ✅ CORRECT
  sort: '-created_date',
  limit: 20,
});

With the q: wrapper: returns empty array (0 results).
Without: returns all matching conversations (3 results).

Impact

This is a documentation bug in the skill itself — any ClawdBot following the reference will produce broken conversation listing code.

Fix needed

Update references/base44-agents.md — remove the q: wrapper from listConversations examples, or add to the WRONG vs CORRECT table.