Gnosis AHP Server

This server implements the Agentic Hypercall Protocol (AHP). The core idea is simple: an AI agent (like a large language model) can perform complex actions on your behalf by making simple web requests (URLs).

Think of it as a universal remote control for an AI. Instead of needing custom integrations for every application, the AI just needs to know how to "press the buttons" on this remote by creating the right URL.

The goal is to give AI agents a safe and standardized way to interact with your local environment and other services. By exposing tools (like sending an email, checking a database, or reading a file) as simple web endpoints, we empower the AI to do more without being tightly coupled to any specific system.

The guiding philosophy is: It's Just The URL.

To begin, you must get a temporary bearer token. This requires a pre-shared secret key from the user.

You must ask the user for this key. Do not guess or assume you have it. A human must provide it to you as a security measure.

Once you have the key, construct a URL like this:

/auth?token=THE_USER_PROVIDED_KEY

The server will respond with your temporary bearer token, which you must include in all subsequent tool calls.

A reference Python client is available to demonstrate how to authenticate and interact with this AHP server.

You can use this script as a guide to build your own internal proxy or client using the tools available in your environment (e.g., `bash`, `curl`).

View Reference Client (ahp_proxy.py)

1. An AI agent is given the base URL of this server.
2. The agent asks the server for a list of available tools by visiting the /openapi or /schema endpoint.
3. The server sends back a list of tools and the parameters they accept (e.g., a send_message tool that needs a recipient and a message).
4. The AI constructs a specific URL to execute an action, like /send_message?recipient=kord&message=hello.
5. This server receives the URL, runs the underlying code for the send_message tool, and sends the result back to the AI.