# How runAgent Works ?

### 1. Introduction

BeaconBar.runAgent() is the main entry point that lets your application talk directly to any AI agent you've configured within beacon. When you call this function, you send a user query (along with agentRouterId and session identifiers), and the function immediately starts streaming (streaming is optional parameter) the agent's intelligent response back to your application in real-time.

***

### 2. API Overview

The runAgent API enables real-time interaction with Beacon AI agents. It handles agent routing, session continuity, and optional response streaming through a single, easy-to-use interface.

Key Features:

* Agent routing via Agent Router ID of Beacon.
* Session-based conversation handling
* Optional streaming responses
* Support for file-based inputs

***

### 3. API Invocation

The API is exposed through the BeaconBar JavaScript interface:

BeaconBar.runAgent(options)

This method is asynchronous and returns a Promise.

***

### 4. Request Parameters

#### 4.1 Required Parameters

| Parameter     | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| agentRouterId | string | Unique identifier of the target AI agent |
| query         | string | User input or instruction                |

#### 4.2 Optional Parameters

| Parameter | Type     | Description                                                                                       |
| --------- | -------- | ------------------------------------------------------------------------------------------------- |
| sessionId | string   | Helps continue an existing conversation. If not provided, a new session is created on every call. |
| files     | array    | Files provided as input to the agent.                                                             |
| callBack  | function | Callback for streaming response chunks.                                                           |

***

### 5. Streaming Responses

When a callBack function is provided, the API streams partial responses as the agent processes the request. This is recommended for chat-style interfaces.

callBack: (text) => { 

    console.log(text); 

}

***

### 6. Example Usage

const response = await BeaconBar.runAgent({

  agentRouterId: "agent\_123",

  sessionId: "session\_abc",

  query: "Explain how this product works",

  callBack: (text) => console.log(text)

});

***

### 7. Best Practices

* Reuse sessionId values to preserve conversation context
* Use streaming callbacks for improved user experience
* Validate agentRouterId before invoking the API
* Avoid empty or malformed queries

***

### 8. Conclusion

The runAgent API provides a standardised and scalable interface for integrating Beacon AI agents into client applications with minimal effort.

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.beacon.li/how-runagent-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.