Ory Argus: Agent and Developer Experience

The core API behind every Ory Agent Plugin and Extension. Argus wraps Ory Identities, Ory Permissions, MCP authorization, and distributed tracing into a single client. Each harness package (@ory/claude-code, @ory/codex, @ory/gemini-cli, and the rest — see the root README for the full list) is a thin adapter that maps one harness's hook contract onto Argus.

Argus is also published on its own so you can build new harness plugins or extensions, embed Ory into a custom agent runtime, or instrument any SDK that exposes event lifecycle hooks for session start, tool execution, and tool completion.

Use

import { OryAgentClient } from "@ory/argus";

const client = OryAgentClient.fromEnv("my-harness");

const session = await client.verifySession(sessionToken);

const result = await client.checkPermission({
  namespace: "AgentTools",
  object: "Bash",
  relation: "use",
  subjectId: `session:${sessionId}`,
});

if (!result.allowed) {
  // block the tool call (or fail-open on result.error)
}

fromEnv() returns a working client even when ORY_PROJECT_URL is unset; calls fail with network_error and the fail-open path handles them.

Build a new plugin, extension, or custom integration

Any agent runtime, framework, or SDK that exposes lifecycle hooks for session start, tool execution, and tool completion can use Argus as its authentication, authorization, and audit layer. The integration contract is the same three calls every plugin in this repo makes:

import {
  OryAgentClient,
  ensureUserAuthenticated,
  ensureAgentIdentity,
} from "@ory/argus";

const client = OryAgentClient.fromEnv("my-harness");

// 1. Session start: authenticate the human and the agent process.
async function onSessionStart() {
  await ensureUserAuthenticated(client, {
    binName: "my-harness",
    harness: "my-harness",
    allowBlock: true,
  });
  await ensureAgentIdentity(client, {
    projectUrl: process.env.ORY_PROJECT_URL,
  });
}

// 2. Before each tool call: check Ory Permissions; block on `deny`.
async function onBeforeTool(toolName: string, sessionId: string) {
  const result = await client.checkPermission({
    namespace: "AgentTools",
    object: toolName,
    relation: "use",
    subjectId: `session:${sessionId}`,
  });
  if (result.allowed === false) {
    return { block: true, reason: result.reason };
  }
}

// 3. After each tool call: record a structured trace span.
async function onAfterTool(toolName: string, durationMs: number) {
  client.tracer.record("tool.complete", { toolName, durationMs });
}

Map the host SDK's or harness's hook names onto those three calls and you get the same identity, policy, and audit story as every published plugin in this repo. Subprocess hosts can additionally block via exit codes; in-process hosts can return decision objects directly.

Surface

OryAgentClient

The wrapped Ory client. One instance per harness session.

Identity gates

Resolve the user and agent identities at session start. Non-blocking by default; opt in to hard blocking on the user gate where the host can carry an exit-style decision.

Tracer

Tracer is exposed as client.tracer. Records every decision as a structured span.

• record(event, attrs): emit a span
• EventEmitter "span" events for live observers
• NDJSON file output
• OTLP / HTTP export

Logger

• DebugLogger: structured JSON to stderr plus optional log file
• Gated by ORY_AGENT_DEBUG

Skill and command catalog

Materialize the canonical SKILL.md templates into each harness's native skill or command format.

CLI and dev tooling

• Shared CLI handlers used by every plugin's CLI: configure, status, local, setup
• runDevLauncher(...): the dev-launcher pipeline used by every plugin
• Local-stack manager: brings up a local Ory instance in Docker Compose
• Verdaccio registry manager: a local npm registry for dev launchers

License

Apache-2.0