Cognizant Technology Solutions Agent Service API

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:
    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
    ChatResponse:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/ChatRequest'
        response:
          $ref: '#/components/schemas/ChatMessage'
      description: Response structure for Chat gRPC method
    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.
    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
    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
    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.
    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
    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.
    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.
    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.
    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.
    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
    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).'