Every API here is available over the APIs.io API and to AI agents over MCP.
{
"openapi": "3.0.3",
"info": {
"title": "NeuroSan",
"version": "0.0.1"
},
"paths": {
"/api/v1/list": {
"get": {
"tags": [
"ConciergeService"
],
"summary": "List",
"description": "Called when a client needs the information about available agents.",
"operationId": "ConciergeService_List",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConciergeResponse"
}
}
}
},
"default": {
"description": "Default error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
}
}
}
},
"/api/v1/{agent_name}/connectivity": {
"get": {
"tags": [
"AgentService"
],
"summary": "Connectivity",
"description": "Called when a client needs the internal connectivity description of an agent.",
"operationId": "AgentService_Connectivity",
"parameters": [
{
"name": "agent_name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConnectivityResponse"
}
}
}
},
"default": {
"description": "Default error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
}
}
}
},
"/api/v1/{agent_name}/function": {
"get": {
"tags": [
"AgentService"
],
"summary": "Function",
"description": "Called when a client needs the function description of an agent.",
"operationId": "AgentService_Function",
"parameters": [
{
"name": "agent_name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FunctionResponse"
}
}
}
},
"default": {
"description": "Default error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
}
}
}
},
"/api/v1/{agent_name}/streaming_chat": {
"post": {
"tags": [
"AgentService"
],
"summary": "StreamingChat",
"description": "Most important semantics of the streaming:\n 1) The \"answer\" to a query of any agent network is in the *last* streamed\n AGENT_FRAMEWORK message.\n 2) To RESTfully continue your conversation with the agent network:\n The very last AGENT_FRAMEWORK message before the stream closes will\n have its chat_context field filled in with a structure. You can\n copy this whole-cloth to the chat_context of your next StreamingChat\n request to continue the conversation.\n 3) It is important to note that since this is a streaming API, for HTTP clients:\n a) Any single response will always be on the same line. That is,\n responses will not be broken up across multiple lines in an\n HTTP response.\n b) We cannot yet guarantee that there will be only one streamed response\n per HTTP response line. That is, it is possible for more than one\n response *might* come on a single line if they come quickly enough,\n though this is not the empirically observed norm.",
"operationId": "AgentService_StreamingChat",
"parameters": [
{
"name": "agent_name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatResponse"
}
}
}
},
"default": {
"description": "Default error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"AgentInfo": {
"type": "object",
"properties": {
"agent_name": {
"type": "string",
"description": "Agent name"
},
"description": {
"type": "string",
"description": "Outward-facing description of what the agent does."
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional metadata describing where this agent falls into larger agent grouping(s)."
}
},
"description": "Description of an agent's function"
},
"ChatContext": {
"type": "object",
"properties": {
"chat_histories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatHistory"
},
"description": "A potentially full list of chat histories that pertain to the node. These will typically come in the last message of any particular agent's chat stream. Do not expect any or all internal agents will broadcast their chat history, but you can at least expect the front-man to broadcast his."
}
},
"description": "Message for holding the state of play for any chat session such that should the client send this back to the service, a different server knows exactly where to pick up where the previous conversation left off."
},
"ChatFilter": {
"type": "object",
"properties": {
"chat_filter_type": {
"enum": [
"UNKNOWN",
"MINIMAL",
"MAXIMAL"
],
"type": "string",
"description": "For now allow for an enum to describe how we want chat messages streamed. In the future the description of this server-side filter might offer more fine-grained control (hence an encapsulating structure).",
"format": "enum"
}
},
"description": "Allows for controlling the messages that get streamed via StreamingChat."
},
"ChatHistory": {
"type": "object",
"properties": {
"origin": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Origin"
}
},
"messages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatMessage"
}
}
},
"description": "A structure for storing chat history for a given node in the graph described by the origin."
},
"ChatMessage": {
"type": "object",
"properties": {
"type": {
"enum": [
"UNKNOWN",
"SYSTEM",
"HUMAN",
"AI",
"AGENT",
"AGENT_FRAMEWORK",
"AGENT_TOOL_RESULT",
"AGENT_PROGRESS"
],
"type": "string",
"description": "The type of chat message",
"format": "enum"
},
"text": {
"type": "string",
"description": "String contents of any chat message"
},
"mime_data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MimeData"
},
"description": "Optional bytes for any non-text media referenced by this message. For some chat sources, the string text field might also be populated as a reference for how the data was created. If this happens, then it should be safe to assume that the text is enough to represent the message in any history carried forward. As of 1/13/25 this is a forward-looking, experimental field not likely to be used in regular operation until we can get proper plumbing of such data in place."
},
"origin": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Origin"
},
"description": "Optional list of Origin structures (see above) describing the origin of the chat message. The intent here is to be able to distiguish responses from nested agents. For each top-level agent/front-man (perhaps on another server) that is called, an extra structure is added to the list."
},
"structure": {
"type": "object",
"description": "Optional structure for a message whose contents are parsed JSON. The idea is to have the server side do the parsing when requested by the agent spec. As of 1/30/25 this is a forward-looking, experimental field not likely to be used in regular operation until we can get proper plumbing of such data in place."
},
"chat_context": {
"$ref": "#/components/schemas/ChatContext"
},
"tool_result_origin": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Origin"
},
"description": "Optional list of Origin structures (see above) describing the origin of a tool result."
},
"sly_data": {
"type": "object",
"description": "This is an entirely optional map whose keys refer to data that is better left out of the LLM chat stream. The keys themselves might appear in the chat stream, referring to the data, but the data itself does not. The intent is for the key references to be passed to tools, which then grab the values by programmatic means, but these tools might also have private data to send back to the client as well."
}
},
"description": "Structure describing a single chat message. This could be a single response, or a list of these might comprise a chat history."
},
"ChatRequest": {
"type": "object",
"properties": {
"sly_data": {
"type": "object",
"description": "This is an entirely optional map whose keys refer to data that is better left out of the LLM chat stream. The keys themselves might appear in the chat stream, referring to the data, but the data itself does not. The intent is for the key references to be passed to tools, which then grab the values by programmatic means."
},
"user_message": {
"$ref": "#/components/schemas/ChatMessage"
},
"chat_context": {
"$ref": "#/components/schemas/ChatContext"
},
"chat_filter": {
"$ref": "#/components/schemas/ChatFilter"
}
},
"description": "Request structure for Chat gRPC method"
},
"ChatResponse": {
"type": "object",
"properties": {
"request": {
"$ref": "#/components/schemas/ChatRequest"
},
"response": {
"$ref": "#/components/schemas/ChatMessage"
}
},
"description": "Response structure for Chat gRPC method"
},
"ConciergeResponse": {
"type": "object",
"properties": {
"agents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentInfo"
},
"description": "List of agent descriptions"
}
},
"description": "Response structure for List gRPC method"
},
"ConnectivityInfo": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"description": "The agent network node whose connectivity is being described"
},
"tools": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of tool nodes that are possible to reach from the origin This might include references into external agent networks, perhaps hosted on other servers. Separate calls to those guys will need to be made in order to gain information about their own connectivity, if this is actually desired by the client. Worth noting that server-side agent descriptions are allowed to withhold connectivity info they deem private, or too much of an implementation detail. That is, connectivity reported is only as much as the server wants a client to know."
},
"display_as": {
"type": "string",
"description": "A string describing the nature of the agent so that a client UI can add an indication of its differences between other nodes in the graph. Values from the neuro-san include: * llm_agent (default) * coded_tool * langchain_tool * external_agent ... however individual agent networks can define their own strings on a per-node basis to customize their own visualizations."
},
"metadata": {
"type": "object",
"description": "Metadata for the node. This comes as a free-form dictionary which can have agent-network defined semantics. Some key/value pairs might eventually become standardized as part of the neuro-san API as time goes on, for instance for fine-grained Responsible AI (RAI) scores. As those keys become standardized, they will be added here in the docs."
}
}
},
"ConnectivityResponse": {
"type": "object",
"properties": {
"connectivity_info": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConnectivityInfo"
},
"description": "The description of the agent network's internal connectivity ... as far as the agent wants the outside world to know.."
},
"metadata": {
"type": "object",
"description": "Metadata for the network as a whole. This comes as a free-form dictionary which can have agent-network defined semantics. Some key/value pairs might eventually become standardized as part of the neuro-san API as time goes on, for instance for network-level Responsible AI (RAI) scores. As those keys become standardized, they will be added here in the docs."
}
},
"description": "Response structure for Connectivity gRPC method"
},
"Function": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Outward-facing description of what the agent does."
},
"parameters": {
"type": "object",
"description": "Optional map of parameters passed in via the natural-language chat text channel that the agent needs in order to work. This is really a pydantic/OpenAI function description, which is a bit too complex to specify directly in protobuf."
},
"sly_data_schema": {
"type": "object",
"description": "This is a description of what data is expected to come *in* via the sly_data channel. Optional map of parameters passed in via the sly_data dictionary private data channel that the agent needs in order to work. Just like the parameters above, this is really a pydantic/OpenAI function description, which is a bit too complex to specify directly in protobuf."
},
"sly_data_output_schema": {
"type": "object",
"description": "This is a description of what data is expected to come *out* via the sly_data channel. Optional map of parameters returned via the sly_data dictionary private data channel that the agent will return after its work. Just like the parameters above, this is really a pydantic/OpenAI function description, which is a bit too complex to specify directly in protobuf."
}
},
"description": "Description of an agent's function"
},
"FunctionResponse": {
"type": "object",
"properties": {
"function": {
"$ref": "#/components/schemas/Function"
}
},
"description": "Response structure for Function gRPC method"
},
"GoogleProtobufAny": {
"type": "object",
"properties": {
"@type": {
"type": "string",
"description": "The type of the serialized message."
}
},
"additionalProperties": true,
"description": "Contains an arbitrary serialized message along with a @type that describes the type of the serialized message."
},
"MimeData": {
"type": "object",
"properties": {
"mime_type": {
"type": "string",
"description": "MIME type of the image data"
},
"mime_bytes": {
"type": "string",
"description": "Raw bytes of the image",
"format": "byte"
}
},
"description": "A Message identifying image data"
},
"Origin": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"description": "String name of the originating tool, as per the agent spec."
},
"instantiation_index": {
"type": "integer",
"description": "Some tools can be called more than once by one or more different paths. Allow for an instantiation index to distinguish these in the chat stream. Index counting starts at 0.",
"format": "int32"
}
}
},
"Status": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].",
"format": "int32"
},
"message": {
"type": "string",
"description": "A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client."
},
"details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GoogleProtobufAny"
},
"description": "A list of messages that carry the error details. There is a common set of message types for APIs to use."
}
},
"description": "The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors)."
}
}
},
"tags": [
{
"name": "AgentService",
"description": "The service comprises all the exchanges to the backend in support of a single agent's\n services. Routing is done by way of agent name on the grpc service hosting the agent,\n so as to keep info about which agents are hosted private (grpc gives the hand when a\n particular agent is unknown."
},
{
"name": "ConciergeService",
"description": "The service provides system-wide information about resources available\n in current instance of neuro-san."
}
]
}