feat:Add OpenAPI agent revision APIs, models, and publishedRevisionId #126
Conversation
WalkthroughAdded agent revision management to the OpenAPI spec: new endpoints to list, create, retrieve, and publish agent revisions; introduced AgentRevision and PaginatedAgentRevisionList models; and extended Agent/PatchedAgent with a read-only publishedRevisionId field. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Client
participant API as API Server
participant Agents as Agents Service
Note over Client,Agents: Agent Revision Management (new)
rect rgba(230,246,255,0.6)
Client->>API: GET /api/agents/{agent_id}/revisions
API->>Agents: List revisions(agent_id, cursor, pageSize)
Agents-->>API: PaginatedAgentRevisionList
API-->>Client: 200 PaginatedAgentRevisionList
end
rect rgba(240,255,240,0.6)
Client->>API: POST /api/agents/{agent_id}/revisions (AgentRevision)
API->>Agents: Create revision(agent_id, callTemplate)
Agents-->>API: 201 AgentRevision
API-->>Client: 201 AgentRevision
end
rect rgba(255,250,230,0.6)
Client->>API: GET /api/agents/{agent_id}/revisions/{revision_id}
API->>Agents: Get revision(agent_id, revision_id)
Agents-->>API: AgentRevision
API-->>Client: 200 AgentRevision
end
rect rgba(255,240,245,0.6)
Client->>API: POST /api/agents/{agent_id}/revisions/{revision_id}/publish
API->>Agents: Publish revision(agent_id, revision_id)
Agents-->>API: Agent (with publishedRevisionId)
API-->>Client: 200 Agent
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
coderabbitai
bot
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (4)
src/libs/Ultravox/openapi.yaml (4)
458-486: Add standard error responses for missing/unauthorized revision.Consider adding 404 (unknown agent/revision) and 403 (forbidden) to improve client expectations. Response shape can reuse your existing error object pattern.
487-514: Publish semantics: specify idempotency and failure responses.
- Clarify whether publishing an already-published revision is idempotent (return 200 with current Agent).
- Add 404 (unknown agent/revision) and 409 (conflict if revision doesn’t belong to agent).
2741-2746: Minor: document the semantics of publishedRevisionId.Add a short description so SDKs/docs clarify whether
Agent.callTemplatereflects the published revision or the latest draft; if it’s the published one, say so explicitly.publishedRevisionId: type: string format: uuid nullable: true readOnly: true + description: The currently published revision for this agent; null if none is published.
3351-3372: Fix trailing quote in example URL.The
next(andprevious) example values end with an extra". Clean this to avoid noisy diffs in generated docs.next: type: string format: uri nullable: true - example: http://api.example.org/accounts/?cursor=cD00ODY%3D" + example: http://api.example.org/accounts/?cursor=cD00ODY%3D
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
⛔ Files ignored due to path filters (15)
src/libs/Ultravox/Generated/Ultravox.AgentsClient.AgentsRevisionsCreate.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.AgentsClient.AgentsRevisionsList.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.AgentsClient.AgentsRevisionsPublishCreate.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.AgentsClient.AgentsRevisionsRetrieve.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.IAgentsClient.AgentsRevisionsCreate.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.IAgentsClient.AgentsRevisionsList.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.IAgentsClient.AgentsRevisionsPublishCreate.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.IAgentsClient.AgentsRevisionsRetrieve.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.JsonSerializerContextTypes.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.Models.Agent.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.Models.AgentRevision.Json.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.Models.AgentRevision.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.Models.PaginatedAgentRevisionList.Json.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.Models.PaginatedAgentRevisionList.g.csis excluded by!**/generated/**src/libs/Ultravox/Generated/Ultravox.Models.PatchedAgent.g.csis excluded by!**/generated/**
📒 Files selected for processing (1)
src/libs/Ultravox/openapi.yaml(5 hunks)
🔇 Additional comments (1)
src/libs/Ultravox/openapi.yaml (1)
3759-3764: LGTM: PatchedAgent includes readOnly publishedRevisionId.This aligns with making the field visible in partial responses without implying writeability.
| '/api/agents/{agent_id}/revisions': | ||
| get: | ||
| tags: | ||
| - agents | ||
| operationId: agents_revisions_list | ||
| parameters: | ||
| - name: agent_id | ||
| in: path | ||
| required: true | ||
| schema: | ||
| type: string | ||
| format: uuid | ||
| - name: cursor | ||
| in: query | ||
| description: The pagination cursor value. | ||
| schema: | ||
| type: string | ||
| - name: pageSize | ||
| in: query | ||
| description: Number of results to return per page. | ||
| schema: | ||
| type: integer | ||
| responses: | ||
| '200': | ||
| description: '' | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/PaginatedAgentRevisionList' | ||
| security: | ||
| - apiKeyAuth: [ ] | ||
| post: | ||
| tags: | ||
| - agents | ||
| operationId: agents_revisions_create | ||
| parameters: | ||
| - name: agent_id | ||
| in: path | ||
| required: true | ||
| schema: | ||
| type: string | ||
| format: uuid | ||
| requestBody: | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/AgentRevision' | ||
| required: true | ||
| responses: | ||
| '201': | ||
| description: '' | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/AgentRevision' | ||
| security: | ||
| - apiKeyAuth: [ ] |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Use a create-only schema for POST body; avoid reusing AgentRevision (has readOnly required fields).
Reusing AgentRevision in the POST body will force clients/codegen to satisfy revisionId, created, and isPublished (all readOnly but listed as required). Many generators ignore readOnly during “required” checks inconsistently; this will cause friction and breaking types.
Apply this diff to point the POST body at a new create schema:
requestBody:
content:
application/json:
schema:
- $ref: '#/components/schemas/AgentRevision'
+ $ref: '#/components/schemas/AgentRevisionCreate'
required: trueAdd this schema under components/schemas (outside this hunk):
AgentRevisionCreate:
type: object
required: [callTemplate]
properties:
callTemplate:
$ref: '#/components/schemas/ultravox.v1.CallTemplate'Optionally document 400/404 failure modes to match other endpoints.
| required: | ||
| - agentId | ||
| - created | ||
| - publishedRevisionId |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Don’t add readOnly field to Agent.required (breaks clients).
publishedRevisionId is readOnly and nullable. Making it “required” on Agent breaks many code generators/types for create/update flows (you already pass Agent in POST /api/agents). Remove it from the required list; keep the property as readOnly.
required:
- agentId
- created
- - publishedRevisionId
- statistics📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - publishedRevisionId | |
| required: | |
| - agentId | |
| - created | |
| - statistics |
🤖 Prompt for AI Agents
In src/libs/Ultravox/openapi.yaml around line 2733, the Agent schema wrongly
lists the readOnly nullable property "publishedRevisionId" as required; remove
"publishedRevisionId" from the Agent.required array while keeping the
publishedRevisionId property defined with readOnly: true and nullable: true so
create/update POST payloads and generated clients are not broken.
| AgentRevision: | ||
| required: | ||
| - callTemplate | ||
| - created | ||
| - isPublished | ||
| - revisionId | ||
| type: object | ||
| properties: | ||
| revisionId: | ||
| type: string | ||
| format: uuid | ||
| readOnly: true | ||
| created: | ||
| type: string | ||
| format: date-time | ||
| readOnly: true | ||
| isPublished: | ||
| type: boolean | ||
| readOnly: true | ||
| callTemplate: | ||
| $ref: '#/components/schemas/ultravox.v1.CallTemplate' | ||
| BillingReasonEnum: |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Split response and create/update types for AgentRevision.
AgentRevision as a response type is fine, but using it in requests (with readOnly + required fields) is problematic. Keep AgentRevision for responses; introduce AgentRevisionCreate (required: callTemplate) for POST (see earlier diff).
I can wire the new schema throughout the spec and update any SDK generation config if you want.
🤖 Prompt for AI Agents
In src/libs/Ultravox/openapi.yaml around lines 2764 to 2785, AgentRevision is
defined with readOnly fields but is also being used for create/update requests;
split the model by keeping AgentRevision as the response type and add a new
AgentRevisionCreate schema that only requires callTemplate (no readOnly or
server-generated fields) and references the ultravox.v1.CallTemplate; then
update any POST/PUT request bodies in the spec to use AgentRevisionCreate
instead of AgentRevision and leave response schemas pointing to AgentRevision.
Summary by CodeRabbit