Static Observability

Static observability allows you to analyze an agent's topology, connected tools, and security posture before deployment by uploading its source code directly to the platform.

Upload Agent Project

Navigate to the Observability tab and select Upload. You can submit your agent code in two ways:

• Local File — drag and drop or browse to upload an archive (.zip, .tar, .tar.gz, .tar.bz2, .tar.xz)
• GitHub URL — provide a link to a public or private GitHub repository for direct ingestion

Once submitted, the platform performs structural analysis and security scanning on the agent project. Completed scans appear in the Scan History list below the upload panel, tagged with the agent framework detected, the source type (Local or GitHub), and the scan status.

Agent Structure

Navigate to the Observability -> Structure Observability tab and you can see the static scan results.

Click the detail of each agent, you can see the detailed agent structure and connected tools of that agent.

---

API Reference

Observability scan endpoints are served by the standalone Observability service. All endpoints accept JWT (Authorization: Bearer <jwt>) or an API key (X-API-Key: <api_key>).

Upload endpoints return 202 Accepted immediately and run analysis in the background — poll GET /api/v1/observability/scans/{scan_id} for the result.

POST /api/v1/observability/upload

Upload a local archive (.zip, .tar.gz) for VirtueHarbor structure analysis and MCP Guard security scanning. Returns 202 Accepted.

Request: multipart/form-data

Field	Type	Required	Description
file	file	Yes	Archive file to scan
framework	string	Yes	Agent framework (e.g. langchain, openai, adk)

Response:

{
  "scan_id": "scan_20260519_langchain_file_myagent",
  "status": "processing",
  "mcpguard_scan_id": null
}

POST /api/v1/observability/upload/github

Clone a GitHub repository and scan it. Returns 202 Accepted.

Request:

{
  "github_url": "https://github.com/my-org/my-agent",
  "revision": "main",
  "framework": "langchain"
}

Field	Type	Required	Description
github_url	string	Yes	Full GitHub repository URL
revision	string	No	Branch, tag, or commit SHA (defaults to the repo's default branch)
framework	string	Yes	Agent framework

GET /api/v1/observability/scans

List all scans (metadata only, no graph data).

Query parameters:

Parameter	Description
framework	Filter by agent framework
status	Filter by scan status (processing, completed, failed)

GET /api/v1/observability/scans/{scan_id}

Get a single scan with full graph data. Poll this after submitting an upload to check whether processing has finished.

Response (completed):

{
  "scan_id": "scan_20260519_langchain_file_myagent",
  "status": "completed",
  "framework": "langchain",
  "filename": "myagent.zip",
  "source": "file",
  "created_at": "2026-05-19T10:30:00Z",
  "graph": { }
}

DELETE /api/v1/observability/scans/{scan_id}

Delete a scan.

Response:

{ "message": "Scan deleted" }