[PRE-284] Update Python SDK to reflect agent deployment changes - #15
Merged
Siutan merged 13 commits intoMay 14, 2026
Merged
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR enables deployment-scoped authentication tokens by making Changes
Sequence DiagramsequenceDiagram
participant Client as Client Code
participant CoreClient as PrefactorCoreClient
participant Manager as AgentInstanceManager
participant HttpClient as PrefactorHttpClient
participant API as Prefactor API
rect rgba(100, 150, 200, 0.5)
Note over Client,API: Deployment-Scoped Token (agent_id=None)
Client->>CoreClient: create_agent_instance(agent_id=None)
CoreClient->>Manager: register(agent_id=None, environment_id=None)
Manager->>HttpClient: agent_instances.register(agent_id=None, environment_id=None, ...)
HttpClient->>API: POST /agent_instances (minimal payload)
API-->>HttpClient: AgentInstance {agent_deployment_id}
HttpClient-->>Manager: registration response
Manager-->>CoreClient: instance token
CoreClient-->>Client: AgentInstanceHandle
end
rect rgba(150, 200, 100, 0.5)
Note over Client,API: Account-Scoped Token (with agent_id and environment_id)
Client->>CoreClient: create_agent_instance(agent_id="my-agent", environment_id="env-1")
CoreClient->>Manager: register(agent_id="my-agent", environment_id="env-1", ...)
Manager->>HttpClient: agent_instances.register(agent_id="my-agent", environment_id="env-1", ...)
HttpClient->>API: POST /agent_instances (full payload)
API-->>HttpClient: AgentInstance {agent_deployment_id}
HttpClient-->>Manager: registration response
Manager-->>CoreClient: instance token
CoreClient-->>Client: AgentInstanceHandle
end
Estimated Code Review Effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly Related PRs
Suggested Reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Siutan
marked this pull request as ready for review
April 30, 2026 07:32
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
packages/core/src/prefactor_core/client.py (1)
322-322: ⚡ Quick winDocument the new
environment_idargument increate_agent_instance()docstring.Line 322 adds a public parameter, but it is missing from the
Argssection, which makes the method contract incomplete.Docstring patch
Args: agent_id: ID of the agent to create an instance for. agent_version: Version information (name, etc.). agent_schema_version: Schema version. Uses registry if not provided and registry is configured. instance_id: Optional custom ID for the instance. external_schema_version_id: Optional external identifier for the schema version. Defaults to "auto-generated" when using registry. + environment_id: Optional environment ID. Required when using an + account-scoped token; omit when using a deployment-scoped token.As per coding guidelines, "All public functions and classes need docstrings in Google style".
Also applies to: 332-340
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/core/src/prefactor_core/client.py` at line 322, The docstring for create_agent_instance is missing the new public parameter environment_id; update the Google-style docstring Args section in the create_agent_instance function to include a clear entry for environment_id (type and purpose, e.g., "environment_id (str | None): Optional environment identifier used to scope the agent instance.") and ensure the description formatting matches the existing Args entries (wrap type in parentheses and provide a short description). Also scan the nearby docstring area referenced around lines where create_agent_instance is defined to ensure documentation consistency for any other newly added parameters.packages/http/tests/test_agent_deployment.py (1)
1-4: ⚡ Quick winAdd
from __future__ import annotationsat module top.This new Python module is missing the required future-annotations import.
As per coding guidelines, `**/*.py`: Use Python 3.11+ with `from __future__ import annotations` at the top of modules.Proposed fix
"""Tests for AgentDeployment models and endpoint client.""" +from __future__ import annotations + import pytest from aioresponses import aioresponses🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/http/tests/test_agent_deployment.py` around lines 1 - 4, This module is missing the required future annotations import; add the line "from __future__ import annotations" at the very top of the test module (before any other imports or code) in the file containing the AgentDeployment tests (test_agent_deployment.py) so that the module uses PEP 563-style postponed evaluation of annotations for compatibility with Python 3.11+ and project guidelines.packages/http/src/prefactor_http/models/agent_deployment.py (1)
11-30: ⚡ Quick winPublic model classes need Google-style docstrings.
These are exported SDK-facing models; adding class docstrings keeps the public contract self-describing.
As per coding guidelines, `All public functions and classes need docstrings in Google style`.Proposed fix
class AgentDeployment(BaseModel): + """Represents an agent deployment. + + Attributes: + type: Resource discriminator. + id: Deployment ID. + account_id: Account ID owning the deployment. + agent_id: Agent ID. + environment_id: Environment ID. + current_version_id: Currently pinned version ID, if any. + inserted_at: Creation timestamp. + updated_at: Last update timestamp. + """ type: Literal["agent_deployment"] @@ class CreateAgentDeploymentRequest(BaseModel): + """Request payload for creating an agent deployment. + + Attributes: + agent_id: Agent ID. + environment_id: Environment ID. + current_version_id: Optional initial pinned version ID. + id: Optional explicit deployment ID. + """ agent_id: str @@ class UpdateAgentDeploymentRequest(BaseModel): + """Request payload for updating an agent deployment. + + Attributes: + current_version_id: New pinned version ID, or `None` to clear. + """ current_version_id: str | None = None🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/http/src/prefactor_http/models/agent_deployment.py` around lines 11 - 30, Add Google-style docstrings to the three public Pydantic models: AgentDeployment, CreateAgentDeploymentRequest, and UpdateAgentDeploymentRequest. For each class provide a one-line summary, a short description if needed, and an Attributes section listing each field (e.g., id, account_id, agent_id, environment_id, current_version_id, inserted_at, updated_at for AgentDeployment; agent_id, environment_id, current_version_id, id for CreateAgentDeploymentRequest; current_version_id for UpdateAgentDeploymentRequest) with types and a brief purpose for each attribute so the SDK contract is self-describing.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/http/src/prefactor_http/endpoints/agent_deployment.py`:
- Around line 97-111: The update() method is treating an omitted
current_version_id the same as an explicit None, causing unintentional clearing;
change the signature to use a unique sentinel (e.g., _UNSET) instead of None as
the default for current_version_id, construct UpdateAgentDeploymentRequest only
when the sentinel is not passed (or set the field but serialize with
exclude_unset=True), and call details.model_dump(exclude_unset=True) before
sending via self._client.request so that omitted fields are not serialized and
explicit None still clears the pin; update references to current_version_id,
UpdateAgentDeploymentRequest, model_dump, and the _client.request call
accordingly.
---
Nitpick comments:
In `@packages/core/src/prefactor_core/client.py`:
- Line 322: The docstring for create_agent_instance is missing the new public
parameter environment_id; update the Google-style docstring Args section in the
create_agent_instance function to include a clear entry for environment_id (type
and purpose, e.g., "environment_id (str | None): Optional environment identifier
used to scope the agent instance.") and ensure the description formatting
matches the existing Args entries (wrap type in parentheses and provide a short
description). Also scan the nearby docstring area referenced around lines where
create_agent_instance is defined to ensure documentation consistency for any
other newly added parameters.
In `@packages/http/src/prefactor_http/models/agent_deployment.py`:
- Around line 11-30: Add Google-style docstrings to the three public Pydantic
models: AgentDeployment, CreateAgentDeploymentRequest, and
UpdateAgentDeploymentRequest. For each class provide a one-line summary, a short
description if needed, and an Attributes section listing each field (e.g., id,
account_id, agent_id, environment_id, current_version_id, inserted_at,
updated_at for AgentDeployment; agent_id, environment_id, current_version_id, id
for CreateAgentDeploymentRequest; current_version_id for
UpdateAgentDeploymentRequest) with types and a brief purpose for each attribute
so the SDK contract is self-describing.
In `@packages/http/tests/test_agent_deployment.py`:
- Around line 1-4: This module is missing the required future annotations
import; add the line "from __future__ import annotations" at the very top of the
test module (before any other imports or code) in the file containing the
AgentDeployment tests (test_agent_deployment.py) so that the module uses PEP
563-style postponed evaluation of annotations for compatibility with Python
3.11+ and project guidelines.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d2f7ef33-0c2a-4efc-b8da-1b5b04f33596
📒 Files selected for processing (14)
packages/core/src/prefactor_core/client.pypackages/core/src/prefactor_core/managers/agent_instance.pypackages/core/tests/test_agent_instance_register.pypackages/http/src/prefactor_http/__init__.pypackages/http/src/prefactor_http/client.pypackages/http/src/prefactor_http/endpoints/__init__.pypackages/http/src/prefactor_http/endpoints/agent_deployment.pypackages/http/src/prefactor_http/endpoints/agent_instance.pypackages/http/src/prefactor_http/models/__init__.pypackages/http/src/prefactor_http/models/agent_deployment.pypackages/http/src/prefactor_http/models/agent_instance.pypackages/http/tests/test_agent_deployment.pypackages/http/tests/test_endpoints.pypackages/http/tests/test_models.py
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
packages/http/src/prefactor_http/endpoints/agent_deployment.py (1)
22-132: ⚡ Quick winStandardize public API docstrings to Google style.
Public class/method docstrings should include structured sections (
Args,Returns, andRaiseswhere relevant) for consistency with repository standards.As per coding guidelines, "All public functions and classes need docstrings in Google style".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/http/src/prefactor_http/endpoints/agent_deployment.py` around lines 22 - 132, The public API docstrings in AgentDeploymentClient (class) and its public methods list, get, create, update, and delete are not in Google style; update each public docstring to Google style including structured sections: Args (with parameter names and types), Returns (type and brief description), and Raises where applicable (e.g., PrefactorResponseContractError from _parse_response and list when ValidationError is raised); also add a short one-line class summary for AgentDeploymentClient and for each method keep the existing short description (HTTP path) but move it into the main description paragraph above the Args/Returns/Raises sections so reviewers can quickly locate the changes by looking for AgentDeploymentClient, _parse_response, list, get, create, update, and delete.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/http/src/prefactor_http/endpoints/agent_deployment.py`:
- Around line 102-116: The parameter current_version_id is annotated as str |
None | object which prevents the type checker from narrowing away the sentinel;
change the signature to include the actual sentinel type (e.g., create a type
alias Unset = type(_UNSET) or similar) and annotate as current_version_id: str |
None | Unset = _UNSET so the else branch passes a value matching
UpdateAgentDeploymentRequest's expected str | None; update the function/method
update() signature and imports/aliases for _UNSET/Unset accordingly so static
type checking can confirm current_version_id is str | None before calling
UpdateAgentDeploymentRequest(current_version_id=...).
In `@packages/http/tests/test_agent_deployment.py`:
- Around line 5-17: Imports are out of import-order: move third-party imports
(including "from pydantic import ValidationError") before local package imports
so they appear in the third-party group ahead of "from prefactor_http import
..." and related local imports; adjust the import block in this test file so
pytest, aioresponses, and pydantic are grouped together above
PrefactorHttpClient/AgentDeployment-related imports to satisfy the repo
import-order rule.
---
Nitpick comments:
In `@packages/http/src/prefactor_http/endpoints/agent_deployment.py`:
- Around line 22-132: The public API docstrings in AgentDeploymentClient (class)
and its public methods list, get, create, update, and delete are not in Google
style; update each public docstring to Google style including structured
sections: Args (with parameter names and types), Returns (type and brief
description), and Raises where applicable (e.g., PrefactorResponseContractError
from _parse_response and list when ValidationError is raised); also add a short
one-line class summary for AgentDeploymentClient and for each method keep the
existing short description (HTTP path) but move it into the main description
paragraph above the Args/Returns/Raises sections so reviewers can quickly locate
the changes by looking for AgentDeploymentClient, _parse_response, list, get,
create, update, and delete.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: c524e64a-016b-4ff8-a662-7b15950a3a72
📒 Files selected for processing (4)
packages/core/src/prefactor_core/client.pypackages/http/src/prefactor_http/endpoints/agent_deployment.pypackages/http/src/prefactor_http/models/agent_deployment.pypackages/http/tests/test_agent_deployment.py
✅ Files skipped from review due to trivial changes (1)
- packages/http/src/prefactor_http/models/agent_deployment.py
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/core/src/prefactor_core/client.py
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/core/examples/agent_e2e.py (1)
34-39: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winAdd
from __future__ import annotationsat the module top.This file is part of the change set but does not include the required future import.
♻️ Proposed fix
""" E2E example for prefactor-core. @@ environment from the token. """ +from __future__ import annotations + import asyncio import osAs per coding guidelines,
**/*.py: Use Python 3.11+ withfrom __future__ import annotationsat the top of modules.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/core/examples/agent_e2e.py` around lines 34 - 39, Add the future annotations import at the very top of the module by inserting "from __future__ import annotations" before any other imports in the file; update the module that imports asyncio, os, PrefactorCoreClient/PrefactorCoreConfig/SchemaRegistry and HttpClientConfig so the future import appears as the first line to satisfy the Python 3.11+ coding guideline.
🧹 Nitpick comments (1)
packages/http/src/prefactor_http/models/agent_instance.py (1)
227-251: ⚡ Quick winUpdate
AgentInstancedocstring to includeagent_deployment_id.A required public field was added, but the class attribute documentation wasn’t updated.
📝 Proposed fix
class AgentInstance(BaseModel): @@ agent_version_id: Agent version ID environment_id: Environment ID + agent_deployment_id: Agent deployment ID status: Instance statusAs per coding guidelines,
**/*.py: All public functions and classes need docstrings in Google style.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/http/src/prefactor_http/models/agent_instance.py` around lines 227 - 251, The AgentInstance docstring is missing the new public field agent_deployment_id; update the class docstring for AgentInstance to include a line describing agent_deployment_id (e.g., "agent_deployment_id: Deployment ID for the agent") following the same Google-style attribute list and formatting as the other attributes so the documentation matches the declared attribute `agent_deployment_id` in the class.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@packages/core/examples/agent_e2e.py`:
- Around line 34-39: Add the future annotations import at the very top of the
module by inserting "from __future__ import annotations" before any other
imports in the file; update the module that imports asyncio, os,
PrefactorCoreClient/PrefactorCoreConfig/SchemaRegistry and HttpClientConfig so
the future import appears as the first line to satisfy the Python 3.11+ coding
guideline.
---
Nitpick comments:
In `@packages/http/src/prefactor_http/models/agent_instance.py`:
- Around line 227-251: The AgentInstance docstring is missing the new public
field agent_deployment_id; update the class docstring for AgentInstance to
include a line describing agent_deployment_id (e.g., "agent_deployment_id:
Deployment ID for the agent") following the same Google-style attribute list and
formatting as the other attributes so the documentation matches the declared
attribute `agent_deployment_id` in the class.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: ea92f2c5-95a2-4329-b69e-d1a3ab0c244a
📒 Files selected for processing (15)
packages/core/README.mdpackages/core/examples/agent_e2e.pypackages/core/src/prefactor_core/client.pypackages/core/src/prefactor_core/managers/agent_instance.pypackages/core/tests/test_agent_instance_register.pypackages/http/README.mdpackages/http/src/prefactor_http/endpoints/agent_instance.pypackages/http/src/prefactor_http/models/agent_instance.pypackages/http/tests/test_endpoints.pypackages/langchain/README.mdpackages/langchain/src/prefactor_langchain/middleware.pypackages/langchain/tests/test_middleware.pypackages/livekit/README.mdpackages/livekit/src/prefactor_livekit/session.pypackages/livekit/tests/test_session.py
✅ Files skipped from review due to trivial changes (4)
- packages/http/README.md
- packages/livekit/README.md
- packages/langchain/README.md
- packages/core/README.md
🚧 Files skipped from review as they are similar to previous changes (3)
- packages/http/tests/test_endpoints.py
- packages/core/src/prefactor_core/managers/agent_instance.py
- packages/livekit/tests/test_session.py
joshgillies
approved these changes
May 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes pre-284
Summary by CodeRabbit
Release Notes
New Features
agent_idandenvironment_idare now optional and automatically inferred from the token.Documentation
agent_idandenvironment_id) and deployment-scoped tokens (parameters inferred from the token).