[5641] fix(sdk): return 422 for invalid self-managed connections

[Linxiushen]

Summary

Closes #5641.

Invalid agent connection values are parsed inside the agent handler, after FastAPI request-model validation. The resulting Pydantic ValidationError therefore reached the workflow normalizer without a client-error status and was returned as HTTP 500.

This change catches validation only around AgentTemplate.from_params() and converts it to a typed AgentTemplateValidationError with status 422. The narrow boundary keeps downstream/internal Pydantic failures visible as server errors while preserving the original field-level validation message for callers.

Testing

Verified locally

• 24 passed: oss/tests/pytest/unit/test_invoke_real_handlers_negotiation_routing.py
• 14 passed: oss/tests/pytest/unit/agents/test_agent_composition_seam.py
• ruff format --check with the CI-pinned Ruff 0.15.12
• ruff check with the CI-pinned Ruff 0.15.12

Added or updated tests

Added a regression through the real FastAPI /invoke route. It submits connection: {mode: self_managed, slug: unused}, asserts HTTP 422 and the typed error URI, and verifies the original validation message is preserved.

QA follow-up

Confirm the same request returns 422 in a deployed staging workflow service after the next build.

Demo

Checklist

• I have included a video or screen recording for UI changes, or marked Demo as N/A
• Relevant tests pass locally
• Relevant linting and formatting pass locally
• I have signed the CLA, or I will sign it when the bot prompts me

[vercel]

@Linxiushen is attempting to deploy a commit to the agenta projects Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 03c0e734-472e-4b0e-9c64-80c4a97c9c8a

📥 Commits

Reviewing files that changed from the base of the PR and between 44ec7e9 and d1686df.

📒 Files selected for processing (1)

• sdks/python/oss/tests/pytest/unit/test_invoke_real_handlers_negotiation_routing.py

🚧 Files skipped from review as they are similar to previous changes (1)

• sdks/python/oss/tests/pytest/unit/test_invoke_real_handlers_negotiation_routing.py

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes
  • Improved agent template error handling by distinguishing structural errors from invalid template values.
  • Invalid agent template requests now return a clear HTTP 422 validation response.
  • Agent invocation requests can include optional parameters, including self-managed connection details.
  • Improved error responses for invalid composition defaults.

Walkthrough

The agent handler converts agent template validation failures into HTTP 422 responses. A dedicated error class identifies invalid template values. Tests cover invalid self-managed connections and invalid composition defaults.

Changes

Agent template validation

Layer / File(s)	Summary
Validation error contract and handler mapping sdks/python/agenta/sdk/agents/dtos.py, sdks/python/agenta/sdk/agents/handler.py	Adds AgentTemplateValidationError with HTTP 422 metadata and maps Pydantic template validation errors to this exception.
Request helper and regression coverage sdks/python/oss/tests/pytest/unit/test_invoke_real_handlers_negotiation_routing.py	Extends test helpers for template injection, request parameters, and exception handling. Verifies HTTP 422 for invalid self-managed connections and HTTP 500 for invalid composition defaults.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant AgentRequest
  participant AgentHandler
  participant AgentTemplate
  AgentRequest->>AgentHandler: Submit agent template parameters
  AgentHandler->>AgentTemplate: Call from_params
  AgentTemplate-->>AgentHandler: Raise ValidationError
  AgentHandler-->>AgentRequest: Return HTTP 422 validation error

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the SDK fix and the expected HTTP 422 response for invalid self-managed connections.
Description check	✅ Passed	The description explains the validation error, the HTTP 422 conversion, preserved messages, and related tests.
Linked Issues check	✅ Passed	The changes address issue #5641 by converting template validation failures to HTTP 422 while preserving the original validation message.
Out of Scope Changes check	✅ Passed	The changes remain within scope by adding the typed validation error, applying it at the template boundary, and adding regression tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with 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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 214e51b7-f9ed-4ce3-b001-b62b29e6cb36

📥 Commits

Reviewing files that changed from the base of the PR and between 4165aa8 and 8090b46.

📒 Files selected for processing (3)

• sdks/python/agenta/sdk/agents/dtos.py
• sdks/python/agenta/sdk/agents/handler.py
• sdks/python/oss/tests/pytest/unit/test_invoke_real_handlers_negotiation_routing.py

[coderabbitai]

🧹 Nitpick comments (1)

sdks/python/oss/tests/pytest/unit/test_invoke_real_handlers_negotiation_routing.py (1)

288-301: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider asserting the response body, not only the status code.

The test only checks resp.status_code == 500. Add an assertion on resp.json() (for example, confirming the response does not surface the raw AgentTemplateValidationError shape used for the 422 case) to guard against a future regression where an invalid composition default is misclassified as a client error instead of an internal one.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9702cd20-05bd-4493-82c4-eeb4c514831e

📥 Commits

Reviewing files that changed from the base of the PR and between 8090b46 and 44ec7e9.

📒 Files selected for processing (2)

• sdks/python/agenta/sdk/agents/handler.py
• sdks/python/oss/tests/pytest/unit/test_invoke_real_handlers_negotiation_routing.py

🚧 Files skipped from review as they are similar to previous changes (1)

• sdks/python/agenta/sdk/agents/handler.py

[Linxiushen]

Addressed the latest review suggestion in d1686df: the composition-default regression now checks the structured 500 payload is classified as #v1:sdk:unknown-workflow-invoke-error, preventing it from silently regressing to the request-level invalid-template error shape. Focused test: 1 passed; Ruff lint and format checks passed.