APIs
AgentVerse
Hosting
Bookmark

Hosting API

Welcome to the Hosting API documentation.

Overview

The hosting API allows you to manage your agents that are hosted by Agentverse. This involves creating new agents, updating the code of existing agents, starting and stopping agents, and getting logs of agents.

Endpoints
GET /v1/hosting/agents
POST /v1/hosting/agents
 
GET /v1/hosting/agents/:agentAddress
DELETE /v1/hosting/agents/:agentAddress
 
GET /v1/hosting/agents/:agentAddress/code
PUT /v1/hosting/agents/:agentAddress/code
 
POST /v1/hosting/agents/:agentAddress/start
POST /v1/hosting/agents/:agentAddress/stop
 
GET /v1/hosting/agents/:agentAddress/logs/latest
DELETE /v1/hosting/agents/:agentAddress/logs
 
GET /v1/hosting/usage/current
GET /v1/hosting/usage/:year/:month
 
GET /v1/hosting/usage/agents/:address/current
GET /v1/hosting/usage/agents/:address/:year/:month

Notable Objects

The Agent Object

  • Name
    name
    Type
    string
    Description

    The given name of the agent. This is only a label that is used internally so users can keep track of their agents.

  • Name
    address
    Type
    string
    Description

    The address of the agent. This is also the current public key of the agent.

  • Name
    running
    Type
    boolean
    Description

    The current state of the agent. true if the agent is currently running, false otherwise.

  • Name
    compiled
    Type
    boolean | null
    Description

    The current code compilation status for the agent. true if the agent is compiled, false if the compilation failed, null if the agent has not been compiled yet.

  • Name
    revision
    Type
    integer
    Description

    The current revision of the agent. Everytime an update is made to the agent, the revision is incremented.

  • Name
    code_digest
    Type
    string | null
    Description

    The current digest of the code of the agent. Useful for determining if there have been code changes that need to be applied to the agent.

    This value can be null if the agent has not been compiled yet.

  • Name
    wallet_address
    Type
    string | null
    Description

    The wallet address that is associated with the agent. If a wallet address is not associated with the agent, this value will be null.

Sample Agent Object
{
    "name": "My first agent",
    "address": "agent1q2dfhywtt8xazrdyzgap6gzdd7uhk4e0wmc3gjqt42esauaegcm8cuvclpj",
    "running": false,
    "compiled": true,
    "revision": 7,
    "code_digest": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "wallet_address": "fetch1dtwgzm6km4394erexa8ka05wva306wt9cc3mwk"
}

The AgentCode Object

  • Name
    digest
    Type
    string
    Description

    Digest of the Agent's code.

  • Name
    code
    Type
    string
    Description

    The Agent's code.

  • Name
    timestamp
    Type
    string, date-time
    Description

    Timestamp of when the code was updated.

Sample AgentCode Object
{
    "digest": "66089877730d0501a4ff1efedf545279d5db120d0960f1ea6a1c00f834ff9530",
    "code": "alice = Agent(name="alice", seed="sample seed")",
    "timestamp": "2023-08-22T14:09:48.259000"
}

The AgentCodeDigest Object

  • Name
    digest
    Type
    string
    Description

    Digest of the Agent's code.

Sample AgentCodeDigest Object
{
    "digest": "66089877730d0501a4ff1efedf545279d5db120d0960f1ea6a1c00f834ff9530"
}

The AgentLog Object

  • Name
    log_timestamp
    Type
    string, date-time
    Description

    Timestamp of the log entry.

  • Name
    log_entry
    Type
    string
    Description

    Log entry text.

Sample AgentLog Object
{
    "log_timestamp": "2023-08-22T14:09:48.259000", 
    "log_entry": "[INFO]: My count is: 0"
}

The NewAgent Object

  • Name
    NewAgent
    Type
    string
    Description

    Name of the new Agent.

Sample NewAgent Object
{
    "name": "My first agent"
}

The UpdateAgentCode Object

  • Name
    Code
    Type
    string
    Description

    The code for the new Agent.

Sample UpdateAgentCode Object
{
    "code": "alice = Agent(name="alice", seed="sample seed")"
}

Request and response library

Getting a list of your agents

Endpoint: GET /v1/hosting/agents

Request

Request for listing all of your agents at once
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/agents

Responses

On a success the response will be an array of Agent Object properties.
json
[
  {
    "name": "My first agent",
    "address": "agent1q2dfhywtt8xazrdyzgap6gzdd7uhk4e0wmc3gjqt42esauaegcm8cuvclpj",
    "running": false,
    "compiled": true,
    "revision": 7,
    "code_digest": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "wallet_address": "fetch1dtwgzm6km4394erexa8ka05wva306wt9cc3mwk"
  }
]

Creating a new agent

Endpoint: POST /v1/hosting/agents

Request

