feat: add FastAPI RESTful server with SSE streaming and ark_apikey support by Copilot · Pull Request #80 · lybic/agent

Copilot · 2025-12-12T07:41:12Z

Summary of your change / What this PR does / why we need it?

Implements a RESTful API server using FastAPI as an HTTP/REST alternative to the existing gRPC service. Provides 8 endpoints matching the mini-agent OpenAPI specification with Server-Sent Events for real-time streaming and ark_apikey parameter for per-request LLM model configuration.

Implementation Details:

Server (gui_agents/restful_app.py, 997 lines)
- 8 REST endpoints: /api/agent/{info,run,submit,status,cancel,tasks}, /api/sandbox/create
- SSE streaming via EventSourceResponse for task execution
- RestfulAgentService mirrors AgentServicer architecture from grpc_app.py
- Task lifecycle management with storage, metrics, and conversation history
Model Configuration
- ark_apikey parameter applies custom API keys to all LLM tools
- Equivalent to gRPC's LLMConfig but via request body
- Enables multi-tenant scenarios with per-request credentials
Dependencies (pyproject.toml)
- New optional [restful] group: fastapi, sse-starlette, uvicorn, pydantic
- Entry point: lybic-guiagent-restful
Docker (Dockerfile)
- Includes restful extras in build
- Exposes port 8080

Usage:

import requests

# Submit task with custom LLM key
response = requests.post("http://localhost:8080/api/agent/submit", json={
    "instruction": "Open calculator and compute 123 + 456",
    "mode": "fast",
    "authentication": {"api_key": "...", "org_id": "..."},
    "ark_apikey": "sk-custom-openai-key"  # Configures all LLM tools
})
task_id = response.json()["task_id"]

# Stream execution in real-time
for line in requests.post("http://localhost:8080/api/agent/run", 
                         json={...}, stream=True).iter_lines():
    print(line.decode('utf-8'))  # SSE events: starting, running, finished

Interactive docs at /docs (Swagger UI).

Please indicate you've done the following:

Made sure tests are passing and test coverage is added if needed.
Made sure commit message follow the rule of Conventional Commits specification.
Considered the docs impact and opened a new docs issue or PR with docs changes if needed.

Special notes for your reviewer:

All endpoints tested via test suite (9 tests passing)
CodeQL security scan: 0 alerts
RESTful and gRPC services can run concurrently on different ports
Sandbox object removed from backend_kwargs before _run_task to avoid serialization issues in some backend implementations

Original prompt

使用fastapi开发 lybic guiagent restful 服务器，实现类似 gui_agent/grpc_app.py 的功能，并将该服务存储于 gui_agent/restful_app.py

api：
参考 https://github.com/lybic/mini-agent/blob/main/openapi.json 接口实现
参考 gui_agent/grpc_app.py 功能实现

其中，openapi文档 RunAgentRequest 的 ark_apikey 功能需要与 gui_agent/grpc_app.py 的 LLMConfig 类似，即支持指定agent的工作模型

在 pyproject.toml 中增加可选的fastapi依赖，但需要在dockerfile中支持完整的restful服务。

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

- Created gui_agents/restful_app.py with FastAPI implementation - Implemented all required endpoints from mini-agent OpenAPI spec - Added ark_apikey parameter support for model configuration - Updated pyproject.toml with restful optional dependencies - Updated Dockerfile to support RESTful server - Added lybic-guiagent-restful entry point Co-authored-by: AEnjoy <37976919+AEnjoy@users.noreply.github.com>

- Created comprehensive test suite in tests/test_restful_api.py - All 9 tests pass successfully - Added detailed documentation in docs/restful_api.md - Documentation includes API endpoints, examples, and usage guide Co-authored-by: AEnjoy <37976919+AEnjoy@users.noreply.github.com>

- Created comprehensive Python client example in examples/restful_client_example.py - Added RESTful API server information to main README.md - Included usage examples and documentation links - Client example demonstrates async submission, streaming, and task management Co-authored-by: AEnjoy <37976919+AEnjoy@users.noreply.github.com>

