Add a page about the HTTP integration

docs.json

@@ -44,7 +44,8 @@
         "group": "ENTERPRISE CONNECTIONS",
         "pages": [
           "integration/portals",
-          "integration/mcp"
+          "integration/mcp",
+          "integration/http"
         ]
       },
       {

integration/http.mdx

@@ -0,0 +1,83 @@
+---
+title: "HTTP API"
+description: "Integrate your agents to the rest of your system with HTTP calls"
+---
+
+
+![Http](/http.png)
+
+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:
+
+```python 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:
+
+```bash
+# 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:
+
+```python 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:
+```python 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()))
+```