Jump to

• Request
• Response

Copy an Agent

post

/20260430/aiDataPlatforms/{aiDataPlatformId}/workspaces/{workspaceKey}/agents/{agentKey}/actions/copy

Copy an Agent.

Request

Path Parameters

• agentKey(required): string
  The UUID of the Agent
• aiDataPlatformId(required): string
  Minimum Length: 1

  Maximum Length: 500

  The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the AI Data Platform (Data Lake) instance.
• workspaceKey(required): string
  Minimum Length: 1

  Maximum Length: 200

  The key of the Workspace

Header Parameters

• if-match: string
  Maximum Length: 1000

  For optimistic concurrency control. In the PUT or DELETE call for a resource, set the `if-match` parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
• opc-request-id: string
  Maximum Length: 255

  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. The only valid characters for request IDs are letters, numbers, underscore, and dash.
• opc-retry-token: string
  Maximum Length: 64

  A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of running that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations. For example, if a resource has been deleted and removed from the system, then a retry of the original creation request might be rejected.
• should-update-recent: boolean
  A flag to identify if the recent list should be updated.

  Default Value: false

Body ()

Details for copying the agent

Root Schema : CopyAgentDetails

Type: object

Details to copy the agent to target workspace.

Show Source

• targetDescription: string
  Agent description.
• targetDisplayName: string
  Agent name.
• targetPathInfo(required): string
  Path inside volume where the agent JSON is written.
• targetWorkspaceKey(required): string
  Key of the target workspace where the agent is copied.

{
    "description":"Details to copy the agent to target workspace.",
    "type":"object",
    "properties":{
        "targetDisplayName":{
            "description":"Agent name.",
            "type":"string"
        },
        "targetDescription":{
            "description":"Agent description.",
            "type":"string"
        },
        "targetPathInfo":{
            "description":"Path inside volume where the agent JSON is written.",
            "type":"string"
        },
        "targetWorkspaceKey":{
            "description":"Key of the target workspace where the agent is copied.",
            "type":"string"
        }
    },
    "required":[
        "targetWorkspaceKey",
        "targetPathInfo"
    ]
}

Back to Top

Response

Supported Media Types

• application/json

200 Response

Request accepted. Agent is copied.

Headers

• content-location: string(uri-reference)
  Same as location.
• etag: string
  For optimistic concurrency control. See `if-match`.
• location: string(uri-reference)
  URL for the created Agent. The Agent key is generated after this request is sent.
• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Agent

Type: object

An agent is a sequence of nodes and edges defining an end-to-end agentic application. | A diagram can be composed of multiple nodes, each node being a single agent or a multi-agent system, working independently | or collaboratively to accomplish an overall objective.

Show Source

• agentCardConfig: object AgentCardConfigDetail
  Details of the A2A publish request payload.
• computeKey: string
  Minimum Length: 1

  Maximum Length: 255

  The key of the agent compute associated with this agent.
• createdBy: string
  Minimum Length: 1

  Maximum Length: 255

  The OCID of the user/principal who created the agent.
• dependenciesFilePath: string
  The path to dependencies file.
• deploymentComputeKey: string
  The key of the compute where agent is deployed.
• deploymentMode: string
  Agent deployment mode.
• description(required): string
  Agent description.
• diagram: object AgentDiagram
  Diagrammatic representation of the agent with all node and edge details.
• displayName(required): string
  Agent name.
• entryFilePath: string
  The path to project entry file.
• guardrails: object GuardrailsConfiguration
  Safety guardrails configuration for an Agent.
• key(required): string
  The unique identifier (UUID) of the agent.
• lifecycleDetails: string
  A message that describes the current state of the agent in more detail. For example, can be used to provide actionable information for a resource in the Failed state.
• lifecycleState(required): string
  Allowed Values: [ "DRAFT", "DEPLOYED" ]

  The current state of the agent.
• pathInfo(required): string
  Path inside volume where the agent JSON is written.
• sessionConfig: object SessionConfiguration
  Session configuration for an Agent.
• timeCreated: string(date-time)
  The date and time the agent was created.
• timeUpdated: string(date-time)
  The date and time the agent was updated.
• type: string
  Allowed Values: [ "CANVAS", "CODE" ]

  The type of agent (Canvas or Code).
• updatedBy: string
  Minimum Length: 1

  Maximum Length: 255

  The ID of the user who last updated the schema.
• uri: string
  Agent URI.
• uriState: string
  Agent URI state.
• version: integer
  A number indicating the version of the record. Each time the record is updated, this version will be incremented. This will be used for optimistic locking.
• workspaceKey: string
  The key of the workspace to which this agent belongs.

