openapi: 3.2.0 info: title: NeuroSan Agent Service API version: 0.0.1 description: 'The service comprises all the exchanges to the backend in support of a single agent''s services. Routing is done by way of agent name on the grpc service hosting the agent, so as to keep info about which agents are hosted private (grpc gives the hand when a particular agent is unknown.' tags: - name: AgentService description: 'The service comprises all the exchanges to the backend in support of a single agent''s services. Routing is done by way of agent name on the grpc service hosting the agent, so as to keep info about which agents are hosted private (grpc gives the hand when a particular agent is unknown.' paths: /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: 1) The "answer" to a query of any agent network is in the *last* streamed AGENT_FRAMEWORK message. 2) To RESTfully continue your conversation with the agent network: The very last AGENT_FRAMEWORK message before the stream closes will have its chat_context field filled in with a structure. You can copy this whole-cloth to the chat_context of your next StreamingChat request to continue the conversation. 3) It is important to note that since this is a streaming API, for HTTP clients: a) Any single response will always be on the same line. That is, responses will not be broken up across multiple lines in an HTTP response. b) We cannot yet guarantee that there will be only one streamed response per HTTP response line. That is, it is possible for more than one response *might* come on a single line if they come quickly enough, 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: 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. 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 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 FunctionResponse: type: object properties: function: $ref: '#/components/schemas/Function' description: Response structure for Function gRPC method 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. 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).' 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 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 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. 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. 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. 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. 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