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.
Last updated