Skip to main content

Core User Workflow

Interacting with agents on Nexus is a straightforward process designed to get you from discovery to implementation as quickly as possible. The entire workflow can be broken down into four simple steps: Discover, Install, Authenticate, and Interact.

Step 1: Discover Agents in the Public Registry​

Your journey begins at our central registry, which is a public marketplace of all available agents. You can easily find the perfect agent for your needs using our powerful search and filtering tools.

You can search for agents based on:

  • Skill: The specific capability you need (e.g., text-summarization, image-classification).
  • Tags: Broader categories or technologies associated with the agent (e.g., finance, nlp, python).
  • Agent Name: If you already know the name of the agent you're looking for.

Agent Discovery UI Mockup - A search bar and filters for finding agents (Optional: Consider adding a mockup image of your search UI for better visualization)

Step 2: Install Agents to Your Private Repository​

Once you find an agent you want to use, you "install" it.

This action doesn't download any code to your local machine. Instead, it adds a reference to the agent into your personal, private repository called "My Agents". Think of this as your personal workspace or a collection of your activated tools. Only agents present in your "My Agents" repository can be called by your API keys.

This approach ensures that you have a curated and managed list of agents that your applications depend on.

Step 3: Create an API Key​

To interact with your installed agents programmatically, you need to authenticate your requests. This is done using a secure API key.

You can generate and manage your API keys from your account dashboard. Each key is unique to your account and should be treated like a password.

Keep Your API Keys Secure

Your API key grants access to interact with agents in your "My Agents" repository. Do not share it publicly, expose it in client-side code, or commit it to version control.

Step 4: Interact via the REST API​

With an agent installed and an API key in hand, you can now communicate with it using our simple and powerful REST API.

To do this, you make a POST request to our API endpoint, specifying which agent you want to call and what action you want it to perform. You must include your Authorization token, your API Key, and your User ID in the headers..

curl --location --request POST 'https://hncugknujacihsgyrvtd.supabase.co/functions/v1/get-agents-card?query=%27agent-name%27' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImhuY3Vna251amFjaWhzZ3lydnRkIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTUyNzExNzIsImV4cCI6MjA3MDg0NzE3Mn0.X6JDJveHFO__gWtff1dzQievPimVFRZTimtuIVD7W6c' \
--header 'Content-Type: application/json' \
--header 'api-key: your api key' \
--header 'user-id: your user id' \
--data ''

Step 5: Fetch Agent Details via API​

Once you've selected an agent, you don't "install" it in the traditional sense. Instead, you make a simple API call to our platform to fetch its deployment details.

This API response provides two critical pieces of information:

Docker Image: The full name of the agent's Docker image (e.g., registry.hub.docker.com/agent-creator/summarizer:latest).

Agent Card: A JSON object containing all the metadata you need to interact with the agent, such as its API endpoints, required input schema, and authentication methods.

Step 6: Pull & Run the Agent via Docker​

Now, you use the Docker image name from the previous step to pull the agent from Docker Hub and run it as a container in your own environment.

Prerequisite

You must have Docker installed and running on your machine to proceed.

First, pull the image using the docker pull command.

docker pull agent-creator/summarizer:latest

Next, run the agent using docker run. You'll typically need to map a port to allow your applications to communicate with the agent container.

# This command runs the agent in the background (-d) and maps port 8080
# on your local machine to port 8080 inside the container (-p 8080:8080).
docker run -d -p 8080:8080 --name my-summarizer-agent agent-creator/summarizer:latest

Your agent is now running locally and ready to receive requests!

Step 7: Interact with Your Local Agent​

With the agent running in a Docker container, you can now interact with it by making REST API calls to localhost on the port you mapped. Use the Agent Card you fetched in Step 2 as your guide to structure the request correctly.

Here’s how you would call the summarization agent we just started:

Visualizing the Workflow​

To better understand the process, let's visualize the entire user journey from discovering an agent to using it in your own application.

High-Level User Flowchart​

This diagram shows the complete lifecycle of finding, installing, and using an agent on the Nexus platform.

This flowchart illustrates:

  • Discovery & Installation: A user browses the public registry on the website and installs the desired agents into their private "My Agents" repository.

  • Authentication: The user generates a unique API key from their dashboard.

  • Interaction: The user's application makes an authenticated API call to our gateway, which securely invokes the correct agent and returns the result.

This sequence diagram shows:

  • Your application sends a POST request with the API key and payload.

  • Our API first authenticates the key and then authorizes the action by checking if the agent is in your "My Agents" list.

  • Once validated, the API forwards the task to the target agent.

  • The agent processes the information and returns the agent meta-data, which is then passed back to your application.