{
    "description":"An agent is a sequence of nodes and edges defining an end-to-end agentic application. | A diagram can be composed of multiple nodes, each node being a single agent or a multi-agent system, working independently | or collaboratively to accomplish an overall objective.",
    "type":"object",
    "required":[
        "key",
        "displayName",
        "description",
        "lifecycleState",
        "pathInfo"
    ],
    "properties":{
        "key":{
            "description":"The unique identifier (UUID) of the agent.",
            "type":"string"
        },
        "displayName":{
            "description":"Agent name.",
            "type":"string"
        },
        "workspaceKey":{
            "description":"The key of the workspace to which this agent belongs.",
            "type":"string"
        },
        "description":{
            "description":"Agent description.",
            "type":"string"
        },
        "pathInfo":{
            "description":"Path inside volume where the agent JSON is written.",
            "type":"string"
        },
        "type":{
            "description":"The type of agent (Canvas or Code).",
            "type":"string",
            "enum":[
                "CANVAS",
                "CODE"
            ]
        },
        "entryFilePath":{
            "description":"The path to project entry file.",
            "type":"string"
        },
        "dependenciesFilePath":{
            "description":"The path to dependencies file.",
            "type":"string"
        },
        "deploymentComputeKey":{
            "description":"The key of the compute where agent is deployed.",
            "type":"string"
        },
        "deploymentMode":{
            "description":"Agent deployment mode.",
            "type":"string"
        },
        "uri":{
            "description":"Agent URI.",
            "type":"string"
        },
        "uriState":{
            "description":"Agent URI state.",
            "type":"string"
        },
        "lifecycleState":{
            "description":"The current state of the agent.",
            "type":"string",
            "enum":[
                "DRAFT",
                "DEPLOYED"
            ]
        },
        "lifecycleDetails":{
            "description":"A message that describes the current state of the agent in more detail. For example,\ncan be used to provide actionable information for a resource in the Failed state.\n",
            "type":"string"
        },
        "timeCreated":{
            "description":"The date and time the agent was created.",
            "type":"string",
            "format":"date-time"
        },
        "timeUpdated":{
            "description":"The date and time the agent was updated.",
            "type":"string",
            "format":"date-time"
        },
        "createdBy":{
            "description":"The OCID of the user/principal who created the agent.",
            "type":"string",
            "minLength":1,
            "maxLength":255
        },
        "updatedBy":{
            "description":"The ID of the user who last updated the schema.",
            "type":"string",
            "minLength":1,
            "maxLength":255
        },
        "computeKey":{
            "description":"The key of the agent compute associated with this agent.",
            "type":"string",
            "minLength":1,
            "maxLength":255
        },
        "diagram":{
            "$ref":"#/definitions/AgentDiagram"
        },
        "guardrails":{
            "$ref":"#/definitions/GuardrailsConfiguration"
        },
        "sessionConfig":{
            "$ref":"#/definitions/SessionConfiguration"
        },
        "agentCardConfig":{
            "$ref":"#/definitions/AgentCardConfigDetail"
        },
        "version":{
            "description":"A number indicating the version of the record. Each time the record is updated, this version will be incremented. This will be used for optimistic locking.",
            "type":"integer"
        }
    }
}

Nested Schema : AgentCardConfigDetail

Type: object

Details of the A2A publish request payload.

Show Source

• capabilities: object AgentCardCapabilitiesDetail
  Capabilities included in publish request.
• description: string
  Maximum Length: 1048576

  Human-readable agent description.
• documentationUrl: string
  Documentation URL for the agent. Serialized as `documentation_url`.
• name(required): string
  Minimum Length: 1

  Maximum Length: 255

  Human-readable agent name.
• provider: object AgentProvider
  Service provider information for an agent.
• skills: array skills
  List of skills supported by the agent.
• version: string
  Agent version string.

{
    "description":"Details of the A2A publish request payload.",
    "type":"object",
    "required":[
        "name"
    ],
    "properties":{
        "name":{
            "type":"string",
            "description":"Human-readable agent name.",
            "minLength":1,
            "maxLength":255
        },
        "description":{
            "type":"string",
            "description":"Human-readable agent description.",
            "maxLength":1048576
        },
        "skills":{
            "type":"array",
            "description":"List of skills supported by the agent.",
            "items":{
                "$ref":"#/definitions/AgentCardSkillDetail"
            }
        },
        "capabilities":{
            "$ref":"#/definitions/AgentCardCapabilitiesDetail"
        },
        "version":{
            "type":"string",
            "description":"Agent version string."
        },
        "provider":{
            "$ref":"#/definitions/AgentProvider"
        },
        "documentationUrl":{
            "type":"string",
            "description":"Documentation URL for the agent. Serialized as `documentation_url`."
        }
    }
}

Nested Schema : AgentDiagram

Type: object

Diagrammatic representation of the agent with all node and edge details.

Show Source

• description: string
  Agent description.
• displayName: string
  Agent name.
• edges: object edges
  Additional Properties Allowed: AgentEdge

  Mapping of edgeId to edge objects.
• guardrailsMap: object guardrailsMap
  Additional Properties Allowed: GuardrailsConfiguration

  A hash map with key=guardrails config key, value=guardrails definition. It is used to find the guardrails definition for a guardrails reference by name.
• key: string
  The unique identifier (UUID) of the agent.
• modelVersion: string
  The model and upgrade compatibility version for this agent diagram.
• nodes: object nodes
  Additional Properties Allowed: AgentDiagramNode

  Mapping of nodeId to node objects.
• toolsMap: object toolsMap
  Additional Properties Allowed: Tool

  A hash map with key=tool key, value=tool definition. It is used to find the tool definition for a tool reference, where the tool is marked as a reference.

