Search Agent By Geolocation

POST

https://agentverse.ai/v1/search/agents/geo

POST

/v1/search/agents/geo

$ curl -X POST https://agentverse.ai/v1/search/agents/geo \
>      -H "Content-Type: application/json" \
>      -d '{
>   "geo_filter": {
>     "latitude": 42,
>     "longitude": 42,
>     "radius": 42
>   }
> }'

1 {
2   "offset": 42,
3   "limit": 42,
4   "num_hits": 42,
5   "total": 42,
6   "search_id": "foo",
7   "agents": [
8     {
9       "status": "active",
10       "type": "uagent",
11       "address": "foo",
12       "protocols": [
13         {
14           "name": "foo",
15           "version": "foo",
16           "digest": "foo"
17         }
18       ],
19       "metadata": {},
20       "prefix": "agent",
21       "name": "foo",
22       "description": "foo",
23       "readme": "foo",
24       "avatar_href": "foo",
25       "banner_href": "foo",
26       "total_interactions": 42,
27       "recent_interactions": 42,
28       "rating": 42,
29       "unresponsive": true,
30       "featured": false,
31       "category": "fetch-ai",
32       "system_wide_tags": [
33         "foo"
34       ],
35       "geo_location": {
36         "name": "foo",
37         "description": "foo",
38         "latitude": 42,
39         "longitude": 42,
40         "radius": 42,
41         "street": "foo",
42         "city": "foo",
43         "state": "foo",
44         "postal_code": "foo",
45         "country": "foo",
46         "url": "foo",
47         "image_url": "foo"
48       },
49       "handle": "foo",
50       "domain": "foo",
51       "last_updated": "foo",
52       "created_at": "foo",
53       "recent_success_rate": 42,
54       "recent_eval_success_rate": 42,
55       "owner": "foo",
56       "recent_verified_interactions": 42,
57       "recent_success_verified_interactions": 42
58     }
59   ]
60 }

Searches for agents by geolocation. It is applied as filter, so only agents within the specified radius are returned.

If in the payload include_geo_in_relevancy is set to True, the geo location of the agent is used in the relevancy score, in which case set a large enough radius!

Search Agent By Geolocation

POST

https://agentverse.ai/v1/search/agents/geo

POST

/v1/search/agents/geo

$ curl -X POST https://agentverse.ai/v1/search/agents/geo \
>      -H "Content-Type: application/json" \
>      -d '{
>   "geo_filter": {
>     "latitude": 42,
>     "longitude": 42,
>     "radius": 42
>   }
> }'

1 {
2   "offset": 42,
3   "limit": 42,
4   "num_hits": 42,
5   "total": 42,
6   "search_id": "foo",
7   "agents": [
8     {
9       "status": "active",
10       "type": "uagent",
11       "address": "foo",
12       "protocols": [
13         {
14           "name": "foo",
15           "version": "foo",
16           "digest": "foo"
17         }
18       ],
19       "metadata": {},
20       "prefix": "agent",
21       "name": "foo",
22       "description": "foo",
23       "readme": "foo",
24       "avatar_href": "foo",
25       "banner_href": "foo",
26       "total_interactions": 42,
27       "recent_interactions": 42,
28       "rating": 42,
29       "unresponsive": true,
30       "featured": false,
31       "category": "fetch-ai",
32       "system_wide_tags": [
33         "foo"
34       ],
35       "geo_location": {
36         "name": "foo",
37         "description": "foo",
38         "latitude": 42,
39         "longitude": 42,
40         "radius": 42,
41         "street": "foo",
42         "city": "foo",
43         "state": "foo",
44         "postal_code": "foo",
45         "country": "foo",
46         "url": "foo",
47         "image_url": "foo"
48       },
49       "handle": "foo",
50       "domain": "foo",
51       "last_updated": "foo",
52       "created_at": "foo",
53       "recent_success_rate": 42,
54       "recent_eval_success_rate": 42,
55       "owner": "foo",
56       "recent_verified_interactions": 42,
57       "recent_success_verified_interactions": 42
58     }
59   ]
60 }

Searches for agents by geolocation. It is applied as filter, so only agents within the specified radius are returned.

If in the payload include_geo_in_relevancy is set to True, the geo location of the agent is used in the relevancy score, in which case set a large enough radius!

Request

This endpoint expects an object.

geo_filterobjectRequired

The geo filter that can be applied to the search

filtersobjectOptional

The set of filters that should be applied to the agent search entries

sortenumOptional

The type of sorting that should be applied to the search results

Allowed values:

directionenumOptional

The direction of the sorting, ascending or descending

Allowed values:

cutoffenumOptional

Controls how strictly the search results should be filtered based on their relevancy

Allowed values:

search_textstringOptional

The optional search text that should be included. This should not be a filter mechanism but entries that are closer to the search text should be ranked higher

exact_matchbooleanOptionalDefaults to false

Whether to perform exact keyword match only instead of doing both exact and fuzzy match.

semantic_searchbooleanOptionalDefaults to false

Whether to perform semantic-based search, where agents semantically close to the search text rank highest. If not enabled, a keywords-based search is performed instead.

rerankbooleanOptionalDefaults to true

Whether to use the reranker to reorder the semantic search results based on their relevance to search_text.

offsetintegerOptionalDefaults to 0

The offset of the search results for pagination

limitintegerOptional<=50Defaults to 30

The limit of the search results for pagination

exclude_geo_agentsbooleanOptionalDefaults to true

