Skip to content

observe-first-agent.mdx

Latest commit

 

History

History
156 lines (102 loc) · 4.24 KB

observe-first-agent.mdx

File metadata and controls

156 lines (102 loc) · 4.24 KB
sidebar_position 1
title Observe Your First Agent in WSO2 Agent Manager
description Register an externally hosted agent, enable zero-code instrumentation, and view traces in the AMP Console.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Observe Your First Agent

This tutorial walks you through registering an externally-hosted agent with WSO2 Agent Manager, connecting it with zero-code instrumentation, and viewing its traces in the AMP Console.

Step 1: Open or Create a Project

WSO2 Agent Manager organises agents inside Projects.

  1. Open the AMP Console.
  2. Click the project switcher in the top navigation bar.
  3. Select an existing project (e.g. Default Project) or click + Create a Project, enter a name and description, then click Create.

Step 2: Add a New Agent

  1. Inside your project, click + Add Agent.
  2. On the Add a New Agent screen, choose Externally-Hosted Agent — use this when your agent runs outside the AMP platform (locally, on your own infrastructure, or in a third-party cloud).

Step 3: Register the Agent

  1. Fill in the Agent Details:
    • Name — e.g. my-first-agent
    • Description (optional)
  2. Click Register.

You are taken to the agent's Overview page. A Setup Agent panel opens automatically on the right.

Step 4: Set Up Instrumentation (Setup Agent Panel)

The Zero-code Instrumentation Guide in the Setup Agent panel walks you through the setup steps. Use the Language dropdown at the top-right of the panel to select your agent's language — Python or Ballerina — and follow the corresponding instructions below.

4.1 Install AMP Instrumentation Package

pip install amp-instrumentation

This provides the ability to instrument your agent and export traces.

:::tip Using a virtual environment? Activate it before installing so the package is available on your path. :::

4.2 Generate an API Key

In the panel, select a Token Duration (e.g. 1 year) and click Generate. Copy the key immediately — it will not be shown again.

4.3 Set Environment Variables

export AMP_OTEL_ENDPOINT="<INSTRUMENTATION_URL>"
export AMP_AGENT_API_KEY="<your-generated-api-key>"

Set the above env variables.

4.4 Run Your Agent with Instrumentation

Prefix your normal run command with amp-instrument:

amp-instrument <run_command>

For example:

# Python script
amp-instrument python my_agent.py

# FastAPI / async service
amp-instrument uvicorn app:main --reload

# Poetry / uv managed projects
amp-instrument poetry run python agent.py
amp-instrument uv run python agent.py

No changes to your agent code are required.

4.1 Import Amp Module

Add the following import to your Ballerina program:

import ballerinax/amp as _;

4.2 Add Build Configuration to Ballerina.toml

Add the following to your Ballerina.toml to enable observability when building:

[build-options]
observabilityIncluded = true

4.3 Update Config.toml

Enable tracing and set the provider to AMP in your Config.toml:

[ballerina.observe]
tracingEnabled = true
tracingProvider = "amp"

4.4 Generate an API Key

In the panel, select a Token Duration (e.g. 1 year) and click Generate. Copy the key immediately — it will not be shown again.

4.5 Set Environment Variables

export BAL_CONFIG_VAR_BALLERINAX_AMP_OTELENDPOINT="<INSTRUMENTATION_URL>"
export BAL_CONFIG_VAR_BALLERINAX_AMP_APIKEY="<your-generated-api-key>"

Set the above env variables.

4.6 Run Your Agent

Run your Ballerina program as usual:

bal run

The observability module is loaded automatically via the import.

Step 5: View Traces in the Console

Once your agent has handled a few requests:

  1. In the left sidebar, under OBSERVABILITY, click Traces.
  2. Each trace represents one end-to-end agent invocation. Click any trace to expand it:
    • The root span shows end-to-end latency and the agent name.
    • LLM spans show the model, token counts, and call latency.
    • Tool spans show tool name, input, and output.