{
    "description":"Diagrammatic representation of the agent with all node and edge details.",
    "properties":{
        "key":{
            "description":"The unique identifier (UUID) of the agent.",
            "type":"string"
        },
        "displayName":{
            "description":"Agent name.",
            "type":"string"
        },
        "description":{
            "description":"Agent description.",
            "type":"string"
        },
        "modelVersion":{
            "description":"The model and upgrade compatibility version for this agent diagram.",
            "type":"string"
        },
        "nodes":{
            "description":"Mapping of nodeId to node objects.",
            "type":"object",
            "additionalProperties":{
                "$ref":"#/definitions/AgentDiagramNode"
            },
            "default":{
            }
        },
        "edges":{
            "description":"Mapping of edgeId to edge objects.",
            "type":"object",
            "additionalProperties":{
                "$ref":"#/definitions/AgentEdge"
            },
            "default":{
            }
        },
        "toolsMap":{
            "description":"A hash map with key=tool key, value=tool definition. It is used to find the tool definition for a tool reference, where the tool is marked as a reference.",
            "type":"object",
            "additionalProperties":{
                "$ref":"#/definitions/Tool"
            }
        },
        "guardrailsMap":{
            "description":"A hash map with key=guardrails config key, value=guardrails definition. It is used to find the guardrails definition for a guardrails reference by name.",
            "type":"object",
            "additionalProperties":{
                "$ref":"#/definitions/GuardrailsConfiguration"
            }
        }
    }
}

Nested Schema : GuardrailsConfiguration

Type: object

Safety guardrails configuration for an Agent.

Show Source

• description: string
  Maximum Length: 1000

  Description of the guardrails configuration
• key: string
  The unique identifier (UUID) of the guardrails configuration.
• name: string
  Maximum Length: 255

  Name of the guardrails configuration
• policies: array policies
  List of safety policies configured in this guardrails

{
    "description":"Safety guardrails configuration for an Agent.",
    "type":"object",
    "properties":{
        "key":{
            "description":"The unique identifier (UUID) of the guardrails configuration.",
            "type":"string"
        },
        "name":{
            "description":"Name of the guardrails configuration",
            "type":"string",
            "maxLength":255
        },
        "description":{
            "description":"Description of the guardrails configuration",
            "type":"string",
            "maxLength":1000
        },
        "policies":{
            "description":"List of safety policies configured in this guardrails",
            "type":"array",
            "items":{
                "$ref":"#/definitions/SafetyPolicy"
            }
        }
    }
}

Nested Schema : SessionConfiguration

Type: object

Session configuration for an Agent.

Show Source

• sessionRetentionConfig: object SessionRetentionConfiguration
  Session data retention configuration for an Agent.
• variables: object variables
  Additional Properties Allowed: SessionVariableDetails

  Map of session variable name to variable definition.

{
    "description":"Session configuration for an Agent.",
    "type":"object",
    "properties":{
        "variables":{
            "description":"Map of session variable name to variable definition.",
            "type":"object",
            "additionalProperties":{
                "$ref":"#/definitions/SessionVariableDetails"
            },
            "default":{
            }
        },
        "sessionRetentionConfig":{
            "$ref":"#/definitions/SessionRetentionConfiguration"
        }
    }
}

Nested Schema : AgentCardCapabilitiesDetail

Type: object

Capabilities included in publish request.

Show Source

• isStreaming: boolean
  Indicates whether streaming responses are supported.

{
    "description":"Capabilities included in publish request.",
    "type":"object",
    "properties":{
        "isStreaming":{
            "type":"boolean",
            "description":"Indicates whether streaming responses are supported."
        }
    }
}

Nested Schema : AgentProvider

Type: object

Service provider information for an agent.

Show Source

• organization: string
  The name of the agent provider's organization.
• url: string
  A URL for the agent provider's website or documentation.

{
    "description":"Service provider information for an agent.",
    "type":"object",
    "properties":{
        "organization":{
            "type":"string",
            "description":"The name of the agent provider's organization."
        },
        "url":{
            "type":"string",
            "description":"A URL for the agent provider's website or documentation."
        }
    }
}

Nested Schema : skills

Type: array

List of skills supported by the agent.

Show Source

• Array of: object AgentCardSkillDetail
  A single skill in the publish request.

{
    "type":"array",
    "description":"List of skills supported by the agent.",
    "items":{
        "$ref":"#/definitions/AgentCardSkillDetail"
    }
}

Nested Schema : AgentCardSkillDetail

Type: object

A single skill in the publish request.

Show Source

• description: string
  Maximum Length: 1048576

  Description of what the skill does.
• examples: array examples
  Optional example prompts for this skill.
• id(required): string
  Minimum Length: 1

  Maximum Length: 255

  Unique skill identifier.
• name(required): string
  Minimum Length: 1

  Maximum Length: 255

  Display name of the skill.
• tags: array tags
  Optional tags for categorization/search.

{
    "description":"A single skill in the publish request.",
    "type":"object",
    "required":[
        "id",
        "name"
    ],
    "properties":{
        "id":{
            "type":"string",
            "description":"Unique skill identifier.",
            "minLength":1,
            "maxLength":255
        },
        "name":{
            "type":"string",
            "description":"Display name of the skill.",
            "minLength":1,
            "maxLength":255
        },
        "description":{
            "type":"string",
            "description":"Description of what the skill does.",
            "maxLength":1048576
        },
        "tags":{
            "type":"array",
            "description":"Optional tags for categorization/search.",
            "items":{
                "type":"string",
                "minLength":1,
                "maxLength":255
            }
        },
        "examples":{
            "type":"array",
            "description":"Optional example prompts for this skill.",
            "items":{
                "type":"string",
                "minLength":1,
                "maxLength":1048576
            }
        }
    }
}

Nested Schema : examples

Type: array

Optional example prompts for this skill.

Show Source

• Array of: string
  Minimum Length: 1

  Maximum Length: 1048576

{
    "type":"array",
    "description":"Optional example prompts for this skill.",
    "items":{
        "type":"string",
        "minLength":1,
        "maxLength":1048576
    }
}

Nested Schema : tags