- Add comment explaining shared dependencies between mcp and restful - Improve clarity of comments about sandbox object removal - Explain why sandbox needs to be removed from backend_kwargs Co-authored-by: AEnjoy <37976919+AEnjoy@users.noreply.github.com>

Copilot

Pull request overview

This PR implements a FastAPI-based RESTful API server as an HTTP/REST alternative to the existing gRPC service. The implementation provides 8 endpoints matching the mini-agent OpenAPI specification, with Server-Sent Events (SSE) for real-time streaming and ark_apikey parameter support for per-request LLM model configuration.

Key Changes:

New RESTful server implementation in gui_agents/restful_app.py (997 lines) with endpoints for agent operations, task management, and sandbox creation
SSE-based streaming via EventSourceResponse for real-time task execution updates
Per-request LLM configuration through ark_apikey parameter, enabling multi-tenant scenarios with custom API keys

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
`gui_agents/restful_app.py`	Core RESTful server implementation with 8 API endpoints, RestfulAgentService class mirroring gRPC architecture, SSE streaming support, and ark_apikey-based model configuration
`tests/test_restful_api.py`	Syntax and structure validation tests for RESTful implementation covering models, endpoints, imports, and streaming support
`pyproject.toml`	Added optional `[restful]` dependency group with FastAPI, sse-starlette, uvicorn, and pydantic; added `lybic-guiagent-restful` entry point
`Dockerfile`	Updated to include restful extras in build and expose port 8080 for RESTful API
`docs/restful_api.md`	Comprehensive documentation covering installation, configuration, all 8 endpoints, ark_apikey usage, examples, and troubleshooting
`examples/restful_client_example.py`	Example client implementation demonstrating async submission, status polling, streaming, and custom model configuration
`README.md`	Added documentation for running RESTful server via Docker with reference to detailed usage guide

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-12T08:13:53Z

+        class SandboxInfo:
+            def __init__(self, id, shape_name):
+                self.id = id
+                self.shapeName = shape_name


The SandboxInfo class is duplicated in both _create_sandbox (lines 294-297) and _get_sandbox_pb (lines 316-319). Consider defining this class once at the module or class level to avoid code duplication and improve maintainability.

Copilot · 2025-12-12T08:13:54Z

+    task_id = str(uuid.uuid4())
+    logger.info(f"Received /api/agent/run request, assigning task_id: {task_id}")
+
+    service.metrics.record_grpc_request("RunAgent")


The method names record_grpc_request and record_grpc_error suggest gRPC-specific metrics, but this is a RESTful API. While this may be intentional for metric compatibility, consider whether these method names accurately reflect their use in a REST context. If the metrics system is shared between gRPC and REST implementations, this is acceptable, but the naming could be misleading.

- Replace direct LybicClient instantiation with async context manager - Simplify sandbox creation and retrieval logic - Update task cancellation handling to use 'canceled' instead of 'cancelled' - Fix module import naming from app to cli_app - Adjust logging and metrics recording for consistency - Update backend compatibility checks to use cli_app module

…trol - Introduce StageModelConfig and LLMConfig Pydantic models - Replace single ark_apikey field with structured stage_model_config - Support per-component LLM configuration (grounding, action generation, etc.) - Allow custom API endpoints and provider-specific settings - Update REST API documentation with new parameter and examples - Modify agent creation logic to apply stage-specific configurations - Maintain backward compatibility through action_generator_model fallback - Add support for platform-specific agent instantiation

AEnjoy · 2025-12-12T09:47:57Z

/gemini review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

gemini-code-assist

Code Review

This pull request introduces a significant and well-structured feature: a FastAPI-based RESTful server that mirrors the existing gRPC service. The implementation includes SSE for real-time streaming, comprehensive documentation, and an example client, which are all excellent additions. The code is generally clean and follows modern asynchronous Python practices. My review focuses on a few key areas for improvement: ensuring the ark_apikey feature is fully implemented as described, enhancing error handling for web clients, and a couple of refactoring suggestions for better maintainability and dependency management.

gemini-code-assist · 2025-12-12T09:50:33Z

