# 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[​](#step-1-open-or-create-a-project "Direct link to 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[​](#step-2-add-a-new-agent "Direct link to 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[​](#step-3-register-the-agent "Direct link to 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)[​](#step-4-set-up-instrumentation-setup-agent-panel "Direct link to 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.

* Python
* Ballerina

### 4.1 Install AMP Instrumentation Package[​](#41-install-amp-instrumentation-package "Direct link to 4.1 Install AMP Instrumentation Package")

```
pip install amp-instrumentation
```

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

Using a virtual environment?

Activate it before installing so the package is available on your path.

### 4.2 Generate an API Key[​](#42-generate-an-api-key "Direct link to 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[​](#43-set-environment-variables "Direct link to 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[​](#44-run-your-agent-with-instrumentation "Direct link to 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[​](#41-import-amp-module "Direct link to 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[​](#42-add-build-configuration-to-ballerinatoml "Direct link to 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[​](#43-update-configtoml "Direct link to 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[​](#44-generate-an-api-key "Direct link to 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[​](#45-set-environment-variables "Direct link to 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[​](#46-run-your-agent "Direct link to 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[​](#step-5-view-traces-in-the-console "Direct link to 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.