> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ellipsis1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# First example: Weather Agent

> Build and instrument a simple LangChain tool-calling agent with Google Gemini and the Ellipsis SDK.

# Starter project

This walkthrough uses the [E1 Weather Agent example repository](https://github.com/BlackNinjaGo/tool-agent-weather) to demonstrate how to add E1 observability to a small LangChain application.

The application is a TypeScript Node.js agent that uses Google's Gemini model and a custom weather tool. The Ellipsis SDK captures supported execution events through a LangChain callback handler and exports telemetry to E1.

> [!NOTE]
>
> The `get_weather` tool in this example returns a fixed demonstration string.
> It does not call a live weather API or provide real weather data.

## What you will build

The example combines:

* **E1 SDK** — instrumentation and trace export.
* **LangChain** — agent creation and tool orchestration.
* **Google Gemini** — `gemini-2.5-flash` model.
* **TypeScript and Node.js** — application runtime.
* **Zod** — schema definition for the tool input.

## Prerequisites

Before starting, make sure you have:

* Node.js 22 or later.
* An E1 account and a valid agent API key.
* The E1 ingestion URL from the [API reference](https://docs.ellipsis1.com/api.md).
* A Google AI API key.

## 1. Get the example project

Clone the repository and move into the project directory:

```bash theme={null}
git clone https://github.com/BlackNinjaGo/tool-agent-weather.git
cd tool-agent-weather
```

Install the dependencies:

```bash theme={null}
npm install
```

The project includes the E1 SDK, LangChain, the Google Gemini integration, dotenv, Zod and TypeScript development tooling.

## 2. Configure your environment

Create a `.env` file in the project root:

```dotenv theme={null}
ELLIPSIS_INGESTION_URL=your_e1_ingestion_url
ELLIPSIS_AGENT_API_KEY=your_e1_agent_api_key
GOOGLE_AI_API_KEY=your_google_ai_api_key
```

Replace the placeholder values with your actual credentials.

* `ELLIPSIS_INGESTION_URL` identifies the E1 telemetry ingestion endpoint.
* `ELLIPSIS_AGENT_API_KEY` authenticates the application and associates its telemetry with the E1 agent.
* `GOOGLE_AI_API_KEY` authenticates requests to Google Gemini.

> [!WARNING]
>
> Do not commit your `.env` file. Keep all E1 and Google API keys out of source
> control.

## 3. Initialize the E1 SDK

The example loads environment variables with `dotenv`, then creates the E1 configuration:

```typescript theme={null}
import { Config, initEllipsis } from "@ellipsis1/sdk";
import dotenv from "dotenv";

dotenv.config();

const config: Config = {
  ingestionUrl: process.env.ELLIPSIS_INGESTION_URL!,
  apiKey: process.env.ELLIPSIS_AGENT_API_KEY!,
  globalTags: ["first-try", "basic example", "gemini"],
  globalMetadata: {
    name: "Agent-Weather-Tool",
    version: "0.1.0",
    stage: "DEV",
  },
};
```

The example adds global tags and metadata so the exported telemetry is associated with the `Agent-Weather-Tool` project, version `0.1.0`, running in the `DEV` stage.

## 4. Create the LangChain instrumentation handler

Initialize the SDK at the top level of the application and create its LangChain handler:

```typescript theme={null}
const ellipsis = initEllipsis(config, "info");
const handler = ellipsis.langchain();
```

The optional `"info"` argument sets the SDK logging level for this example.

The call to `ellipsis.langchain()` creates the callback handler that will be passed to the agent invocation.

## 5. Define the weather tool

The example defines a tool named `get_weather`. It accepts a city as a string and returns a demonstration response:

```typescript theme={null}
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(({ city }) => `It's always sunny in ${city}!`, {
  name: "get_weather",
  description: "Get the weather for a given city",
  schema: z.object({
    city: z.string(),
  }),
});
```

The tool schema describes the expected input. The model can use the tool when it determines that the user's request requires weather information.

## 6. Configure the Gemini model

The example uses Google's `gemini-2.5-flash` model through the LangChain Google integration:

```typescript theme={null}
import { ChatGoogleGenerativeAI } from "@langchain/google-genai";