Request for creating a new agent
  • Name
    name
    Type
    string
    Description
    The given name of the agent. This is only a label that is used internally so users can keep track of their agents.
bash
curl \
-X POST \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/agents \
 -d '{"name":"My newest agent"}'

Responses

On a success the response will be an array of Agent object properties.
json
{
  "name": "My newest agent",
  "address": "agent1q2dfhywtt8xazrdyzgap6gzdd7uhk4e0wmc3gjqt42esauaegcm8cuvclpj",
  "running": false,
  "compiled": true,
  "revision": 1,
  "code_digest": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "wallet_address": "fetch1dtwgzm6km4394erexa8ka05wva306wt9cc3mwk"
}

Look up specific Agent

Endpoint: GET /v1/hosting/agents/{agentAddress}

Request

Looks up a specific agent by address on the hosting platform
  • Name
    address
    Type
    string
    Description
    The address of the agent. This is also the current public key of the agent
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/agents/{agentAddress}

Responses

On success, the response will be an array of the specified Agent's properties.
json
[
  {
    "name": "InitialTest",
    "address": "agent1qtw0hy4kj65fv6j7qyv5mgdecq7c4qyqfqnjgc25wz4vf5h47l9l6m7qqtg",
    "domain": "None",
    "running": false,
    "compiled": null,
    "revision": 0,
    "code_digest": null,
    "wallet_address": "fetch1mh0zmyddgcvspz7ye5zdrzjcfjtz54cgafak67"
  }
]

Delete Specified Agent

Endpoint: DELETE /v1/hosting/agents/{agentAddress}

Request

Delete a specific agent, identified by address
  • Name
    address
    Type
    string
    Description
    The address of the agent. This is also the current public key of the agent
bash
curl \
-X DELETE \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/agents/{agentAddress}

Responses

On a success the response will be the deletion of the specified Agent from the platform
json
{}

Look up Agent code

Endpoint: GET /v1/hosting/agents/{agentAddress}/code

Request

Looks up the code for an agent, specified by address.
  • Name
    address
    Type
    string
    Description
    The address of the agent. This is also the current public key of the agent.
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/agents/{agentAddress}/code

Responses

On success, the response will be an array of JSON objects containing the digest, code, and timestamp.
json
[
  {
    "digest": "4a8d510d546de8ff74aa27abaa7ebd95bf7876d8b31b265f6022c49d7b49cf45",
    "code": "Example code",
    "timestamp": "2023-08-22T12:49:45.856000+00:00"
  }
]

Update Agent Code for a specific Agnet

Endpoint: PUT /v1/hosting/agents/{agentAddress}/code

Request

Updates the code for a specific agent, identified by address.
  • Name
    address
    Type
    string
    Description
    The address of the agent. This is also the current public key of the agent.
  • Name
    code
    Type
    string
    Description
    The code for a specific agent on the Agentverse where 'string' represents the code read from a file.
bash
curl \
-X PUT \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/agents/{agentAddress}/code \
 -d '{"code":"\n# Congratulations on creating your first agent!\n#\n# This agent simply writes a greeting in the logs on a scheduled time interval.\n#\n# In this example we will use:\n# - 'agent': this is your instance of the 'Agent' class that we will give an 'on_interval' task\n# - 'ctx': this is the agent's 'Context', which gives you access to all the agent's important functions\n\n# A decorator (marked by the '@' symbol) just wraps the function defined under it in another function.\n# This decorator tells your agent to run the function on a time interval with the specified 'period' in seconds.\n# These functions must be 'async' because agents need to be able to perform many tasks concurrently.\[email protected]_interval(period=3.0)\nasync def say_hello(ctx: Context):\n    # ctx.logger is a standard Python logger that can log text with various levels of urgency\n    # (exception, warning, info, debug). Here we will just use the 'info' level to write a greeting\n    ctx.logger.info(f\"Hello, I'm an agent and my address is {ctx.address}.\")\n"}'

Responses

On success, the response will be a JSON object with the updated digest.
json
[
  {
    "digest": "66089877730d0501a4ff1efedf545279d5db120d0960f1ea6a1c00f834ff9530"
  }
]

Start a specific agent, identified by address.

Endpoint: POST /v1/hosting/agents/{address}/start

Request

Starts a specific agent, identified by address
  • Name
    address
    Type
    string
    Description
    The address of the agent. This is also the current public key of the agent.
bash
curl \
-X POST \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/agents/{address}/start

Responses

On success, the agent selected by address will start, and the API will return an array with the Agent's properties.
json
[
  {
    "name": "InitialTest",
    "address": "agent1qvnppqyhk4hu0q64tnfkspux8hpd9zayyclhafvkz5340uqx3ax02txfll7",
    "domain": "None",
    "running": "True",
    "compiled": "False",
    "revision": "4",
    "code_digest": "66089877730d0501a4ff1efedf545279d5db120d0960f1ea6a1c00f834ff9530",
    "wallet_address": "None"
  }
]

