An agent node can provide an HTTP endpoint to access agents:

  • List all agents on the node.
  • Start a conversation with an agent.
  • List conversations.
  • List all the tools on the node.

You can also easily create our own HTTP routes and tailor the interactions with your agent to your needs.

Here is how you can start a standard HTTP server when creating an agent node:

images/main/main.py
from ockam import Agent, Node, Repl, HttpServer
from sys import argv


async def main(node):
    agent = await Agent.start(node, 
      name="cerberus", 
      instructions="You use network tools to detect intrusions")
    await Repl.start(agent, argv[1])


Node.start(main, http_server=HttpServer(listen_address=argv[2]))

This will serve the node standard HTTP API to interact with agents. For example:

# return the list of all agents referenced on the node (either local or remote)
curl http://127.0.0.1:8000/agents

# send a message to an agent
curl -X POST http://localhost:8000/agents/cerberus \
  -H "Content-Type: application/json" \
  -d '{"message":"Is my network safe?", "scope":"acme", "conversation":"1"}'

# retrieve all the conversations for a given scope
curl http://localhost:8000/agents/cerberus/scopes/acme

You can also define your own API, by creating your own routes:

images/main/api.py
from fastapi import FastAPI
from fastapi.responses import JSONResponse

class Api:
    def __init__(self):
        self.api = FastAPI()

    def routes(self, node):
        @self.api.post("/analysis")
        async def create_analysis(network: str):
            print(f"Analyzing the network {network}...")
            return JSONResponse(content={"status": "ok"})

The access to node gives you the mean to interact with all the agents referenced on the node and even start new ones if necessary!

Finally the Api is set on the HttpServer to ensure it is merged with the rest of the node API:

images/main/main.py
from ockam import Agent, Node, Repl, HttpServer
from sys import argv
from api import Api

async def main(node):
    agent = await Agent.start(node, 
      name="cerberus", 
      instructions="You use network tools to detect intrusions")
    await Repl.start(agent, argv[1])


Node.start(main, http_server=HttpServer(listen_address=argv[2], api=Api()))