Sawra/runagent cloud support wip

[sawradip]

Summary by CodeRabbit

• New Features

  • Added streaming execution support (CLI run_stream and SDK/client).
  • Revamped run endpoints with structured responses and streaming over WebSocket.
  • Enhanced deployment with progress bars, validation, and new APIs to run agents and fetch architecture.
  • Updated template entrypoints for sync and streaming usage.

• Refactor

  • Standardized CLI error handling and messages; path-based arguments with stricter validation.
  • Added agent fingerprinting and remote-agent management to prevent duplicates.

• Chores

  • Updated ignore list to include test.md.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Adds streaming run support across CLI, client, server, and schema; refactors REST/socket clients and server handlers to new request/response formats; introduces fingerprint/is_local agent metadata and revised deployment with metadata+zip flows; updates auth validation; adjusts templates’ entrypoints; standardizes error handling and path/Path usage.

Changes

Cohort / File(s)	Summary of Changes
Ignore Rules \.gitignore	Added test.md to ignore list; whitespace/newline tweak around parlant-data.
CLI Commands & Wiring runagent/cli/commands.py, runagent/cli/main.py	New run_stream command; standardized error formatting via format_error_message; DISABLE_TRY_CATCH gating; improved arg parsing/validation; Path-based inputs; consistent sys.exit(1) on failures; main registers run_stream.
Client Interfaces (High-level + Socket + REST) runagent/client/client.py, runagent/sdk/socket_client.py, runagent/sdk/rest_client.py	Added RunAgentClient.run_stream; refactored to JSON-based websocket protocol /run-stream; REST client gains is_local, progress utilities, core upload/start helpers, run_agent, get_agent_architecture, upload_agent_metadata_and_zip; deploy flow adds fingerprinting and duplicate handling.
SDK & Deployment runagent/sdk/sdk.py, runagent/sdk/deployment/remote.py, runagent/sdk/config.py, runagent/sdk/db.py	upload_agent now accepts Path; remote upload renamed upload_agent_to_server(Path) and targets metadata+zip API; auth test switched to token validation endpoint; DB adds is_local, fingerprint, lookup/update helpers, and add_remote_agent.
Server: HTTP & WebSocket runagent/sdk/server/local_server.py, runagent/sdk/server/socket_utils.py	New POST /api/v1/agents/{id}/run returning AgentRunResponseV2; websocket /api/v1/agents/{id}/run-stream with JSON payload {entrypoint_tag,input_args,input_kwargs}; revamped invocation tracking, middleware sync, and structured success/error responses.
Schema & Serialization runagent/utils/schema.py, runagent/utils/serializer.py	Removed AgentInputArgs; rewrote AgentRunRequest/WebSocketAgentRequest to args/kwargs; added ExecutionData, ErrorDetail, AgentRunResponseV2; deserializer now returns original string on JSON decode failure (when try/catch enabled).
Templates (LangGraph) templates/langgraph/default/agents.py, templates/langgraph/default/runagent.config.json	Added app_invoke and app_stream entry functions; config switches modules from app.invoke→app_invoke and app.stream→app_stream.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant CLI as CLI (run_stream)
  participant RAC as RunAgentClient
  participant SC as SocketClient
  participant Srv as Local Server
  participant WS as WebSocket

  User->>CLI: run_stream --id <agent_id> --tag <..._stream>
  CLI->>RAC: run_stream(args, kwargs)
  RAC->>SC: connect /api/v1/agents/{id}/run-stream?token=...
  SC->>Srv: WebSocket OPEN
  SC->>WS: send JSON {entrypoint_tag, input_args, input_kwargs}
  alt Valid streaming entrypoint
    WS-->>SC: status stream_started
    loop chunks
      WS-->>SC: data {chunk}
      SC-->>CLI: yield chunk
    end
    WS-->>SC: status stream_completed
    SC-->>RAC: complete
    RAC-->>CLI: done
  else Error
    WS-->>SC: error {message, code}
    SC-->>RAC: raise
    RAC-->>CLI: formatted error
  end

Loading

sequenceDiagram
  autonumber
  participant CLI as CLI (run)
  participant RAC as RunAgentClient
  participant RC as RestClient
  participant Srv as Local Server (HTTP)

  CLI->>RAC: run(agent_id, tag, args, kwargs)
  RAC->>RC: POST /api/v1/agents/{id}/run {entrypoint_tag,input_args,input_kwargs}
  RC->>Srv: Request
  alt Success
    Srv-->>RC: AgentRunResponseV2 {data: ExecutionData}
    RC-->>RAC: unwrap result_data/output_data
    RAC-->>CLI: result
  else Failure
    Srv-->>RC: AgentRunResponseV2 {error: ErrorDetail}
    RC-->>RAC: error info
    RAC-->>CLI: formatted error/exit
  end

Loading

sequenceDiagram
  autonumber
  participant CLI as CLI (deploy/upload)
  participant SDK as RunAgentSDK
  participant RD as RemoteDeployment
  participant RC as RestClient
  participant DB as Local DB

  CLI->>SDK: upload_agent(Path)
  SDK->>RD: upload_agent_to_server(Path)
  RD->>RC: upload_agent_metadata_and_zip(Path)
  RC->>RC: validate + fingerprint
  RC->>DB: check by fingerprint/path
  alt Duplicate detected
    RC-->>RD: decision path (overwrite/new/cancel)
  else New content
    RC->>RC: _upload_agent_metadata_core
    RC->>RC: _upload_agent_zip_file_core
    RC-->>RD: upload complete
  end

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related PRs

• Sawra/runagent cloud support #69 — Overlapping changes across SDK DB, REST client, schema, socket utilities, and streaming support; likely part of the same streaming/deploy refactor.
• Sawra/runagent cloud support wip #71 — Also updates streaming run paths and client/server/schema surfaces in tandem with this PR.
• Support: Add middleware API integration for local CLI #58 — Touches the same streaming/websocket layers but with a different message protocol; relevant for protocol migration context.

Poem

A hare taps keys with nimble grace,
Streams now sing in real-time pace.
New schemas bloom, responses neat,
Fingerprints guide agent feet.
Deploy zips hum, progress bars gleam—
I thump with joy at this streaming dream! 🐇✨

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch sawra/runagent_cloud_support_wip

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c7fea99 and 3ae79c5.

📒 Files selected for processing (17)

• .gitignore (1 hunks)
• runagent/cli/commands.py (11 hunks)
• runagent/cli/main.py (1 hunks)
• runagent/client/client.py (1 hunks)
• runagent/sdk/config.py (2 hunks)
• runagent/sdk/db.py (3 hunks)
• runagent/sdk/deployment/remote.py (2 hunks)
• runagent/sdk/rest_client.py (21 hunks)
• runagent/sdk/sdk.py (2 hunks)
• runagent/sdk/server/local_server.py (5 hunks)
• runagent/sdk/server/socket_utils.py (7 hunks)
• runagent/sdk/socket_client.py (2 hunks)
• runagent/sdk/template_manager.py (2 hunks)
• runagent/utils/schema.py (2 hunks)
• runagent/utils/serializer.py (1 hunks)
• templates/langgraph/default/agents.py (1 hunks)
• templates/langgraph/default/runagent.config.json (1 hunks)

---

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 and usage tips.}