Type: array

Optional tags for categorization/search.

Show Source

• Array of: string
  Minimum Length: 1

  Maximum Length: 255

{
    "type":"array",
    "description":"Optional tags for categorization/search.",
    "items":{
        "type":"string",
        "minLength":1,
        "maxLength":255
    }
}

Nested Schema : edges

Type: object

Additional Properties Allowed

Show Source

• object AgentEdge
  An edge connecting two nodes in the diagram, with context and metadata.

{
    "description":"Mapping of edgeId to edge objects.",
    "type":"object",
    "additionalProperties":{
        "$ref":"#/definitions/AgentEdge"
    },
    "default":{
    }
}

Mapping of edgeId to edge objects.

Default Value: { }

Nested Schema : guardrailsMap

Type: object

Additional Properties Allowed

Show Source

• object GuardrailsConfiguration
  Safety guardrails configuration for an Agent.

{
    "description":"A hash map with key=guardrails config key, value=guardrails definition. It is used to find the guardrails definition for a guardrails reference by name.",
    "type":"object",
    "additionalProperties":{
        "$ref":"#/definitions/GuardrailsConfiguration"
    }
}

A hash map with key=guardrails config key, value=guardrails definition. It is used to find the guardrails definition for a guardrails reference by name.

Nested Schema : nodes

Type: object

Additional Properties Allowed

Show Source

• object AgentDiagramNode
  Discriminator: type

  A node in a diagram, representing logic, data, or operation.

{
    "description":"Mapping of nodeId to node objects.",
    "type":"object",
    "additionalProperties":{
        "$ref":"#/definitions/AgentDiagramNode"
    },
    "default":{
    }
}

Mapping of nodeId to node objects.

Default Value: { }

Nested Schema : toolsMap

Type: object

Additional Properties Allowed

Show Source

• object Tool
  Discriminator: toolType

  A tool is a function that an agent can call. Tools can retrieve data, call external APIs, HTTP endpoints, execute a snippet of code, entire Python scripts, etc. | A tool is stateless, doesn't reason (it just executes), and can be reused across agents.

{
    "description":"A hash map with key=tool key, value=tool definition. It is used to find the tool definition for a tool reference, where the tool is marked as a reference.",
    "type":"object",
    "additionalProperties":{
        "$ref":"#/definitions/Tool"
    }
}

A hash map with key=tool key, value=tool definition. It is used to find the tool definition for a tool reference, where the tool is marked as a reference.

Nested Schema : AgentEdge

Type: object

An edge connecting two nodes in the diagram, with context and metadata.

Show Source

• destNodeId(required): string
  Destination node for this edge.
• destNodeInput(required): string
  Input port on the destination node.
• edgeHandles: array edgeHandles
  Geometry handle coordinates.
• edgeProperties: object edgeProperties
  Additional Properties Allowed: additionalProperties

  Extensible properties of the edge.
• edgeType: string
  Style/type for edge.
• key(required): string
  Unique edge identifier.
• parentNodeId: string
  Parent node, if hierarchical.
• srcNodeId(required): string
  Source node for this edge.
• srcNodeOutput(required): string
  Output port on the source node.
• timeCreated: string(date-time)
  Default Value: 2024-12-11T22:41:25.622463Z

  RFC3339 timestamp when edge was created.
• timeUpdated: string(date-time)
  Default Value: 2024-12-11T22:41:25.622470Z

  RFC3339 timestamp when edge was last updated.
• validationErrors: array validationErrors
  List of validation errors encountered in the diagram.

{
    "description":"An edge connecting two nodes in the diagram, with context and metadata.",
    "type":"object",
    "properties":{
        "srcNodeId":{
            "description":"Source node for this edge.",
            "type":"string"
        },
        "destNodeId":{
            "description":"Destination node for this edge.",
            "type":"string"
        },
        "srcNodeOutput":{
            "description":"Output port on the source node.",
            "type":"string"
        },
        "destNodeInput":{
            "description":"Input port on the destination node.",
            "type":"string"
        },
        "parentNodeId":{
            "description":"Parent node, if hierarchical.",
            "type":"string"
        },
        "edgeHandles":{
            "description":"Geometry handle coordinates.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/Point"
            },
            "default":[
            ]
        },
        "edgeProperties":{
            "description":"Extensible properties of the edge.",
            "type":"object",
            "additionalProperties":{
                "type":"object"
            }
        },
        "edgeType":{
            "description":"Style/type for edge.",
            "type":"string"
        },
        "key":{
            "description":"Unique edge identifier.",
            "type":"string"
        },
        "timeCreated":{
            "description":"RFC3339 timestamp when edge was created.",
            "type":"string",
            "format":"date-time",
            "default":"2024-12-11T22:41:25.622463Z"
        },
        "timeUpdated":{
            "description":"RFC3339 timestamp when edge was last updated.",
            "type":"string",
            "format":"date-time",
            "default":"2024-12-11T22:41:25.622470Z"
        },
        "validationErrors":{
            "description":"List of validation errors encountered in the diagram.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/ValidationError"
            }
        }
    },
    "required":[
        "srcNodeId",
        "destNodeId",
        "srcNodeOutput",
        "destNodeInput",
        "key"
    ]
}

Nested Schema : edgeHandles

Type: array

Geometry handle coordinates.

Show Source

• Array of: object Point
  A 2D point for edge handles on diagram elements.

{
    "description":"Geometry handle coordinates.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/Point"
    },
    "default":[
    ]
}

Nested Schema : edgeProperties

