Skip to content

Commit 77fa7bd

Browse files
jenna-winklertomkis
jenna-winkler
and
tomkis
authored
docs: Create gui-components.mdx (#885)
* docs: Create gui-components.mdx Signed-off-by: Jenna Winkler <[email protected]> * docs: Update docs.json Signed-off-by: Jenna Winkler <[email protected]> * docs: Update docs.json Signed-off-by: Jenna Winkler <[email protected]> * docs: Update gui-components.mdx Signed-off-by: Jenna Winkler <[email protected]> * docs: Update gui-components.mdx Signed-off-by: Jenna Winkler <[email protected]> * Apply suggestions from code review Co-authored-by: Tomáš Weiss <[email protected]> Signed-off-by: Jenna Winkler <[email protected]> * docs: Update gui-components.mdx Signed-off-by: Jenna Winkler <[email protected]> --------- Signed-off-by: Jenna Winkler <[email protected]> Co-authored-by: Tomáš Weiss <[email protected]>
1 parent 99b65c4 commit 77fa7bd

File tree

2 files changed

+251
-1
lines changed

2 files changed

+251
-1
lines changed

‎docs/concepts/gui-components.mdx‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
---
2+
title: "GUI Components"
3+
description: "Customize how your agents appear and behave in the BeeAI platform interface"
4+
---
5+
6+
GUI components in the BeeAI platform define how your agents appear and behave in the graphical user interface. This customization happens through two types of metadata:
7+
1. **Standard ACP metadata** - recognized by any ACP-compliant system
8+
2. **BeeAI platform extensions** - specific to the BeeAI platform GUI
9+
10+
<Note>
11+
To fully customize your agent's appearance and behavior in the interface, you'll be using metadata defined by the Agent Communication Protocol (ACP). For details on how metadata annotations work, see the [ACP metadata documentation](https://agentcommunicationprotocol.dev/core-concepts/agent-manifest#schema-metadata).
12+
</Note>
13+
14+
## BeeAI Platform Extensions
15+
16+
BeeAI Platform extends the standard ACP metadata with platform-specific GUI customizations through the `PlatformUIAnnotation`. This annotation is placed in the `beeai_ui` field within the agent's metadata annotations.
17+
18+
```python
19+
from acp_sdk import Annotations, Metadata
20+
from acp_sdk.models.platform import PlatformUIAnnotation, PlatformUIType, AgentToolInfo
21+
22+
@server.agent(
23+
metadata=Metadata(
24+
annotations=Annotations(
25+
beeai_ui=PlatformUIAnnotation(
26+
ui_type=PlatformUIType.CHAT,
27+
user_greeting="Hello! I'm your AI assistant. How can I help you today?",
28+
display_name="My Custom Agent",
29+
tools=[
30+
AgentToolInfo(name="Weather", description="Get current weather information"),
31+
AgentToolInfo(name="Wikipedia", description="Search Wikipedia articles"),
32+
]
33+
)
34+
)
35+
)
36+
)
37+
```
38+
39+
## UI Types
40+
41+
The platform supports two primary UI types, each optimized for different interaction patterns:
42+
43+
### Chat UI
44+
45+
The chat interface (`PlatformUIType.CHAT`) provides a conversational experience.
46+
47+
<Info>
48+
Chat UI is best suited for conversational agents, customer support bots, and multi-turn dialogues.
49+
</Info>
50+
51+
### Hands-off UI
52+
53+
The hands-off interface (`PlatformUIType.HANDSOFF`) is designed for autonomous agents that work independently:
54+
55+
- **Task Execution**: Focus on agent actions rather than conversation
56+
- **Result Display**: Clear presentation of final outcomes
57+
58+
<Info>
59+
Hands-off UI is ideal for automated workflows where there is a clear output. For example, consider a researcher agent: it receives a clearly defined input which is the research topic and then it produces a well-structured output which is the resulting research.
60+
</Info>
61+
62+
## Platform-Specific Properties
63+
64+
### Display Name
65+
66+
Override the default agent name shown in the UI:
67+
68+
```python
69+
PlatformUIAnnotation(
70+
display_name="Customer Support Assistant"
71+
)
72+
```
73+
74+
### User Greeting
75+
76+
Set a welcoming message displayed when users first interact with your agent:
77+
78+
```python
79+
PlatformUIAnnotation(
80+
user_greeting="Welcome! I'm here to help you with your questions."
81+
)
82+
```
83+
84+
### Tool Information
85+
86+
Define the tools your agent can use, providing clear descriptions for users:
87+
88+
```python
89+
PlatformUIAnnotation(
90+
tools=[
91+
AgentToolInfo(
92+
name="Search Engine",
93+
description="Search the web for current information"
94+
),
95+
AgentToolInfo(
96+
name="Calculator",
97+
description="Perform mathematical calculations"
98+
),
99+
AgentToolInfo(
100+
name="File Processor",
101+
description="Read and analyze uploaded files"
102+
)
103+
]
104+
)
105+
```
106+
107+
## Standard ACP Metadata
108+
109+
These properties are part of the standard Agent Communication Protocol and will be recognized by any ACP-compliant system, not just BeeAI. They provide essential information about your agent that appears in the GUI.
110+
111+
### Tags
112+
113+
Custom tags help categorize and filter agents:
114+
115+
```python
116+
metadata=Metadata(
117+
tags=["Research", "Data Analysis", "Educational"]
118+
)
119+
```
120+
121+
### Framework Badge
122+
123+
Shows which framework the agent is built with, with special styling for BeeAI agents:
124+
125+
```python
126+
metadata=Metadata(
127+
framework="BeeAI" # Displays with special BeeAI badge
128+
)
129+
```
130+
131+
### License
132+
133+
Shows the agent's license information:
134+
135+
```python
136+
metadata=Metadata(
137+
license="Apache 2.0"
138+
)
139+
```
140+
141+
### Programming Language
142+
143+
Displays the primary programming language:
144+
145+
```python
146+
metadata=Metadata(
147+
programming_language="Python"
148+
)
149+
```
150+
151+
### Author Information
152+
153+
Shows agent author details:
154+
155+
```python
156+
metadata=Metadata(
157+
author={
158+
"name": "John Smith",
159+
"email": "[email protected]",
160+
"url": "https://example.com"
161+
}
162+
)
163+
```
164+
165+
## Advanced Features
166+
167+
### Dynamic Content Rendering
168+
169+
The platform automatically renders various content types within your agent responses:
170+
171+
#### Markdown Support
172+
- Headers, lists, and text formatting
173+
- Code blocks with syntax highlighting
174+
- Tables and structured data
175+
- Links and references
176+
= Images
177+
178+
### Trajectory Visualization
179+
180+
The platform provides built-in trajectory visualization to show the step-by-step process of agent execution:
181+
182+
```python
183+
from acp_sdk import MessagePart
184+
from acp_sdk.models.models import TrajectoryMetadata
185+
186+
# Show trajectory steps during agent execution
187+
yield MessagePart(metadata=TrajectoryMetadata(
188+
message="Processing user request with Trajectory Agent...",
189+
tool_name="Think" # Optional: specify which tool is being used
190+
))
191+
192+
yield MessagePart(metadata=TrajectoryMetadata(
193+
message="Step 1: Analyzing the problem",
194+
tool_name="Think"
195+
))
196+
197+
yield MessagePart(metadata=TrajectoryMetadata(
198+
message="Step 2: Searching for relevant information",
199+
tool_name="Wikipedia"
200+
))
201+
```
202+
203+
<Info>
204+
Trajectory metadata creates a visual timeline in the UI, helping users understand the agent's reasoning process and tool usage.
205+
</Info>
206+
207+
### File Upload Support
208+
209+
The platform automatically handles file uploads and makes them available to agents through `content_url`:
210+
211+
```python
212+
import httpx
213+
214+
async def file_processing_agent(input: list[Message], context: Context):
215+
# Check for uploaded files
216+
for part in input[-1].parts:
217+
if part.content_url:
218+
yield MessagePart(content="📁 Processing uploaded file...")
219+
220+
try:
221+
# Download file content
222+
async with httpx.AsyncClient() as client:
223+
response = await client.get(str(part.content_url))
224+
content = response.content.decode('utf-8')
225+
226+
# Process the file content
227+
# ... your processing logic here
228+
229+
except Exception as e:
230+
yield MessagePart(content=f"❌ Error processing file: {str(e)}")
231+
```
232+
233+
### Citation and Sources
234+
235+
For agents that reference external sources, the platform provides built-in citation components:
236+
237+
```python
238+
# Citations are automatically rendered when included in message metadata
239+
MessagePart(
240+
content="According to recent studies...",
241+
metadata=CitationMetadata(
242+
url="https://example.com/study",
243+
title="Recent Research Study",
244+
description="Comprehensive analysis of the topic",
245+
start_index=0,
246+
end_index=25
247+
)
248+
)
249+
```

‎docs/docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,8 @@
3535
{
3636
"group": "Core Concepts",
3737
"pages": ["concepts/architecture",
38-
"concepts/acp-protocol"]
38+
"concepts/acp-protocol",
39+
"concepts/gui-components"]
3940
},
4041
{
4142
"group": "Deployment",

0 commit comments

Comments
 (0)