+            sandbox = await lybic_client.sandbox.get(result.id)
+
+        # Create simple namespace object to mimic protobuf
+        class SandboxInfo:


The nested class SandboxInfo is used here and in _get_sandbox_pb to mimic a protobuf structure. In a FastAPI application, it's more idiomatic and maintainable to define this as a Pydantic BaseModel at the top level of the file. This improves type safety, consistency with other models, and allows for easier serialization (e.g., using .model_dump()).

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

- Implemented MigrationManager class to handle SQL migrations - Added automatic migration execution during PostgreSQL storage initialization - Created migration tracking table (schema_migrations) to record applied versions - Added support for running individual migration files - Included convenience function migrate_database for easy migration execution - Added CLI script (run_migrations.py) for manual migration management - Created README.md with migration documentation and troubleshooting guide - Added first migration (001_add_conversation_history.sql) to extend agent_tasks table - Implemented idempotent migration operations using IF NOT EXISTS clauses - Added proper logging and error handling for migration processes

- Add logic to retrieve and validate sandbox from previous tasks - Handle sandbox expiration and not-found errors with proper messaging - Ensure sandbox ID consistency when both previous and new IDs are provided - Update all three apps (grpc, mcp, restful) to support continuing tasks - Introduce final_sandbox_id variable for clearer sandbox management - Log sandbox usage and creation for better traceability - Import LybicAPIError for more precise error handling

Initial plan

e0a097e

Copilot AI assigned Copilot and AEnjoy Dec 12, 2025

Copilot started work on behalf of AEnjoy December 12, 2025 07:41 View session

Copilot AI and others added 4 commits December 12, 2025 07:46

Address code review feedback

db9e847

- Add comment explaining shared dependencies between mcp and restful - Improve clarity of comments about sandbox object removal - Explain why sandbox needs to be removed from backend_kwargs Co-authored-by: AEnjoy <37976919+AEnjoy@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add FastAPI implementation for LyBic GUIAgent RESTful server~~ Add FastAPI RESTful server with SSE streaming and ark_apikey support Dec 12, 2025

Copilot AI requested a review from AEnjoy December 12, 2025 07:59

Copilot finished work on behalf of AEnjoy December 12, 2025 07:59

AEnjoy marked this pull request as ready for review December 12, 2025 08:02

Copilot AI review requested due to automatic review settings December 12, 2025 08:02

AEnjoy changed the title ~~Add FastAPI RESTful server with SSE streaming and ark_apikey support~~ feat: add FastAPI RESTful server with SSE streaming and ark_apikey support Dec 12, 2025

Copilot started reviewing on behalf of AEnjoy December 12, 2025 08:03 View session

Copilot AI reviewed Dec 12, 2025

View reviewed changes

AEnjoy added 2 commits December 12, 2025 16:59

AEnjoy and others added 2 commits December 12, 2025 17:49

Update gui_agents/restful_app.py

a535d21

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update gui_agents/restful_app.py

37567f7

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

gemini-code-assist Bot reviewed Dec 12, 2025

View reviewed changes

AEnjoy and others added 5 commits December 12, 2025 17:53

Update pyproject.toml

e236208

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Update gui_agents/restful_app.py

0a3e68d

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

update docs

9ce9cca

AEnjoy merged commit c6eaad2 into main Dec 15, 2025
2 checks passed

AEnjoy deleted the copilot/implement-fastapi-restful-server branch December 15, 2025 03:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add FastAPI RESTful server with SSE streaming and ark_apikey support#80

feat: add FastAPI RESTful server with SSE streaming and ark_apikey support#80
AEnjoy merged 14 commits into
mainfrom
copilot/implement-fastapi-restful-server

Copilot AI commented Dec 12, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Dec 12, 2025

Uh oh!

Uh oh!

Uh oh!

Copilot AI Dec 12, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AEnjoy commented Dec 12, 2025

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist Bot Dec 12, 2025

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of your change / What this PR does / why we need it?

Please indicate you've done the following:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AEnjoy commented Dec 12, 2025

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist Bot Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Dec 12, 2025 •

edited

Loading