Type: object

Additional Properties Allowed

Show Source

• object additionalProperties

{
    "description":"Extensible properties of the edge.",
    "type":"object",
    "additionalProperties":{
        "type":"object"
    }
}

Extensible properties of the edge.

Nested Schema : validationErrors

Type: array

List of validation errors encountered in the diagram.

Show Source

• Array of: object ValidationError
  Validation error for a component in agent diagram.

{
    "description":"List of validation errors encountered in the diagram.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/ValidationError"
    }
}

Nested Schema : Point

Type: object

A 2D point for edge handles on diagram elements.

Show Source

• x(required): number(float)
  X coordinate.
• y(required): number(float)
  Y coordinate.

{
    "description":"A 2D point for edge handles on diagram elements.",
    "type":"object",
    "properties":{
        "x":{
            "description":"X coordinate.",
            "type":"number",
            "format":"float"
        },
        "y":{
            "description":"Y coordinate.",
            "type":"number",
            "format":"float"
        }
    },
    "required":[
        "x",
        "y"
    ]
}

Nested Schema : additionalProperties

Type: object

Nested Schema : ValidationError

Type: object

Validation error for a component in agent diagram.

Show Source

• key(required): string
  Id of the component that caused the error
• message(required): string
  Error message.
• name(required): string
  Error name
• type(required): string
  Type of error.

{
    "description":"Validation error for a component in agent diagram.",
    "type":"object",
    "properties":{
        "type":{
            "description":"Type of error.",
            "type":"string"
        },
        "message":{
            "description":"Error message.",
            "type":"string"
        },
        "name":{
            "description":"Error name",
            "type":"string"
        },
        "key":{
            "description":"Id of the component that caused the error",
            "type":"string"
        }
    },
    "required":[
        "type",
        "message",
        "name",
        "key"
    ]
}

Nested Schema : AgentDiagramNode

Type: object

Discriminator: type

A node in a diagram, representing logic, data, or operation.

Show Source

• configuration: object configuration
  Additional Properties Allowed: additionalProperties

  Configuration object for this node.
• description: string
  Default Value: New node

  Description of this node.
• inputs: array inputs
  Array of NodeInput objects.
• isExpanded: boolean
  Default Value: false

  Is node expanded in UI.
• key(required): string
  Unique identifier for the node.
• name: string
  Default Value: New node

  Name of this node.
• nodeType: string
  This field is deprecated. | It does not need to be set to any value for API calls.
• nodeTypeId: string
  Definition ID for this node type.
• outputs: array outputs
  Array of NodeOutput objects.
• parentNodeId: string
  Parent node ID, for subgraphs.
• positionX: number(float)
  Default Value: 0

  Canvas X coordinate.
• positionY: number(float)
  Default Value: 0

  Canvas Y coordinate.
• timeCreated: string(date-time)
  Default Value: 2024-12-11T22:41:25.967777Z

  RFC3339 timestamp when node was created.
• timeUpdated: string(date-time)
  Default Value: 2024-12-11T22:41:25.967783Z

  RFC3339 timestamp when node was last updated.
• type: string
  Allowed Values: [ "START_NODE", "GUARDRAILS", "AGENT", "SUPERVISOR_AGENT", "SQL_TOOL", "PROMPT_TOOL", "RAG_TOOL", "MCP_TOOL", "HTTP_TOOL", "CUSTOM_TOOL" ]

  Node type discriminator.
• validationErrors: array validationErrors
  List of validation errors encountered in the diagram.

{
    "description":"A node in a diagram, representing logic, data, or operation.",
    "type":"object",
    "discriminator":"type",
    "properties":{
        "type":{
            "description":"Node type discriminator.",
            "type":"string",
            "x-obmcs-top-level-enum":"#/definitions/NodeType",
            "enum":[
                "START_NODE",
                "GUARDRAILS",
                "AGENT",
                "SUPERVISOR_AGENT",
                "SQL_TOOL",
                "PROMPT_TOOL",
                "RAG_TOOL",
                "MCP_TOOL",
                "HTTP_TOOL",
                "CUSTOM_TOOL"
            ]
        },
        "nodeType":{
            "description":"This field is deprecated. | It does not need to be set to any value for API calls.",
            "type":"string"
        },
        "name":{
            "description":"Name of this node.",
            "type":"string",
            "default":"New node"
        },
        "description":{
            "description":"Description of this node.",
            "type":"string",
            "default":"New node"
        },
        "positionX":{
            "description":"Canvas X coordinate.",
            "type":"number",
            "format":"float",
            "default":0
        },
        "positionY":{
            "description":"Canvas Y coordinate.",
            "type":"number",
            "format":"float",
            "default":0
        },
        "isExpanded":{
            "description":"Is node expanded in UI.",
            "type":"boolean",
            "default":false
        },
        "parentNodeId":{
            "description":"Parent node ID, for subgraphs.",
            "type":"string"
        },
        "configuration":{
            "description":"Configuration object for this node.",
            "type":"object",
            "default":{
            },
            "additionalProperties":{
                "type":"object",
                "default":{
                }
            }
        },
        "nodeTypeId":{
            "description":"Definition ID for this node type.",
            "type":"string"
        },
        "key":{
            "description":"Unique identifier for the node.",
            "type":"string"
        },
        "timeCreated":{
            "description":"RFC3339 timestamp when node was created.",
            "type":"string",
            "format":"date-time",
            "default":"2024-12-11T22:41:25.967777Z"
        },
        "timeUpdated":{
            "description":"RFC3339 timestamp when node was last updated.",
            "type":"string",
            "format":"date-time",
            "default":"2024-12-11T22:41:25.967783Z"
        },
        "inputs":{
            "description":"Array of NodeInput objects.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/NodeInput"
            },
            "default":[
            ]
        },
        "outputs":{
            "description":"Array of NodeOutput objects.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/NodeOutput"
            },
            "default":[
            ]
        },
        "validationErrors":{
            "description":"List of validation errors encountered in the diagram.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/ValidationError"
            }
        }
    },
    "required":[
        "key"
    ]
}

