Skip to content

Feat/add parts support to http api#270

Merged
MaojiaSheng merged 4 commits intovolcengine:mainfrom
SeanZ:feat/add-parts-support-to-http-api
Feb 25, 2026
Merged

Feat/add parts support to http api#270
MaojiaSheng merged 4 commits intovolcengine:mainfrom
SeanZ:feat/add-parts-support-to-http-api

Conversation

@SeanZ
Copy link
Contributor

@SeanZ SeanZ commented Feb 25, 2026

Summary

Add support for parts parameter in the HTTP API add_message endpoint, enabling feature parity with the Python SDK.

Previously, the HTTP API only supported content: str, which limited the ability to store structured message parts (TextPart, ContextPart, ToolPart). This PR adds an optional parts parameter while maintaining backward compatibility with the existing content parameter.

Type of Change

  • New feature (feat)
  • Bug fix (fix)
  • Documentation (docs)
  • Refactoring (refactor)
  • Other

Changes

API Changes

  • POST /api/v1/sessions/{session_id}/messages now accepts either:
    • content (string) - simple mode, backward compatible
    • parts (array) - full Part support mode

Files Modified

  • openviking/server/routers/sessions.py - Server endpoint
  • openviking/client/local.py - Local client
  • openviking_cli/client/http.py - HTTP client
  • docs/zh/api/05-sessions.md - Chinese documentation
  • docs/en/api/05-sessions.md - English documentation

Testing

# Test simple mode (backward compatible)
curl -X POST http://localhost:1933/api/v1/sessions/test/messages \
  -H "Content-Type: application/json" \
  -d '{"role": "user", "content": "Hello"}'

# Test parts mode
curl -X POST http://localhost:1933/api/v1/sessions/test/messages \
  -H "Content-Type: application/json" \
  -d '{"role": "assistant", "parts": [{"type": "text", "text": "Response"}]}'

Checklist

  • Code follows project style guidelines
  • Documentation updated
  • Tests added (TODO: add unit tests)

- Add optional 'parts' parameter to AddMessageRequest
- Support two modes: simple (content string) and parts (array)
- Update LocalClient and HTTP Client for consistency
- Update Chinese and English documentation

This enables HTTP API clients to store full Part information
(TextPart, ContextPart, ToolPart) instead of just text content,
achieving feature parity with the Python SDK.
When reading a non-existent file, agfs.read() raises AGFSClientError
which was not being caught by Session.load()'s exception handler.
This caused the server to return 422 errors instead of gracefully
handling missing session files.

Now read_file() catches all exceptions from agfs.read() and re-raises
them as FileNotFoundError, ensuring consistent error handling across
the codebase.
Map AGFSClientError to appropriate Python exceptions (FileNotFoundError,
PermissionError, IOError) instead of always raising FileNotFoundError.
This allows callers to handle file-not-found vs network errors differently.
@CLAassistant
Copy link

CLAassistant commented Feb 25, 2026

CLA assistant check
All committers have signed the CLA.

- Restore offset/limit parameters in HTTPClient and LocalClient read()
  methods that were accidentally removed
- Extract part_from_dict() to openviking/message/part.py to reduce
  code duplication between LocalClient and sessions router
@SeanZ SeanZ force-pushed the feat/add-parts-support-to-http-api branch from 1142560 to a269f30 Compare February 25, 2026 03:43
@qin-ctx qin-ctx self-requested a review February 25, 2026 04:05
@MaojiaSheng MaojiaSheng merged commit ea93ad0 into volcengine:main Feb 25, 2026
1 check passed
@github-project-automation github-project-automation bot moved this from Backlog to Done in OpenViking project Feb 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants