{"id":6958,"library":"agentscope-runtime","title":"AgentScope Runtime","description":"AgentScope Runtime is a production-ready framework for deploying agent applications, providing secure sandboxed execution environments, scalable deployment solutions (local, Kubernetes, serverless), and multi-framework support. It exposes agents as streaming, production-ready APIs with full-stack observability. The current version is 1.1.3, and it maintains an active development and release cadence.","status":"active","version":"1.1.3","language":"en","source_language":"en","source_url":"https://github.com/agentscope-ai/agentscope-runtime","tags":["agent","llm","runtime","sandbox","deployment","fastapi","ai"],"install":[{"cmd":"pip install agentscope-runtime","lang":"bash","label":"Base installation"},{"cmd":"pip install \"agentscope-runtime[ext]\"","lang":"bash","label":"Installation with extensions (e.g., for certain model integrations)"}],"dependencies":[{"reason":"AgentApp directly inherits from FastAPI for web service capabilities.","package":"fastapi"},{"reason":"The core AgentScope framework is a foundational dependency for defining agents.","package":"agentscope"},{"reason":"Required for sandbox tool execution, as it relies on Docker images.","package":"docker"},{"reason":"Often used in quickstart examples for local session management during development/testing.","package":"fakeredis","optional":true}],"imports":[{"note":"As of v1.1.0, AgentApp directly inherits from FastAPI, deprecating the previous factory pattern.","wrong":"from agentscope_runtime.factory import create_agent_app","symbol":"AgentApp","correct":"from agentscope_runtime.engine import AgentApp"},{"symbol":"LocalDeployManager","correct":"from agentscope_runtime.engine.deployers import LocalDeployManager"},{"note":"ReActAgent is part of the core `agentscope` framework, not `agentscope_runtime` directly.","symbol":"ReActAgent","correct":"from agentscope.agent import ReActAgent"},{"note":"RedisSession is part of the core `agentscope` framework for session management.","symbol":"RedisSession","correct":"from agentscope.session import RedisSession"}],"quickstart":{"code":"import os\nimport uvicorn\nfrom contextlib import asynccontextmanager\nfrom fastapi import FastAPI\nfrom agentscope.agent import ReActAgent\nfrom agentscope.model import DashScopeChatModel\nfrom agentscope.formatter import DashScopeChatFormatter\nfrom agentscope.memory import InMemoryMemory\nfrom agentscope.session import RedisSession\nfrom agentscope_runtime.engine import AgentApp\nfrom agentscope_runtime.engine.schemas.agent_schemas import AgentRequest\nfrom agentscope.pipeline import stream_printing_messages\nimport fakeredis # For local development/testing\n\n# Configure API key (replace with your actual key or other LLM provider config)\n# os.environ['DASHSCOPE_API_KEY'] = 'YOUR_API_KEY_HERE'\n\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n    # Initialize Session manager (using fakeredis for demonstration)\n    fake_redis = fakeredis.aioredis.FakeRedis(decode_responses=True)\n    app.state.session = RedisSession(connection_pool=fake_redis.connection_pool)\n    print(\"\\n🚀 AgentApp starting up...\")\n    yield\n    print(\"\\n🛑 AgentApp shutting down...\")\n\nagent_app = AgentApp(lifespan=lifespan)\n\n@agent_app.query(framework=\"agentscope\")\nasync def query_agent(msgs, request: AgentRequest = None, **kwargs):\n    # Example agent setup - customize with your model, tools, and memory\n    dashscope_api_key = os.environ.get('DASHSCOPE_API_KEY', 'sk-example') # Use actual key in production\n    if not dashscope_api_key or dashscope_api_key == 'sk-example':\n        print(\"Warning: DASHSCOPE_API_KEY not set. Using dummy key. Model interactions may fail.\")\n\n    model = DashScopeChatModel(\n        model_name=\"qwen-plus\", # Or your preferred model\n        api_key=dashscope_api_key,\n        # Other model parameters like `temperature`, `max_tokens` can be set here\n    )\n    agent = ReActAgent(\n        name=\"SimpleAgent\",\n        model=model,\n        memory=InMemoryMemory(), # Or RedisSession for persistence\n        formatter=DashScopeChatFormatter(),\n    )\n\n    # Load session context (if using RedisSession in app.state.session)\n    if hasattr(request, 'session_id') and app.state.session:\n        session_id = request.session_id\n        # In a real scenario, you'd load context using session_id\n        # For this simple example, we'll just acknowledge it.\n        print(f\"Processing request for session_id: {session_id}\")\n\n    # Stream responses\n    async for msg, last in stream_printing_messages(agent.reply(msgs, **kwargs)):\n        yield msg, last\n\n\n# To run this: save as e.g., `main.py` and run `uvicorn main:agent_app --reload --port 8090`\n# Test with curl:\n# curl -N -X POST \"http://localhost:8090/process\" \\\n#      -H \"Content-Type: application/json\" \\\n#      -d '{ \"input\": [ { \"role\": \"user\", \"content\": [ { \"type\": \"text\", \"text\": \"What is the capital of France?\" } ] } ], \"session_id\": \"session_1\" }'","lang":"python","description":"This quickstart demonstrates how to create a basic agent application using `AgentScope Runtime` to expose an AgentScope `ReActAgent` as a streaming API. It includes lifecycle management, session handling (using `fakeredis` for local testing), and uses a DashScope model (requires `DASHSCOPE_API_KEY`). To run, save as `main.py` and execute `uvicorn main:agent_app --reload --port 8090`."},"warnings":[{"fix":"Migrate your `AgentApp` instantiation to directly use `AgentApp()` and integrate FastAPI lifecycle events via `lifespan` context manager.","message":"AgentApp's architecture was refactored in v1.1.0 to directly inherit from FastAPI, deprecating the previous factory pattern. Code using `create_agent_app` will break.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Monitor AgentScope and AgentScope Runtime release notes for 2.0.0+ for migration guides. Development for this is tracked on a `v2_dev` branch.","message":"Future AgentScope 2.0.0 (core framework) plans to consolidate some `agentscope-runtime` deployment capabilities directly into the core `agentscope` library. This will involve breaking changes and refactoring of core data structures and tool execution.","severity":"breaking","affected_versions":"Anticipated in AgentScope 2.0.0 and subsequent `agentscope-runtime` versions."},{"fix":"Ensure Docker is installed and running, and pull necessary sandbox images (e.g., `docker pull agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-browser:latest` and tag it as `agentscope/runtime-sandbox-browser:latest`).","message":"Using sandboxed tools (e.g., `BrowserSandbox`, `FilesystemSandbox`) often requires a running Docker daemon and pulling specific Docker images. The quickstart examples using sandboxes might not work out-of-the-box without Docker setup.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Replace `fakeredis` with an actual `aioredis.Redis` client or your chosen production-grade Redis client, configuring it with your Redis connection details.","message":"The quickstart and examples often use `fakeredis` for local session management. This is for development/testing only. For production deployments, a robust Redis client and connection to a real Redis instance are required.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Inspect the generated Dockerfile for syntax errors or unexpected characters. Ensure your Docker daemon is running correctly and has sufficient permissions. Check for common Docker build environment issues.","cause":"This error typically indicates an issue during the Docker image build process for deploying an agent, possibly due to malformed Dockerfile generation or specific Docker environment issues.","error":"Failed to build image: Runner image build failed: Command '['docker', 'build', '-t', ...']' returned non-zero exit status 1. (Error response from daemon: dockerfile parse error line 19: unknown instruction: EOF)"},{"fix":"This is a library-level issue. Users can work around it by configuring their type checker to ignore missing type stubs for `agentscope_runtime` (e.g., add `\"agentscope_runtime\"` to `reportMissingTypeStubs` in Pyright/Pylance settings) or wait for a future library update that includes the `py.typed` file.","cause":"The `agentscope-runtime` package is missing a `py.typed` marker file, which prevents static type checkers like Pyright or Pylance from correctly finding and using type stubs.","error":"Pyright reports issue when there is no py.typed file in the package, and it is currently missing. (Error: '找不到 \"agentscope_runtime.engine.helpers.agent_api_builder\" 的 Stub 文件 Pylance (reportMissingTypeStubs)')"}]}