Nested Schema : configuration

Type: object

Additional Properties Allowed

Show Source

• object additionalProperties

{
    "description":"Configuration object for this node.",
    "type":"object",
    "default":{
    },
    "additionalProperties":{
        "type":"object",
        "default":{
        }
    }
}

Configuration object for this node.

Default Value: { }

Nested Schema : inputs

Type: array

Array of NodeInput objects.

Show Source

• Array of: object NodeInput
  An input slot for a node, including type and requirements.

{
    "description":"Array of NodeInput objects.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/NodeInput"
    },
    "default":[
    ]
}

Nested Schema : outputs

Type: array

Array of NodeOutput objects.

Show Source

• Array of: object NodeOutput
  An output slot for a node, including type and requirements.

{
    "description":"Array of NodeOutput objects.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/NodeOutput"
    },
    "default":[
    ]
}

Nested Schema : validationErrors

Type: array

List of validation errors encountered in the diagram.

Show Source

• Array of: object ValidationError
  Validation error for a component in agent diagram.

{
    "description":"List of validation errors encountered in the diagram.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/ValidationError"
    }
}

Nested Schema : additionalProperties

Type: object

Default Value: { }

Nested Schema : NodeInput

Type: object

An input slot for a node, including type and requirements.

Show Source

• description: string
  Documentation or tooltip shown in the UI.
• isRequired(required): boolean
  True if this input is mandatory.
• isSingleConnection: boolean
  Default Value: false

  True if only one connection is allowed; false allows multiple.
• name(required): string
  Unique name for the input slot.
• portPosition: string
  Allowed Values: [ "TOP", "BOTTOM", "RIGHT", "LEFT" ]

  UI position of the input port on the node.
• type(required): object NodeIo
  Defines the data type and color for an input or output.

{
    "description":"An input slot for a node, including type and requirements.",
    "type":"object",
    "properties":{
        "name":{
            "description":"Unique name for the input slot.",
            "type":"string"
        },
        "type":{
            "$ref":"#/definitions/NodeIo"
        },
        "portPosition":{
            "description":"UI position of the input port on the node.",
            "type":"string",
            "x-obmcs-top-level-enum":"#/definitions/NodePortPosition",
            "enum":[
                "TOP",
                "BOTTOM",
                "RIGHT",
                "LEFT"
            ]
        },
        "description":{
            "description":"Documentation or tooltip shown in the UI.",
            "type":"string"
        },
        "isRequired":{
            "description":"True if this input is mandatory.",
            "type":"boolean"
        },
        "isSingleConnection":{
            "description":"True if only one connection is allowed; false allows multiple.",
            "type":"boolean",
            "default":false
        }
    },
    "required":[
        "name",
        "type",
        "isRequired"
    ]
}

Nested Schema : NodeIo

Type: object

Defines the data type and color for an input or output.

Show Source

• color(required): object NodeIoColor
  Text and background color configuration for a node input/output.
• dataType(required): string
  Allowed Values: [ "FLOW", "STR", "INT", "BOOL", "FLOAT", "LIST", "DICT", "ANY", "TOOLS", "LLMS", "AGENTS", "PLANNER", "FLOWS" ]

  Possible types of node inputs and outputs.

{
    "description":"Defines the data type and color for an input or output.",
    "type":"object",
    "properties":{
        "dataType":{
            "description":"Possible types of node inputs and outputs.",
            "type":"string",
            "enum":[
                "FLOW",
                "STR",
                "INT",
                "BOOL",
                "FLOAT",
                "LIST",
                "DICT",
                "ANY",
                "TOOLS",
                "LLMS",
                "AGENTS",
                "PLANNER",
                "FLOWS"
            ]
        },
        "color":{
            "$ref":"#/definitions/NodeIoColor"
        }
    },
    "required":[
        "dataType",
        "color"
    ]
}

Nested Schema : NodeIoColor

Type: object

Text and background color configuration for a node input/output.

Show Source

• backgroundColor(required): string
  Input/output badge background color.
• handleColor(required): string
  Input/output connector handle color.
• textColor(required): string
  Allowed Values: [ "DARK", "LIGHT" ]

  Whether the text on badges should be dark or light for visibility.

{
    "description":"Text and background color configuration for a node input/output.",
    "type":"object",
    "properties":{
        "textColor":{
            "description":"Whether the text on badges should be dark or light for visibility.",
            "type":"string",
            "enum":[
                "DARK",
                "LIGHT"
            ]
        },
        "backgroundColor":{
            "description":"Input/output badge background color.",
            "type":"string"
        },
        "handleColor":{
            "description":"Input/output connector handle color.",
            "type":"string"
        }
    },
    "required":[
        "textColor",
        "backgroundColor",
        "handleColor"
    ]
}

Nested Schema : NodeOutput

Type: object

An output slot for a node, including type and requirements.

Show Source

• description: string
  Documentation or tooltip shown in the UI.