const model = new ChatGoogleGenerativeAI({
  model: "gemini-2.5-flash",
  apiKey: process.env.GOOGLE_AI_API_KEY,
  maxRetries: 1,
});
```

## 7. Create the agent

Create a LangChain agent with the Gemini model and the weather tool:

```typescript theme={null}
import { createAgent } from "langchain";

const agent = createAgent({
  model,
  tools: [getWeather],
});
```

The agent can now decide when to call `get_weather` in response to a user message.

## 8. Invoke the agent with E1 instrumentation

The final step is to pass the Ellipsis handler to the agent invocation:

```typescript theme={null}
await agent.invoke(
  {
    messages: [{ role: "user", content: "What's the weather in Vilnius?" }],
  },
  {
    callbacks: [handler],
  }
);
```

The `callbacks` option is the connection point between the LangChain execution and the Ellipsis SDK. The handler captures supported events emitted by the framework and exports the resulting telemetry to E1.

## 9. Run the example

The repository provides a development script:

```bash theme={null}
npm run dev
```

This runs the TypeScript entry point using `tsx`.

The project is configured as ESM-first and also includes scripts to build and run ESM and CommonJS outputs:

```bash theme={null}
npm run build:esm
npm run start:esm
```

For the CommonJS build:

```bash theme={null}
npm run build:cjs
npm run start:cjs
```

## 10. Inspect the execution in E1

After the agent has executed and telemetry has been exported:

1. Sign in to [E1](https://app.ellipsis1.com).
2. Open the organization workspace containing the agent whose API key you configured.
3. Open the `Agent-Weather-Tool` agent.
4. Inspect the traces received from the example application.

Depending on the telemetry emitted by the framework and model integration, you can explore trace and span relationships, agent and chain operations, model information, token usage, execution timing, tool calls and errors.

## View the resulting trace waterfall

The screenshot below shows the trace captured by E1 and visualized as a waterfall chart. It provides an overview of the execution timeline, making it easy to follow the sequence and duration of each operation, as well as the relationships between the agent, Gemini model invocation, and `get_weather` tool call.

![Weather Agent trace displayed as a waterfall chart in E1.](https://mintcdn.com/ellipsis-87b8d78e/J0Of_sOrxfQd8HTk/examples/img/waterfall.png?fit=max\&auto=format\&n=J0Of_sOrxfQd8HTk\&q=85\&s=32c69df2353af90f3878c3f7b2625d70)

Weather Agent — resulting trace waterfall

## Inspect and export the raw trace in the JSON viewer

You can also inspect the raw JSON data generated during the agent execution. The JSON viewer lets you explore the different data structures captured in the trace and export them for further analysis or debugging.

![Weather Agent raw trace displayed in the E1 JSON viewer.](https://mintcdn.com/ellipsis-87b8d78e/J0Of_sOrxfQd8HTk/examples/img/json-viewer.png?fit=max\&auto=format\&n=J0Of_sOrxfQd8HTk\&q=85\&s=c7bd45355670d89da2d78f490063272f)

Weather Agent — raw trace in the JSON viewer

## Explore detailed activity and cost breakdowns

Finally, open the associated activity details to review the cost breakdown for each model invocation. This view provides greater visibility into model usage and the costs associated with the agent execution.

![Weather Agent activity details showing the cost breakdown per model invocation in E1.](https://mintcdn.com/ellipsis-87b8d78e/J0Of_sOrxfQd8HTk/examples/img/activity.png?fit=max\&auto=format\&n=J0Of_sOrxfQd8HTk\&q=85\&s=260ef4b8abbf811ab28cba67dd2b2084)

Weather Agent — detailed activity and cost breakdown

## Explore the source code

The full example is available on GitHub:

> [card] [BlackNinjaGo/tool-agent-weather](https://github.com/BlackNinjaGo/tool-agent-weather)
>
> Browse the complete TypeScript implementation, environment template and
> project configuration.

## What to try next

* Change the user message and observe another agent execution.
* Add another LangChain tool and inspect how its execution appears in the trace.
* Change the global tags or metadata to distinguish environments or versions.
* Replace the demonstration weather tool with a real weather API integration.

For more configuration options, continue to the [TypeScript SDK reference](https://docs.ellipsis1.com/sdk/typescript.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.