add agent to guardrail doc (#1138)

Author: snegi-do

specification/DigitalOcean-public.v2.yaml

@@ -2234,6 +2234,13 @@ paths:
     delete:
       $ref: 'resources/gen-ai/genai_detach_agent_function.yml'
 
+  /v2/gen-ai/agents/{agent_uuid}/guardrails:
+    post:
+      $ref: 'resources/gen-ai/genai_attach_agent_guardrails.yml'
+
+  /v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}:
+    delete:
+      $ref: 'resources/gen-ai/genai_detach_agent_guardrail.yml'
 
   /v2/gen-ai/agents/{agent_uuid}/knowledge_bases:
     post:

specification/resources/gen-ai/definitions.yml

@@ -3399,6 +3399,19 @@ apiLinkAgentGuardrailOutput:
     agent:
       $ref: '#/apiAgent'
   type: object
+apiLinkAgentGuardrailsInputPublic:
+  description: Information about linking an agent to a guardrail
+  properties:
+    agent_uuid:
+      description: The UUID of the agent.
+      example: '"12345678-1234-1234-1234-123456789012"'
+      type: string
+    guardrails:
+      description: The list of guardrails to attach.
+      items:
+        $ref: '#/apiAgentGuardrailInput'
+      type: array
+  type: object
 apiLinkAgentInputPublic:
   description: Information for linking an agent
   properties:
@@ -4900,6 +4913,12 @@ apiUnlinkAgentFunctionOutput:
     agent:
       $ref: '#/apiAgent'
   type: object
+apiUnlinkAgentGuardrailInputPublic:
+  properties:
+    agent_uuid:
+      example: '"12345678-1234-1234-1234-123456789012"'
+    guardrail_uuid:
+      example: '"12345678-1234-1234-1234-123456789012"'
 apiUnlinkAgentGuardrailOutput:
   description: UnlinkAgentGuardrailOutput description
   properties:

specification/resources/gen-ai/examples/curl/genai_attach_agent_guardrails.yml

@@ -0,0 +1,18 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/gen-ai/agents/1c8be326-00fe-11f1-b542-ca68c578b05c/guardrails" \
+    -d '{
+      "guardrails": [
+        {
+          "guardrail_uuid": "69bcc61c-2bb2-49fd-b6ed-7c1bd73d6442",
+          "priority": 1
+        },
+        {
+          "guardrail_uuid": "dc72b12b-bd45-46c9-bca1-00a6624aac3a",
+          "priority": 2
+        }
+      ]
+    }'

specification/resources/gen-ai/examples/curl/genai_detach_agent_guardrail.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X DELETE \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/gen-ai/agents/1c8be326-00fe-11f1-b542-ca68c578b04c/guardrails/69bcc61c-2bb2-49fd-b6ed-7c1bd73d6572"

specification/resources/gen-ai/genai_attach_agent_guardrails.yml

@@ -0,0 +1,47 @@
+description: To attach guardrails to an agent, send a POST request to `/v2/gen-ai/agents/{agent_uuid}/guardrails`.
+operationId: genai_attach_agent_guardrails
+parameters:
+- description: The UUID of the agent.
+  example: '"123e4567-e89b-12d3-a456-426614174000"'
+  in: path
+  name: agent_uuid
+  required: true
+  schema:
+    type: string
+requestBody:
+  content:
+    application/json:
+      schema:
+        $ref: ./definitions.yml#/apiLinkAgentGuardrailsInputPublic
+responses:
+  "200":
+    content:
+      application/json:
+        schema:
+          $ref: ./definitions.yml#/apiLinkAgentGuardrailOutput
+    description: A successful response.
+    headers:
+      ratelimit-limit:
+        $ref: ../../shared/headers.yml#/ratelimit-limit
+      ratelimit-remaining:
+        $ref: ../../shared/headers.yml#/ratelimit-remaining
+      ratelimit-reset:
+        $ref: ../../shared/headers.yml#/ratelimit-reset
+  "401":
+    $ref: ../../shared/responses/unauthorized.yml
+  "404":
+    $ref: ../../shared/responses/not_found.yml
+  "429":
+    $ref: ../../shared/responses/too_many_requests.yml
+  "500":
+    $ref: ../../shared/responses/server_error.yml
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+security:
+- bearer_auth:
+  - genai:create
+summary: Attach Guardrails to an Agent
+tags:
+- GradientAI Platform
+x-codeSamples:
+- $ref: examples/curl/genai_attach_agent_guardrails.yml

specification/resources/gen-ai/genai_detach_agent_guardrail.yml

@@ -0,0 +1,49 @@
+description: To detach a guardrail from an agent, send a DELETE request to `/v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}`.
+operationId: genai_detach_agent_guardrail
+parameters:
+- description: The UUID of the agent.
+  example: '"123e4567-e89b-12d3-a456-426614174000"'
+  in: path
+  name: agent_uuid
+  required: true
+  schema:
+    type: string
+- description: The UUID of the guardrail to detach.
+  example: '"123e4567-e89b-12d3-a456-426614174000"'
+  in: path
+  name: guardrail_uuid
+  required: true
+  schema:
+    type: string
+responses:
+  "200":
+    content:
+      application/json:
+        schema:
+          $ref: ./definitions.yml#/apiUnlinkAgentGuardrailOutput
+    description: A successful response.
+    headers:
+      ratelimit-limit:
+        $ref: ../../shared/headers.yml#/ratelimit-limit
+      ratelimit-remaining:
+        $ref: ../../shared/headers.yml#/ratelimit-remaining
+      ratelimit-reset:
+        $ref: ../../shared/headers.yml#/ratelimit-reset
+  "401":
+    $ref: ../../shared/responses/unauthorized.yml
+  "404":
+    $ref: ../../shared/responses/not_found.yml
+  "429":
+    $ref: ../../shared/responses/too_many_requests.yml
+  "500":
+    $ref: ../../shared/responses/server_error.yml
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+security:
+- bearer_auth:
+  - genai:delete
+summary: Detach a Guardrail from an Agent
+tags:
+- GradientAI Platform
+x-codeSamples:
+- $ref: examples/curl/genai_detach_agent_guardrail.yml