• isRequired(required): boolean
  True if this output is mandatory.
• name(required): string
  Unique name for the output slot.
• portPosition: string
  Allowed Values: [ "TOP", "BOTTOM", "RIGHT", "LEFT" ]

  UI position of the output port on the node.
• type(required): object NodeIo
  Defines the data type and color for an input or output.

{
    "description":"An output slot for a node, including type and requirements.",
    "type":"object",
    "properties":{
        "name":{
            "description":"Unique name for the output slot.",
            "type":"string"
        },
        "type":{
            "$ref":"#/definitions/NodeIo"
        },
        "portPosition":{
            "description":"UI position of the output port on the node.",
            "type":"string",
            "x-obmcs-top-level-enum":"#/definitions/NodePortPosition",
            "enum":[
                "TOP",
                "BOTTOM",
                "RIGHT",
                "LEFT"
            ]
        },
        "description":{
            "description":"Documentation or tooltip shown in the UI.",
            "type":"string"
        },
        "isRequired":{
            "description":"True if this output is mandatory.",
            "type":"boolean"
        }
    },
    "required":[
        "name",
        "type",
        "isRequired"
    ]
}

Nested Schema : Tool

Type: object

Discriminator: toolType

A tool is a function that an agent can call. Tools can retrieve data, call external APIs, HTTP endpoints, execute a snippet of code, entire Python scripts, etc. | A tool is stateless, doesn't reason (it just executes), and can be reused across agents.

Show Source

• createdBy: string
  Minimum Length: 1

  Maximum Length: 255

  The OCID of the user/principal who created the tool.
• description: string
  Tool description.
• displayName: string
  Tool name.
• key: string
  The unique identifier of the tool
• positionX: number(float)
  Default Value: 0

  Canvas X coordinate of the Tool node
• positionY: number(float)
  Default Value: 0

  Canvas Y coordinate of the Tool node
• properties: object properties
  Additional Properties Allowed: additionalProperties

  A list of key-value pairs to use for configuring the tool
• timeCreated: string(date-time)
  The date and time the tool was created.
• timeUpdated: string(date-time)
  The date and time the tool was updated.
• toolType: string
  Allowed Values: [ "RAG", "SQL", "PROMPT", "NL2SQL", "MCP", "CUSTOM", "HTTP" ]

  Type of tool. Managed, external or mount tool.
• updatedBy: string
  Minimum Length: 1

  Maximum Length: 255

  The ID of the user who last updated the schema.
• workspaceKey: string
  The key of the Workspace to which this tool belongs.

{
    "description":"A tool is a function that an agent can call. Tools can retrieve data, call external APIs, HTTP endpoints, execute a snippet of code, entire Python scripts, etc. | A tool is stateless, doesn't reason  (it just executes), and can be reused across agents.",
    "type":"object",
    "discriminator":"toolType",
    "properties":{
        "key":{
            "description":"The unique identifier of the tool",
            "type":"string"
        },
        "displayName":{
            "description":"Tool name.",
            "type":"string"
        },
        "workspaceKey":{
            "description":"The key of the Workspace to which this tool belongs.",
            "type":"string"
        },
        "description":{
            "description":"Tool description.",
            "type":"string"
        },
        "toolType":{
            "description":"Type of tool. Managed, external or mount tool.",
            "type":"string",
            "x-obmcs-top-level-enum":"#/definitions/ToolType",
            "enum":[
                "RAG",
                "SQL",
                "PROMPT",
                "NL2SQL",
                "MCP",
                "CUSTOM",
                "HTTP"
            ]
        },
        "positionX":{
            "description":"Canvas X coordinate of the Tool node",
            "type":"number",
            "format":"float",
            "default":0
        },
        "positionY":{
            "description":"Canvas Y coordinate of the Tool node",
            "type":"number",
            "format":"float",
            "default":0
        },
        "properties":{
            "description":"A list of key-value pairs to use for configuring the tool",
            "type":"object",
            "additionalProperties":{
                "type":"object"
            }
        },
        "timeCreated":{
            "description":"The date and time the tool was created.",
            "type":"string",
            "format":"date-time"
        },
        "timeUpdated":{
            "description":"The date and time the tool was updated.",
            "type":"string",
            "format":"date-time"
        },
        "createdBy":{
            "description":"The OCID of the user/principal who created the tool.",
            "type":"string",
            "minLength":1,
            "maxLength":255
        },
        "updatedBy":{
            "description":"The ID of the user who last updated the schema.",
            "type":"string",
            "minLength":1,
            "maxLength":255
        }
    }
}

Nested Schema : properties

Type: object

Additional Properties Allowed

Show Source

• object additionalProperties

{
    "description":"A list of key-value pairs to use for configuring the tool",
    "type":"object",
    "additionalProperties":{
        "type":"object"
    }
}

A list of key-value pairs to use for configuring the tool

Nested Schema : additionalProperties

Type: object

Nested Schema : policies

Type: array

List of safety policies configured in this guardrails

Show Source

• Array of: object SafetyPolicy
  Discriminator: policyType

  Individual safety policy configuration.

{
    "description":"List of safety policies configured in this guardrails",
    "type":"array",
    "items":{
        "$ref":"#/definitions/SafetyPolicy"
    }
}

Nested Schema : SafetyPolicy

Type: object

Discriminator: policyType

Individual safety policy configuration.

Show Source

• action(required): string
  Allowed Values: [ "BLOCK", "INFORM", "MASK" ]

  Action to take when policy is violated.
• policyDescription: string
  Maximum Length: 1000

  Description of the policy.
