Skip to content

Commit 420ce49

Browse files
jenna-winklerjenna-winkler
authored
docs: updates (#1403)
* docs: updates * Fix formatting of beeai logs command in documentation Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> * Fix typo in AgentDetail extension reference Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> * Update proxy commands to use i-am-bee package Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> * docs: removed outdated docs pages Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> * Remove 'Agent Catalog' link from docs.json Removed the 'Agent Catalog' link from the documentation. Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> * Update link to guide for adding agents in web interface Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> * Revise title and description for A2A agent documentation Updated the title and description for clarity. Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> * docs: updates * docs: update * Update titles and descriptions in documentation Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> --------- Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com>
1 parent c6153ee commit 420ce49

File tree

6 files changed

+165
-112
lines changed

6 files changed

+165
-112
lines changed

‎docs/concepts/observability.mdx‎

Lines changed: 64 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Observability
33
description: Monitor traces, logs, and metrics from your agents and platform
44
---
55

6-
BeeAI Platform includes built-in observability through [OpenTelemetry (OTLP)](https://opentelemetry.io/), with [Arize Phoenix](https://docs.arize.com/phoenix) available out-of-the-box for immediate use. Additional backends like Langfuse can be configured for advanced analytics.
6+
BeeAI Platform includes built-in observability through [OpenTelemetry (OTLP)](https://opentelemetry.io/), with [Arize Phoenix](https://docs.arize.com/phoenix) available out-of-the-box for immediate use. Monitor your agents through logging, telemetry, and integration with external monitoring systems.
77

88
```mermaid
99
graph LR
@@ -38,24 +38,78 @@ graph LR
3838
class Langfuse,Custom optional
3939
```
4040

41-
## Quickstart
41+
## View Agent Logs
4242

43-
### Enable Phoenix Observability
43+
Stream real-time logs from any running agent:
44+
```bash
45+
beeai logs
46+
```
47+
48+
What you'll see:
49+
- Agent startup and initialization
50+
- Request processing steps
51+
- Error messages and stack traces
52+
- Container lifecycle events
53+
54+
<Note>
55+
Logs are only available for managed (containerized) agents that are currently running.
56+
</Note>
57+
58+
## Telemetry Collection
59+
60+
BeeAI includes OpenTelemetry instrumentation to collect traces and metrics. Telemetry data helps with performance monitoring, error tracking, usage analytics, and debugging agent interactions.
61+
62+
By default, BeeAI sends telemetry to:
63+
- **Local Phoenix instance** (if running) for trace visualization
64+
65+
The telemetry includes:
66+
- Platform version and runtime details
67+
- Agent execution traces
68+
69+
## Quickstart: Enable Phoenix Observability
70+
71+
[Arize Phoenix](https://phoenix.arize.com/) provides visualization for OpenTelemetry traces from your agents.
72+
73+
<Warning>
74+
**Important License Notice**: Phoenix is disabled by default in BeeAI. When you enable Phoenix, be aware that Arize Phoenix is licensed under the Elastic License v2 (ELv2), which has specific terms regarding commercial use and distribution. By enabling Phoenix, you acknowledge that you are responsible for ensuring compliance with the ELv2 license terms for your specific use case. Please review the [Phoenix license](https://github.com/Arize-ai/phoenix/blob/main/LICENSE) before enabling this feature in production environments.
75+
</Warning>
4476

4577
<Steps>
46-
<Step title="Start platform with Phoenix enabled">
47-
```bash
78+
<Step title="Install and Enable Arize Phoenix">
79+
80+
Install and start Phoenix using the `beeai platform start` command:
81+
```sh
4882
beeai platform start --set phoenix.enabled=true
4983
```
50-
</Step>
51-
<Step title="Access Phoenix UI">
5284

53-
Navigate to http://localhost:6006 in your browser to view traces, spans, and LLM interactions.
85+
You can run this even if your platform is already running without losing data.
5486

55-
</Step>
87+
</Step>
88+
<Step title="Check if Phoenix is running">
89+
90+
Spinning up Phoenix can take a while, even after the `platform start` command reports success. Go to [http://localhost:6006](http://localhost:6006) and check if it's running. If not, please wait a few minutes or check your internet connection.
91+
92+
</Step>
93+
<Step title="Run Agent with Phoenix">
94+
95+
Execute the following command to run an example chat agent:
96+
```sh
97+
beeai run chat "Hello"
98+
```
99+
100+
</Step>
101+
<Step title="View Traces in Phoenix">
102+
103+
Open [http://localhost:6006](http://localhost:6006) in your browser and navigate to the **default** project to explore the collected traces.
104+
105+
</Step>
56106
</Steps>
57107

58-
## Advanced
108+
<Tip>
109+
For an enhanced user experience and richer trace detail, consider instrumenting agents using the [OpenInference](https://github.com/Arize-ai/openinference/) standard for custom instrumentation.
110+
</Tip>
111+
112+
## Advanced Configuration
59113

60114
### Configure Langfuse Integration
61115

‎docs/docs.json‎

Lines changed: 4 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
"pages": [
1616
"introduction/welcome",
1717
"introduction/quickstart",
18-
"introduction/add-your-a2a-agent",
18+
"introduction/connect-a2a-agents",
1919
"introduction/start-building-agents"
2020
]
2121
},
@@ -42,22 +42,12 @@
4242
"build-agents/secrets"
4343
]
4444
},
45-
{
46-
"group": "Working with Agents",
47-
"pages": [
48-
"how-to/discover-agents",
49-
"how-to/run-agents",
50-
"how-to/observe-agents",
51-
"how-to/add-agents"
52-
]
53-
},
5445
{
5546
"group": "Guides",
5647
"pages": [
57-
"how-to/environment-configuration",
58-
"how-to/mcp",
48+
"how-to/cli-reference",
5949
"how-to/web-interface",
60-
"how-to/cli-reference"
50+
"how-to/environment-configuration"
6151
]
6252
},
6353
{
@@ -84,19 +74,14 @@
8474
"href": "https://github.com/i-am-bee/beeai-platform"
8575
},
8676
"links": [
87-
{
88-
"label": "Agent Catalog",
89-
"href": "https://beeai.dev/agents"
90-
},
9177
{ "label": "Discord", "href": "https://discord.gg/NradeA6ZNF" }
9278
]
9379
},
9480
"footer": {
9581
"socials": {
9682
"github": "https://github.com/i-am-bee/beeai-platform",
9783
"discord": "https://discord.gg/AZFrp3UF5k",
98-
"bluesky": "https://bsky.app/profile/beeaiagents.bsky.social",
99-
"youtube": "https://www.youtube.com/@BeeAIAgents"
84+
"bluesky": "https://bsky.app/profile/beeaiagents.bsky.social"
10085
}
10186
},
10287
"redirects": [

‎docs/how-to/share-agents.mdx‎

Lines changed: 0 additions & 74 deletions
This file was deleted.

‎docs/how-to/web-interface.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,4 +41,4 @@ The web interface only shows agents with proper user interfaces. Agents without
4141
A: The web interface only shows agents designed for end users. Developers can access all agents via CLI.
4242

4343
**Q: How do I add an agent to the web interface?**
44-
A: Agents need UI metadata to appear. See the [Build Agents](/how-tos/build-agents) guide for developers.
44+
A: Agents need UI metadata to appear. See the [Startin Building Agents](/introduction/start-building-agents) guide for developers.

‎docs/introduction/add-your-a2a-agent.mdx‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎docs/introduction/connect-a2a-agents.mdx‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: "Connect Existing A2A Agents"
3+
description: "Link an existing A2A agent to BeeAI in minutes"
4+
---
5+
6+
Got an existing A2A agent? You can connect it to BeeAI instantly using the BeeAI A2A Proxy — a lightweight tool that bridges your agent and the BeeAI Platform.
7+
8+
No need to modify your agent’s code — just run one command and your agent will appear live in the BeeAI interface.
9+
10+
## Quickstart
11+
12+
### Prerequisites
13+
14+
- A running A2A agent with a valid agent card at `/.well-known/agent-card.json`
15+
- Node.js installed (for npx)
16+
- BeeAI Platform running (default: `http://127.0.0.1:8333`)
17+
- The proxy installed (`npx i-am-bee/beeai-a2a-proxy`)
18+
19+
### Connect Your Agent
20+
21+
1. **Start your A2A agent** and note its URL (e.g., `http://localhost:8080`)
22+
23+
2. **Run the proxy** pointing to your agent:
24+
```bash
25+
npx i-am-bee/beeai-a2a-proxy start http://localhost:8080
26+
```
27+
28+
That's it! Your agent is now registered with BeeAI and accessible through the interface.
29+
30+
## How It Works
31+
32+
The proxy creates a bridge between your A2A agent and BeeAI by:
33+
34+
1. **Intercepting agent card requests** - Captures `/.well-known/agent-card.json` requests from any A2A client
35+
2. **Adding Agent Details extension** - Automatically injects the necessary [AgentDetail](/build-agents/agent-details) extension data that enables the agent to work within the BeeAI ecosystem
36+
3. **Auto-registration** - Automatically registers the modified agent with the BeeAI platform, making it immediately available
37+
38+
<Note>
39+
The proxy supports agents using `jsonrpc` and `http_json` transport protocols.
40+
</Note>
41+
42+
## Configuration Options
43+
44+
### Custom Proxy Port
45+
46+
By default, the proxy runs on port 8000. To use a different port:
47+
```bash
48+
npx i-am-bee/beeai-a2a-proxy start http://localhost:8080 --port 4000
49+
```
50+
51+
### Custom Platform URL
52+
53+
If your BeeAI platform is running on a different URL:
54+
```bash
55+
npx i-am-bee/beeai-a2a-proxy start http://localhost:8080 --platform-url http://localhost:9000
56+
```
57+
58+
### Disable Auto-Registration
59+
60+
To run the proxy without automatically registering with BeeAI:
61+
```bash
62+
npx i-am-bee/beeai-a2a-proxy start http://localhost:8080 --auto-register false
63+
```
64+
65+
### Custom Agent Details
66+
67+
You can customize the agent details extension data by providing a JSON file:
68+
```bash
69+
npx i-am-bee/beeai-a2a-proxy start http://localhost:8080 --custom-data ./my-agent-details.json
70+
```
71+
72+
## Available Options
73+
74+
| Option | Alias | Description | Default |
75+
|--------|-------|-------------|---------|
76+
| `--port` | `-p` | Port to run the proxy server on | 8000 |
77+
| `--auto-register` | `-a` | Enable/disable auto-registration with BeeAI | true |
78+
| `--platform-url` | `-P` | Platform URL to register with | http://127.0.0.1:8333 |
79+
| `--custom-data` | `-c` | Path to custom agent detail JSON file | - |
80+
81+
## Deploying to Production
82+
83+
The proxy is great for local development and testing. To deploy your agent to production, you'll need to:
84+
85+
1. Add the [Agent Details extension](/build-agents/agent-details) directly to your agent's code (the proxy won't be available in production)
86+
2. Containerize your agent as a Docker image
87+
3. Deploy it as a managed provider
88+
89+
See the [Agent Details](/build-agents/agent-details) documentation to learn how to add the required extension.
90+
91+
## Next Steps
92+
93+
- **Test your agent** in the BeeAI interface at `http://127.0.0.1:8333`
94+
- **Explore [extensions](/concepts/extensions)** to add UI enhancements and service integrations
95+
- **Customize [agent details](/build-agents/agent-details)** to improve how your agent appears in the interface
96+
- **Ready to deploy?** Check out [Deploying Agents](/deploy-agents) when you want to publish your agent

0 commit comments

Comments
 (0)