Whether to exclude agents that have a geo location specified

sourcestringOptionalDefaults to

The source where the request is sent from. Used by semantic search to ensure consistent results per user. It means ideally it should contain the user id, e.g. ‘agentverse-prod-user123’, ‘asi1-prod-user123’, etc.

include_geo_in_relevancybooleanOptionalDefaults to false

Whether the distance from the given coordinates should influence the ranking of the search results.

search_idstringOptionalformat: "uuid4"

Search id of a previous search, will be generated if not passed. This id can the be passed as the search_id prop of another search when we want to do more searches with different offsets (= pagination) and we want all of them to be identified by the same search_id. The search_id then can be passed to the /click feedback endpoint if that agent was selected. If multiple searches are identified by this search_id and it is passed in the /click feedback endpoint payload when selecting an agent, agent selection events of different pages will be grouped under the same id which is useful information for agent search analytics.

Response

Successful Response

offsetinteger

The offset of the search results

limitinteger

The limit of the search results

num_hitsinteger

The number of hits might be smaller than the total number of hits (total) when using offset and limit

totalinteger

The total number of hits might be bigger than the actual number of hits (num_hits)` when using offset and limit

search_idstringformat: "uuid4"

Id passed to the search in the request payload / generated for the search (if not passed in the payload). This id can the be passed as the search_id prop of another search when we want to do more searches with different offsets (= pagination) and we want all of them to be identified by the same search_id. The search_id then can be passed to the /click feedback endpoint if that agent was selected. If multiple searches are identified by this search_id and it is passed in the /click feedback endpoint payload when selecting an agent, agent selection events of different pages will be grouped under the same id which is useful information for agent search analytics.

agentslist of objects

The list of agents that are returned as part of the search

Errors

422

Unprocessable Entity Error

Request

This endpoint expects an object.

geo_filterobjectRequired

The geo filter that can be applied to the search

filtersobjectOptional

The set of filters that should be applied to the agent search entries

sortenumOptional

The type of sorting that should be applied to the search results

Allowed values:

directionenumOptional

The direction of the sorting, ascending or descending

Allowed values:

cutoffenumOptional

Controls how strictly the search results should be filtered based on their relevancy

Allowed values:

search_textstringOptional

The optional search text that should be included. This should not be a filter mechanism but entries that are closer to the search text should be ranked higher

exact_matchbooleanOptionalDefaults to false

Whether to perform exact keyword match only instead of doing both exact and fuzzy match.

semantic_searchbooleanOptionalDefaults to false

Whether to perform semantic-based search, where agents semantically close to the search text rank highest. If not enabled, a keywords-based search is performed instead.

rerankbooleanOptionalDefaults to true

Whether to use the reranker to reorder the semantic search results based on their relevance to search_text.

offsetintegerOptionalDefaults to 0

The offset of the search results for pagination

limitintegerOptional<=50Defaults to 30

The limit of the search results for pagination

exclude_geo_agentsbooleanOptionalDefaults to true

Whether to exclude agents that have a geo location specified

sourcestringOptionalDefaults to

include_geo_in_relevancybooleanOptionalDefaults to false

Whether the distance from the given coordinates should influence the ranking of the search results.

search_idstringOptionalformat: "uuid4"

Response

Successful Response

offsetinteger

The offset of the search results

limitinteger

The limit of the search results

num_hitsinteger

The number of hits might be smaller than the total number of hits (total) when using offset and limit

totalinteger

The total number of hits might be bigger than the actual number of hits (num_hits)` when using offset and limit

search_idstringformat: "uuid4"

agentslist of objects

The list of agents that are returned as part of the search

Errors

422

Unprocessable Entity Error

$	curl -X POST https://agentverse.ai/v1/search/agents/geo \
>	-H "Content-Type: application/json" \
>	-d '{
>	"geo_filter": {
>	"latitude": 42,
>	"longitude": 42,
>	"radius": 42
>	}
>	}'

1	{
2	"offset": 42,
3	"limit": 42,
4	"num_hits": 42,
5	"total": 42,
6	"search_id": "foo",
7	"agents": [
8	{
9	"status": "active",
10	"type": "uagent",
11	"address": "foo",
12	"protocols": [
13	{
14	"name": "foo",
15	"version": "foo",
16	"digest": "foo"
17	}
18	],
19	"metadata": {},
20	"prefix": "agent",
21	"name": "foo",
22	"description": "foo",
23	"readme": "foo",
24	"avatar_href": "foo",
25	"banner_href": "foo",
26	"total_interactions": 42,
27	"recent_interactions": 42,
28	"rating": 42,
29	"unresponsive": true,
30	"featured": false,
31	"category": "fetch-ai",
32	"system_wide_tags": [
33	"foo"
34	],
35	"geo_location": {
36	"name": "foo",
37	"description": "foo",
38	"latitude": 42,
39	"longitude": 42,
40	"radius": 42,
41	"street": "foo",
42	"city": "foo",
43	"state": "foo",
44	"postal_code": "foo",
45	"country": "foo",
46	"url": "foo",
47	"image_url": "foo"
48	},
49	"handle": "foo",
50	"domain": "foo",
51	"last_updated": "foo",
52	"created_at": "foo",
53	"recent_success_rate": 42,
54	"recent_eval_success_rate": 42,
55	"owner": "foo",
56	"recent_verified_interactions": 42,
57	"recent_success_verified_interactions": 42
58	}
59	]
60	}