• policyName: string
  Maximum Length: 255

  Custom name for the policy.
• policyType(required): string
  Allowed Values: [ "CONTENT_MODERATION", "PROMPT_ATTACKS_PREVENTION", "PII_DETECTION", "DENIED_TOPICS", "WORD_FILTERS", "CONTEXTUAL_GROUNDING", "CUSTOM_POLICY" ]

  Type of safety policy.
• scope(required): string
  Allowed Values: [ "USER_REQUEST", "AGENT_RESPONSE", "BOTH" ]

  Scope of policy application.
• threshold: number(float)
  Minimum Value: 0

  Maximum Value: 1

  Default Value: 0.5

  Threshold value for policy violation (0.0 to 1.0).

{
    "description":"Individual safety policy configuration.",
    "type":"object",
    "discriminator":"policyType",
    "required":[
        "policyType",
        "scope",
        "action"
    ],
    "properties":{
        "policyType":{
            "description":"Type of safety policy.",
            "type":"string",
            "x-obmcs-top-level-enum":"#/definitions/PolicyType",
            "enum":[
                "CONTENT_MODERATION",
                "PROMPT_ATTACKS_PREVENTION",
                "PII_DETECTION",
                "DENIED_TOPICS",
                "WORD_FILTERS",
                "CONTEXTUAL_GROUNDING",
                "CUSTOM_POLICY"
            ]
        },
        "policyName":{
            "description":"Custom name for the policy.",
            "type":"string",
            "maxLength":255
        },
        "policyDescription":{
            "description":"Description of the policy.",
            "type":"string",
            "maxLength":1000
        },
        "scope":{
            "description":"Scope of policy application.",
            "type":"string",
            "x-obmcs-top-level-enum":"#/definitions/PolicyScope",
            "enum":[
                "USER_REQUEST",
                "AGENT_RESPONSE",
                "BOTH"
            ]
        },
        "action":{
            "description":"Action to take when policy is violated.",
            "type":"string",
            "x-obmcs-top-level-enum":"#/definitions/PolicyAction",
            "enum":[
                "BLOCK",
                "INFORM",
                "MASK"
            ]
        },
        "threshold":{
            "description":"Threshold value for policy violation (0.0 to 1.0).",
            "type":"number",
            "format":"float",
            "minimum":0,
            "maximum":1,
            "default":0.5
        }
    }
}

Nested Schema : SessionRetentionConfiguration

Type: object

Session data retention configuration for an Agent.

Show Source

• retentionPeriodInDays: integer
  Minimum Value: 1

  No. of days session data will be kept
• sessionSizeLimit: integer
  Minimum Value: 1

  Max storage allocated to session data (in MB).
• threadCountLimit: integer
  Minimum Value: 1

  Maximum no. of user prompt and agent response pairs per session

{
    "description":"Session data retention configuration for an Agent.",
    "type":"object",
    "properties":{
        "retentionPeriodInDays":{
            "description":"No. of days session data will be kept",
            "type":"integer",
            "minimum":1
        },
        "sessionSizeLimit":{
            "description":"Max storage allocated to session data (in MB).",
            "type":"integer",
            "minimum":1
        },
        "threadCountLimit":{
            "description":"Maximum no. of user prompt and agent response pairs per session",
            "type":"integer",
            "minimum":1
        }
    }
}

Nested Schema : variables

Type: object

Additional Properties Allowed

Show Source

• object SessionVariableDetails
  Session Variable Details.

{
    "description":"Map of session variable name to variable definition.",
    "type":"object",
    "additionalProperties":{
        "$ref":"#/definitions/SessionVariableDetails"
    },
    "default":{
    }
}

Map of session variable name to variable definition.

Default Value: { }

Nested Schema : SessionVariableDetails

Type: object

Session Variable Details.

Show Source

• description: string
  Description of the Session Variable
• isRequired: boolean
  Default Value: false

  If this Variable is required or not
• isSystem: boolean
  Default Value: false

  True if Session Variable is defined by System
• name(required): string
  Name of the Session Variable.
• shouldLog: boolean
  Default Value: true

  If we should log this Session Variable or not
• value: string
  Default Value of this Session Variable

{
    "description":"Session Variable Details.",
    "type":"object",
    "required":[
        "name"
    ],
    "properties":{
        "name":{
            "description":"Name of the Session Variable.",
            "type":"string"
        },
        "description":{
            "description":"Description of the Session Variable",
            "type":"string"
        },
        "isRequired":{
            "description":"If this Variable is required or not",
            "type":"boolean",
            "default":false
        },
        "shouldLog":{
            "description":"If we should log this Session Variable or not",
            "type":"boolean",
            "default":true
        },
        "isSystem":{
            "description":"True if Session Variable is defined by System",
            "type":"boolean",
            "default":false
        },
        "value":{
            "description":"Default Value of this Session Variable",
            "type":"string"
        }
    }
}

400 Response

Bad Request (invalid query parameters, malformed headers, and so on).

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

401 Response

Unauthorized (missing or expired credentials, and so on).

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

404 Response

Not Found. The requested resource was not found.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

409 Response

Conflict. Request conflicts with the current state of the resource.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

412 Response

Precondition Failed (One or more conditions in request failed).

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

429 Response

Too Many Requests. Too many requests sent to the server in a short period.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

500 Response

Internal Server Error. The server encountered an unexpected condition preventing fulfilment of the request.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

Default Response

Unknown Error. Error is not recognized by the system.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

Back to Top