SDKs · TypeScript

Run agents & bundles

Use Phrony, PhronyAgent, and PhronyBundle to start sessions and wait for completion.

Phrony is the high-level entry point for agent and bundle sessions. Connect first — see Connect to the runtime.

Phrony

new Phrony(options?)

Create a facade. runtimeAddr and optional credentials match RuntimeClientOptions. The client dials lazily on first use.

TypeScript

import { Phrony } from "@phrony/sdk";

const phrony = new Phrony({ runtimeAddr: "127.0.0.1:7777" });
const agent = phrony.agent("default/my-agent");
// Client dials lazily on first run() or runtimeClient()

Phrony.connect(options?)

Connect eagerly and return a ready instance.

TypeScript

import { Phrony } from "@phrony/sdk";

const phrony = await Phrony.connect({
  runtimeAddr: process.env.PHRONY_RUNTIME_ADDR,
});

// Same options as RuntimeClient: credentials, address via runtimeAddr
phrony.close();

phrony.close()

Close the underlying gRPC client.

TypeScript

import { Phrony, RuntimeClient } from "@phrony/sdk";

const client = await RuntimeClient.connect();
client.close();

const phrony = await Phrony.connect();
phrony.close();

phrony.agent("namespace/name")

Return a PhronyAgent. Accepts namespace/name@version. Bare names without a slash throw AgentRefParseError.

TypeScript

const phrony = await Phrony.connect();

const pinned = phrony.agent("default/my-agent@0.2.0");
const latest = phrony.agent("default/my-agent");

phrony.bundle("namespace/name")

Return a PhronyBundle. Accepts namespace/name@version where version is semver or a lock hash (sha256:…). Bare names without a slash throw BundleRefParseError.

TypeScript

const phrony = await Phrony.connect();

const semver = phrony.bundle("demo/payment-desk@1.0.0");
const lockHash = phrony.bundle("demo/payment-desk@sha256:abc…");
const active = phrony.bundle("demo/payment-desk");

phrony.runtimeClient()

Return the lazily connected RuntimeClient.

TypeScript

import { Phrony } from "@phrony/sdk";

const phrony = await Phrony.connect();
const client = await phrony.runtimeClient();
const agents = await client.listAgents();

PhronyAgent

run(options?)

Start a session. wait: true (default) streams until completed; wait: false uses unary RunSession and returns immediately.

TypeScript

import { Phrony } from "@phrony/sdk";

const phrony = await Phrony.connect();

const result = await phrony.agent("default/my-agent").run({
  input: { claimId: "CLM-48219" },
  resolvedSecrets: { openai: process.env.OPENAI_API_KEY },
});

console.log(result.sessionId, result.output, result.stopReason);
phrony.close();

run({ wait: false })

Fire-and-forget session start.

TypeScript

import { Phrony } from "@phrony/sdk";

const phrony = await Phrony.connect();

const result = await phrony.agent("default/my-agent").run({
  input: { claimId: "CLM-48219" },
  wait: false,
});

console.log(result.sessionId, result.status);

runInteractive(options?)

Open RunSessionInteractive without waiting. Consume events() and call close() when done.

TypeScript

import { Phrony } from "@phrony/sdk";

const phrony = await Phrony.connect();

const session = await phrony.agent("default/my-agent").runInteractive({
  input: { question: "Summarize claim CLM-48219" },
});

for await (const event of session.events()) {
  if (event.type === "text_delta") process.stdout.write(event.delta);
}
session.close();

PhronyBundle

Multi-agent systems published as a Bundle run through the bundle root member. PhronyBundle mirrors PhronyAgent — same run() options and AgentSessionError on failure.

run(options?)

Start a session on the bundle root. wait: true (default) streams until completed; wait: false uses unary RunSession with bundleRef.

TypeScript

import { Phrony } from "@phrony/sdk";

const phrony = await Phrony.connect();

const result = await phrony.bundle("demo/payment-desk").run({
  input: { message: "Pay 500 USD to Acme" },
  resolvedSecrets: { stripe: process.env.STRIPE_API_KEY },
});

console.log(result.sessionId, result.output, result.stopReason);
phrony.close();

run({ wait: false })

Fire-and-forget bundle session start.

TypeScript

import { Phrony } from "@phrony/sdk";

const phrony = await Phrony.connect();

const result = await phrony.bundle("demo/payment-desk").run({
  input: { message: "Pay 500 USD to Acme" },
  wait: false,
});

console.log(result.sessionId, result.status);

runInteractive(options?)

Open RunSessionInteractive with bundleRef without waiting.

TypeScript

import { Phrony } from "@phrony/sdk";

const phrony = await Phrony.connect();

const session = await phrony.bundle("demo/payment-desk").runInteractive({
  input: { message: "Pay 500 USD to Acme" },
});

for await (const event of session.events()) {
  if (event.type === "text_delta") process.stdout.write(event.delta);
}
session.close();

For streaming event types, see Interactive sessions. On failure with wait: true, run() throws AgentSessionError — see Utilities.