Agent Icon Data Model#

Agent icons in Dify use a three-field model: icon_type, icon, and icon_url. The meaning of icon varies by icon_type, making type checks essential before use.

Core Fields#

Defined on App in web/types/app.ts:

AppIconType is defined as 1:

export type AppIconType = 'image' | 'emoji' | 'link'

Rendering via AppIcon#

The AppIcon component (web/app/components/base/app-icon/index.tsx) accepts imageUrl (not icon_url) as a separate prop. It renders 2:

• An <img> tag from imageUrl only when iconType === 'image' && imageUrl is truthy
• Otherwise, an emoji (defaulting to 🤖) or the innerIcon slot

The background color is suppressed for image icons 3.

Inconsistencies in Agent API Types#

The auto-generated contracts in packages/contracts/generated/api/console/agent/types.gen.ts reveal a split between agent response types:

Types that include icon_url (read-only computed field, server-resolved URL):

• AgentAppPartial — readonly icon_url: string | null (line 513)
• AgentAppDetailWithSite — readonly icon_url: string | null (line 44)
• AppDetailSiteResponse — readonly icon_url: string | null (line 585)

Types that do NOT include icon_url:

• AgentInviteOptionResponse — has icon, icon_background, icon_type, but no icon_url
• AgentComposerAgentResponse — same omission
• AgentLogSourceResponse — uses app_icon* field names, no URL field
• AgentReferencingWorkflowResponse — uses app_icon* field names, no URL

There are also two separate enum definitions for the icon type with identical values:

• IconType — 'emoji' | 'image' | 'link' (used in payload types like AgentAppCreatePayload)
• AgentIconType — 'emoji' | 'image' | 'link' (used in AgentInviteOptionResponse and ComposerSavePayload)

These are structurally identical but separate declarations, creating an inconsistency that could cause type errors when passing one where the other is expected.

Workaround in Agent Selector#

Because AgentInviteOptionResponse lacks icon_url, the agent selector passes agent.icon as both the icon and imageUrl props to AppIcon:

// agent-selector.tsx lines 225–232
<AppIcon
  size="small"
  iconType={agent.icon_type}
  icon={agent.icon ?? undefined}
  background={agent.icon_background}
  imageUrl={agent.icon ?? undefined} // ⚠ passes file ID, not a URL
/>

The same pattern is used in agent-roster-field.tsx. This means image-type agent icons in these components attempt to render a file ID as a direct image URL rather than the resolved icon_url, which can result in broken images.

The toAgentRosterNodeData mapping also propagates this gap — icon_url is never copied into AgentRosterNodeData because it doesn't exist on the source type.

Writable vs Readonly Variants#

The contracts file also generates parallel *Writable types (e.g., AgentAppDetailWithSiteWritable, AgentAppPartialWritable) that omit icon_url entirely. This is intentional — icon_url is a server-computed field and should never be submitted in write payloads.

Key Files#