Run advisory checks against an agent shape

POST

/v1/agents/analyze

const url = 'https://app.everruns.com/api/v1/agents/analyze';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"capabilities":[{"config":{},"ref":"current_time"},{"config":{},"ref":"test_math"}],"mcpServers":{"additionalProperty":{"args":["example"],"auth_mode":"none","command":"example","env":{"additionalProperty":"example"},"headers":{"additionalProperty":"example"},"oauth_provider_id":"example","tool_discovery":true,"type":"http","url":"example"}},"system_prompt":"You are a helpful customer support agent.","tools":[{}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://app.everruns.com/api/v1/agents/analyze \
  --header 'Content-Type: application/json' \
  --data '{ "capabilities": [ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "test_math" } ], "mcpServers": { "additionalProperty": { "args": [ "example" ], "auth_mode": "none", "command": "example", "env": { "additionalProperty": "example" }, "headers": { "additionalProperty": "example" }, "oauth_provider_id": "example", "tool_discovery": true, "type": "http", "url": "example" } }, "system_prompt": "You are a helpful customer support agent.", "tools": [ {} ] }'

Runs built-in rules plus on-demand LLM analysis (specs/agent-checks.md) and returns merged advisory findings. Requires the system utility LLM service to be configured.

Request Body^required

application/json

Request to preview the final agent shape with capabilities applied

object

capabilities

Capabilities to apply with per-agent configuration.

Array<object>

Per-agent capability configuration

Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.

object

config

Per-agent configuration for this capability (capability-specific)

ref

required

Reference to the capability ID

string

Example

[
  {
    "config": {},
    "ref": "current_time"
  },
  {
    "config": {},
    "ref": "test_math"
  }
]

mcpServers

Remote MCP servers scoped to the previewed agent.

object

key

additional properties

Session-, agent-, or harness-scoped remote MCP server configuration.

This intentionally mirrors the mcpServers object shape used by common MCP client config files while staying within Everruns’ current remote-HTTP-only support.

object

args

Arguments passed to the stdio command.

Array<string>

auth_mode

Authentication mode used when executing tools from this scoped server.

string

Allowed values: none api_key o_auth

Example

api_key

command

Executable to spawn for a stdio transport server.

string | null

env

Environment variables set for the stdio command.

object

key

additional properties

string

headers

Additional HTTP headers sent on MCP requests (HTTP transport only).

object

key

additional properties

string

oauth_provider_id

Provider id used to resolve a user-scoped bearer token.

string | null

tool_discovery

Whether to discover tool definitions live from this server.

boolean

type

MCP transport type. Only remote HTTP is supported today.

string

Allowed values: http stdio

Example

http

url

URL of the remote MCP server endpoint. Required for HTTP transport; empty/ignored for stdio.

string

system_prompt

required

The base system prompt (before capability additions)

string

Example

You are a helpful customer support agent.

tools

Client-side tools to include in the preview.

Array<object>

object

Responses

200

Agent analysis completed

application/json

Response from on-demand agent analysis (built-in rules + LLM checkers)

object

findings

required

Advisory findings, built-in and LLM-sourced (specs/agent-checks.md)

Array<object>

A single advisory finding about an agent configuration.

object

category

required

string

Allowed values: structure completeness effectiveness safety cost

fix

Proposed replacement text (phase 2+; always absent for builtin rules).

string | null

location

One of:

null
object

null

Pointer to the config field (and optional byte span within it) a finding refers to.

object

end

integer | null format: int32

field

required

Config field name, e.g. system_prompt, tools.

string

start

Byte offset range into the field’s authored text, when applicable.

integer | null format: int32

message

required

Human-readable explanation. Safe to render in user-facing messages.

string

rule_id

required

Stable rule identifier, e.g. prompt.duplicate_paragraphs.

string

severity

required

Advisory severity. There is deliberately no error: checks never gate save/publish (specs/agent-checks.md, Non-Goals).

string

Allowed values: warning info suggestion

source

required

Which tier produced the finding.

string

Allowed values: builtin llm health_check

Example

{
  "findings": [
    {
      "category": "structure",
      "severity": "warning",
      "source": "builtin"
    }
  ]
}

400

Utility LLM service not configured

application/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object

allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null

method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null

rel

required

Link relation describing the action. Closed vocabulary documented in specs/api-conventions.md — examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string

schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

500

Internal server error

application/json

Standard error response.

object

allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

href

string | null

method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null

rel

required

string

schema_ref

string | null

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

Run advisory checks against an agent shape

Request Body required

Example

Example

Example

Example

Responses

200

Example

400

Example

500

Example

Request Body^required