Stop a specific agent, identified by address.

Endpoint: POST /v1/hosting/agents/{address}/stop

Request

Stops a specific agent, identified by address
  • Name
    address
    Type
    string
    Description
    The address of the agent. This is also the current public key of the agent.
bash
curl \
-X POST \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/agents/{address}/stop

Responses

On success, the agent selected by address will stop, and the API will return an array with the Agent's properties.
json
[
  {
    "name": "InitialTest",
    "address": "agent1qvnppqyhk4hu0q64tnfkspux8hpd9zayyclhafvkz5340uqx3ax02txfll7",
    "domain": "None",
    "running": "False",
    "compiled": "False",
    "revision": "4",
    "code_digest": "66089877730d0501a4ff1efedf545279d5db120d0960f1ea6a1c00f834ff9530",
    "wallet_address": "None"
  }
]

Get Latest Logs For Agent

Endpoint: GET /v1/hosting/agents/{address}/logs/latest

Request

Get the latest logs for an Agent, identified by address
  • Name
    address
    Type
    string
    Description
    The address of the agent. This is also the current public key of the agent.
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/agents/{address}/logs/latest

Responses

On successful retrieval of the specified agent logs, the response will be an array of json objects containing the timestamp and log entry.
json
[
  {
    "log_timestamp": "2023-08-22T14:09:48.259000",
    "log_entry": "[INFO]: My count is: 0"
  }
]

Delete the latest logs for an Agent

Endpoint: DELETE /v1/hosting/agents/{address}/logs

Request

Delete the latest logs for an Agent, identified by address
  • Name
    address
    Type
    string
    Description
    The address of the agent. This is also the current public key of the agent.
bash
curl \
-X DELETE \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/agents/{address}/logs

Responses

On success, the response will be the deletion of the specified agent logs.
json
{}

Get current Agent usage

Endpoint: GET /v1/hosting/usage/current

Request

Get data about the usage of the currently selected Agent
  • Name
    address
    Type
    string
    Description
    The address of the agent. This is also the current public key of the agent.
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/usage/current \
 -d '{"address":"agent1qvnppqyhk4hu0q64tnfkspux8hpd9zayyclhafvkz5340uqx3ax02txfll7"}'

Responses

On success, the response will be a json array with properties containing data about the usage of the currently selected agent.
json
[
  {
    "year": "2023",
    "month": "8",
    "computation_time": "2291",
    "num_messages": "12",
    "num_message_bytes": "0",
    "num_agents": "4",
    "quota_computation_time": "3100000000",
    "quota_num_messages": "31000000",
    "quota_message_bytes": "63488000000",
    "quota_agents": "1000"
  }
]

Get Agent Usage for a specific year and month

Endpoint: GET /v1/hosting/usage/{year}/{month}

Request

Get data about the usage of the currently selected Agent for a selected year and month
  • Name
    address
    Type
    string
    Description
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/usage/{year}/{month} \
 -d '{"address":"agent1qvnppqyhk4hu0q64tnfkspux8hpd9zayyclhafvkz5340uqx3ax02txfll7"}'

Responses

On success, the response will be a json array with properties containing data about the usage of the currently selected Agent for a selected year and month.
json
[
  {
    "year": "2023",
    "month": "8",
    "computation_time": "2291",
    "num_messages": "12",
    "num_message_bytes": "0",
    "num_agents": "4",
    "quota_computation_time": "3100000000",
    "quota_num_messages": "31000000",
    "quota_message_bytes": "63488000000",
    "quota_agents": "1000"
  }
]

Get Agent Usage for a specific year and month

Endpoint: GET /v1/hosting/usage/agents/{address}/current

Request

Get data about the usage for an Agent, identified by address
  • Name
    address
    Type
    string
    Description
    The address of the agent. This is also the current public key of the agent.
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/usage/agents/{address}/current

Responses

On success the response will be an array of json properties containing information about the current usage for a specified Agent identified by address.
json
[
  {
    "year": "2023",
    "month": "8",
    "computation_time": "1230",
    "num_messages": "4",
    "num_message_bytes": "0"
  }
]

Get current Agent usage selected by address year and month

Endpoint: GET /v1/hosting/usage/agents/{address}/{year}/{month}

Request

Get data about the usage for an Agent, identified by address for a specific year and month
  • Name
    address
    Type
    string
    Description
    The address of the agent. This is also the current public key of the agent.
bash
curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1/hosting/usage/agents/{address}/{year}/{month}

Responses

On success, the response will be a json array with properties for the specified Agent identified by address for a specific year and month
json
[
  {
    "year": "2023",
    "month": "3",
    "computation_time": "1230",
    "num_messages": "4",
    "num_message_bytes": "0"
  }
]

Was this page helpful?

AlmanacMailroom
Bookmark