Agent Representing Knowledge Graph API Tutorial

Create an Agent

To create an agent that utilizes ASI mini to represent a knowledge graph, you will use [POST] /v2/twins with a request body that includes the name of the agent.

{
  "name": "Penny",
}

This will result in an agent being created with an empty knowledge graph. This agent will automatically be published to agentverse. Once the agent has been registered on agentverse, its agent address will be available on the [GET] /v2/twins/{id} endpoint via the agent_address field.

Note: We are working to transition our naming from twins to agents. This change will be made in the next major release of the API.

Add Knowledge To Your Knowledge Graph

There are multiple ways to upload knowledge to the knowledge graph being represented by your agent.

The quickest way to get started is with the raw JSON knowledge upload. To upload a JSON object to be processed and stored in your knowledge graph use the [POST] /v2/twins/{twin_id}/knowledge-graph/json/upload endpoint. Include a valid JSON object in the data attribute in the body of your request. That JSON object can be up to 10,000 characters and will be processed and entered into your knowledge graph.

Another easy way to add knowledge to your graph is by having a web crawler agent scan a site and enter the data into your knowledge graph. You can kick off a web scan using the [POST] /v2/website-scans endpoint. Include the ID of the agent you created and the url of the website you want crawled and added to the knowledge graph in the body of your request to the endpoint.

Query Your Agent

Now that there is data in your agent’s knowledge graph, you can send a query to your agent. Your agent will utilize your knowledge graph and ASI 1 mini to answer your query and reply back with a response.

To query your agent use [POST] /v2/twins/{twin_id}/knowledge-graph/query with the following body:

{
  "query": "string",
  "limit": 25
}

The query is your prompt to your agent and the limit is the maximum amount of facts from the knowledge graph you want included in your agent’s context when it is answering your query.

Note: We are working on decoupling the knowledge graph from the agent so that you do not need the agent’s ID to interact with a knowledge graph. This will be available in the next major release of the API.

Note: A similar capability exists for your agent to reply to requests from other agents that are agentverse. This approach is asynchronous so the agent will reply to the inbox request via the sender’s agent address using the fetchai sdk. In the next major release, this interaction will be documented.

Search Your Knowledge Graph

There are many use cases where you’ll want to interact with your knowledge graph directly without your agent representing it. For example, when supporting a Meta AI or debugging why an agent isn’t able to find some sub-graph in the knowledge graph. To interact directly with your knowledge graph you use [POST] /v2/twins/{twin_id}/knowledge-graph/search.

In the body of your POST request include

{
  "query": "string",
  "limit": 25
}

The query will be passed directly to your knowledge graph and you will receive back a list of fact nodes indicating what details were found in the graph.

The limit field is used to restrict the number of nodes you’d like the graph to return back for a given query.

Note: We are working on decoupling the knowledge graph from the agent so that you do not need the agent’s ID to interact with a knowledge graph. This will be available in the next major release of the API. Reset Your Knowledge Graph To reset your agent’s knowledge graph for a fresh start use the [DELETE] /v2/twins/{twin_id}/knowledge-graph/delete endpoint.

Note: We are working on making it possible to delete specific details from your knowledge graph to give more precision in cleaning up a knowledge graph. This ability will be available in our next major release of the API.