gen-ai docs 2nd attempt #961
Conversation
specification/resources/gen-ai/GenAIAPI_CancelKnowledgeBaseIndexingJobPublic.yml
Outdated
Show resolved
Hide resolved
specification/resources/gen-ai/GenAIAPI_CreateAgentAPIKeyPublic.yml
Outdated
Show resolved
Hide resolved
specification/resources/gen-ai/GenAIAPI_CreateKnowledgeBaseDataSourcePublic.yml
Outdated
Show resolved
Hide resolved
specification/resources/gen-ai/GenAIAPI_DeleteAgentAPIKeyPublic.yml
Outdated
Show resolved
Hide resolved
specification/resources/gen-ai/GenAIAPI_GetKnowledgeBaseIndexingJobPublic.yml
Outdated
Show resolved
Hide resolved
specification/resources/gen-ai/GenAIAPI_GetKnowledgeBasePublic.yml
Outdated
Show resolved
Hide resolved
specification/resources/gen-ai/GenAIAPI_LinkAgentFunctionPublic.yml
Outdated
Show resolved
Hide resolved
| This endpoint allows developers to link agent funciton. | ||
| operationId: GenAIAPI_LinkAgentFunctionPublic | ||
| parameters: | ||
| - description: agnet id |
specification/resources/gen-ai/GenAIAPI_LinkAgentFunctionPublic.yml
Outdated
Show resolved
Hide resolved
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: link agent. |
| description: |- | ||
| post /v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid} | ||
|
|
||
| This endpoint allows developers to link knowledge base. |
There was a problem hiding this comment.
I dont understand this one. I'm assuming this means attaching a knowledge base to an agent? If yes, then
This endpoint allows developers to attach a knowledge base to an agent.
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: link knowledge base. |
| description: |- | ||
| get /v2/gen-ai/agents | ||
|
|
||
| This endpoint allows developers to returns a list of agents specific to the users context. |
There was a problem hiding this comment.
This endpoint allows developers to return a list of agents specific to the user's context.
There was a problem hiding this comment.
I think this is "This endpoint returns a list of all agents." ??
| description: |- | ||
| get /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources | ||
|
|
||
| This endpoint allows developers to list knowledge base data source. |
There was a problem hiding this comment.
This endpoint allows developers to list knowledge base data sources.
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: list knowledge base data source. |
| description: |- | ||
| get /v2/gen-ai/knowledge_bases | ||
|
|
||
| This endpoint allows developers to provides a list of knowledge bases for the user context. |
There was a problem hiding this comment.
This endpoint allows developers to provide a list of knowledge bases for the user context.
I don't undrstand what "for the user context" means - can you explain?
There was a problem hiding this comment.
I think this is "This endpoint returns a list of all knowledge bases." ??
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: list models. |
| description: |- | ||
| put /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}/regenerate | ||
|
|
||
| This endpoint allows developers to regenerate agent api key. |
There was a problem hiding this comment.
This endpoint allows developers to regenerate an agent api key.
| description: |- | ||
| post /v2/gen-ai/indexing_jobs | ||
|
|
||
| This endpoint allows developers to start knowledge base indexing job. |
There was a problem hiding this comment.
to start a knowledge base indexing job.
| description: |- | ||
| delete /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid} | ||
|
|
||
| This endpoint allows developers to unlink agent funciton. |
There was a problem hiding this comment.
This endpoint allows developers to destroy an agent's function route.
// Just to note that what this is doing is destroying the function route, so it is truly a destructive action. Do we have a confirmation step in the API as an "are you sure you want to destroy this route?" kind of thing?
| This endpoint allows developers to unlink agent funciton. | ||
| operationId: GenAIAPI_UnlinkAgentFunctionPublic | ||
| parameters: | ||
| - description: The id of the agent to unlink the function from |
There was a problem hiding this comment.
The id of the agent the function route belongs to.
| required: true | ||
| type: string | ||
| - description: |- | ||
| The function to remove from the agent |
There was a problem hiding this comment.
The function route to be destroyed. This does not destroy the function itself.
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: unlink agent funciton. |
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: Regenerate agent api key. |
There was a problem hiding this comment.
| summary: Regenerate agent api key. | |
| summary: Regenerate API Key for an Agent |
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: Start knowledge base indexing job. |
There was a problem hiding this comment.
| summary: Start knowledge base indexing job. | |
| summary: Start Indexing Job for a Knowledge Base |
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: 'Add Data Source to a Knowledge Base ' |
There was a problem hiding this comment.
| summary: 'Add Data Source to a Knowledge Base ' | |
| summary: Add Data Source to a Knowledge Base |
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: 'Delete API Key for an Agent ' |
There was a problem hiding this comment.
| summary: 'Delete API Key for an Agent ' | |
| summary: Delete API Key for an Agent |
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: 'Delete a Data Source from a Knowledge Base ' |
There was a problem hiding this comment.
| summary: 'Delete a Data Source from a Knowledge Base ' | |
| summary: Delete a Data Source from a Knowledge Base |
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: 'Retrieve Status of Indexing Job for a Knowledge Base ' |
There was a problem hiding this comment.
| summary: 'Retrieve Status of Indexing Job for a Knowledge Base ' | |
| summary: Retrieve Status of Indexing Job for a Knowledge Base |
There was a problem hiding this comment.
i think this is just the fact that it is a string
| example: '"My Agent Description"' | ||
| type: string | ||
| instruction: | ||
| description: Agent instruction |
There was a problem hiding this comment.
| description: Agent instruction | |
| description: Agent instruction. Instructions help your agent to perform its job effectively. See [Write Effective Agent Instructions](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/#agent-instructions) for best practices. |
| example: '"My Agent"' | ||
| type: string | ||
| project_id: | ||
| description: The id of the DigitalOcean this agent will belong to |
There was a problem hiding this comment.
| description: The id of the DigitalOcean this agent will belong to | |
| description: The id of the DigitalOcean project this agent will belong to |
| example: '"tor1"' | ||
| type: string | ||
| tags: | ||
| example: '["tag1", "tag2"]' |
There was a problem hiding this comment.
| example: '["tag1", "tag2"]' | |
| description: Agent tag to organize related resources | |
| example: '["tag1", "tag2"]' |
| name: agent_uuid | ||
| required: true | ||
| type: string | ||
| - description: Knowledge base |
There was a problem hiding this comment.
| - description: Knowledge base | |
| - description: Knowledge base id |
| description: Region of bucket | ||
| example: example string | ||
| type: string | ||
| title: Spaces Bucket Data Source |
There was a problem hiding this comment.
This one still appears in parenthesis.
| type: string | ||
| type: array | ||
| model_uuid: | ||
| description: Model id |
There was a problem hiding this comment.
| description: Model id | |
| description: Identifier for the [foundation model](https://docs.digitalocean.com/products/genai-platform/details/models/#foundation-models). |
| $ref: ../../shared/responses/server_error.yml | ||
| default: | ||
| $ref: ../../shared/responses/unexpected_error.yml | ||
| summary: Attach Knowledge base to Agent |
There was a problem hiding this comment.
| summary: Attach Knowledge base to Agent | |
| summary: Attach Knowledge Base to an Agent |
| @@ -0,0 +1,39 @@ | |||
| description: To create an agent API key, send a POST request to `/v2/gen-ai/agents/{agent_uuid}/api_keys`. | |||
| operationId: Create_an_Agent_API_Key | |||
There was a problem hiding this comment.
| operationId: Create_an_Agent_API_Key | |
| operationId: genAI_agent_api_key_create |
Can we follow the naming practice used in the rest of the project for these? When generating API clients from the OpenAPI spec (e.g. https://github.com/digitalocean/pydo), the operationId is used for the method names.
They should be in the format of <namespace>_<operation>. For example: sshKeys_list becomes ssh_keys.list().
So for this one example, we probably want something more like genAI_agent_api_key_create
There was a problem hiding this comment.
amanda requested the operation id be the summary. is it enough to add the genAi_ in front of it?
| tags: | ||
| - GenAI Platform | ||
| x-codeSamples: | ||
| - $ref: examples/curl/GenAIAPI_CancelKnowledgeBaseIndexingJobPublic.yml |
There was a problem hiding this comment.
| - $ref: examples/curl/GenAIAPI_CancelKnowledgeBaseIndexingJobPublic.yml | |
| - $ref: examples/curl/GenAIAPI_CancelKnowledgeBaseIndexingJobPublic.yml | |
| security: | |
| - bearer_auth: | |
| - 'genai:update' |
We also need to document the token scopes required for each operation. This can be done by adding a security section with the appropriate scopes under bearer_auth.
| - BATCH_JOB_PHASE_SUCCEEDED | ||
| - BATCH_JOB_PHASE_FAILED | ||
| - BATCH_JOB_PHASE_ERROR | ||
| example: example string |
There was a problem hiding this comment.
| example: example string | |
| example: BATCH_JOB_PHASE_PENDING |
A number of the validation errors I'm seeing are for cases like this where the example does not match a valid enum value.
|
Closing in favor of the new PR at: #966 |
No description provided.