Agents

​

Overview

• AgentsClient: The main client class for interacting with agents. It handles:
  • Calling agents
  • Asking questions to agents
  • Listing available toolkits
  • Listing available agents
  • Invoking specific tools
• AgentDescription: Describes an agent, its input/output schemas, requirements, labels, etc.
• ToolDescription: Describes an individual tool, including metadata and input schemas.
• ToolkitDescription: Groups multiple tools under one toolkit name, allowing retrieval of individual tools by name.
• ToolkitConfiguration: Describes which tools in a toolkit you want to enable or use.

​

API Methods

​

1. Call

• Description:
  • Allows you to send a request to an agent to perform a specific action or function.
• Parameters:
  • name: The name of the agent you want to call.
  • url: The URL endpoint or route on the agent side that you want to call.
  • arguments: A record of arguments (payload) that you want to send to the agent.
• Returns: Response object (likely a JsonResponse), containing the output or result from the agent.

await room.agents.make_call(
  name="example-agent",
  url="some-endpoint",
  arguments={ "foo": "bar" }
)

​

2. Ask

• Description:
  • Sends a question or prompt to the specified agent. You can optionally provide an array of RequiredToolkit objects indicating which toolkits (and which tools within them) are available for this agent to use.
  • The ask method allows you to send a question or prompt to an agent, specifying the agent’s name, any toolkits you want to enable, and the arguments you want to pass.
  • This is useful for getting responses from agents that can process natural language or perform specific tasks.
• Parameters:
  • agent: The name/identifier of the agent you want to ask.
  • requires: An optional array of RequiredToolkit objects that specify which toolkits are allowed for this ask.
  • arguments: A record of arguments (payload) that you want to send to the agent.
• Returns: Response object (likely a JsonResponse), containing the output or result from the agent.

answer = await room.agents.ask(
  agent="example-agent",
  requires: [RequiredToolkit(name="example-toolkit", tools=["toolA", "toolB"])],
  arguments={
    "prompt": "Explain quantum computing in simple terms."
  }
)
print(answer)  # logs the JSON structure from the agent

​

3. List Toolkits

• Description:
  • Retrieves a list of all available toolkits and parses each one into a ToolkitDescription.
  • This is useful for discovering which toolkits are available for use and what tools they contain.
• Parameters: None
• Returns An array of ToolkitDescription objects.

all_toolkits = await room.agents.list_toolkits()

for toolkit in all_toolkits:
  print(f"Toolkit: {toolkit.name}, Tools: {[tool.name for tool in toolkit.tools]}")

​

4. List Agents

• Description:
  • Lists the agents currently available. Each is converted into an AgentDescription object.
  • This is useful for discovering which agents are available for use and what their capabilities are.
• Parameters: None
• Returns An array of AgentDescription objects.

agents = await room.agents.list_agents()
for agent in agents:
  print(f"Agent: {agent.name}, Title: {agent.title}")

​

5. Invoke Tool

• Description:
  • Invokes a specific tool within a toolkit in a given toolkit with the provided arguments.
  • This is useful for directly interacting with tools without going through an agent.
• Parameters:
  • toolkit: The name of the toolkit that contains the tool you want to invoke.
  • tool: The name of the specific tool you want to invoke.
  • arguments: A record of arguments (payload) that you want to send to the tool. Returns Response object (likely a JsonResponse), containing the output or result from the invoked tool.

response = await room.agents.invoke_tool(
  toolkit="example-toolkit",
  tool="toolA",
  arguments={"param1": "value1"}
)
# 'response' may contain JSON data or a message detailing the tool's output.

​

Typical Workflow

1. Instantiate RoomClient
   NodeJs

   Copy

   Ask AI

   const room = new RoomClient({protocol});
   

2. List Available Agents and Toolkits
   NodeJs

   Copy

   Ask AI

   const agents = await room.agents.listAgents();
   const toolkits = await room.agents.listToolkits();
   

3. Ask a Question to an Agent
   NodeJs

   Copy

   Ask AI

   const toolkit = new RequiredToolkit({ name: "quantum-toolkit", tools: ["add"] });
   const result = await room.agents.ask({
     agent: "my-agent",
     requires: [toolkit],
     arguments: { prompt: "Explain the concept of entanglement." }
   });
   console.log("Agent Answer:", result);
   

4. Invoke a Specific Tool (If needed)
   NodeJs

   Copy

   Ask AI

   const toolResponse = await room.agents.invokeTool({
     toolkit: "example-toolkit",
     tool: "toolA",
     arguments: { foo: "bar" }
   });
   console.log("Tool Response:", toolResponse);
   

5. Call an Agent Directly (If the agent supports such calls)
   NodeJs

   Copy

   Ask AI

   await room.agents.call({
     name: "myAgent",
     url: "run-something",
     arguments: { data: "payload" }
   });
   

​

AgentDescription

​

ToolDescription

​

ToolkitDescription

​

ToolkitConfiguration

​

Conclusion