@veridex/agents-react

React provider and hooks for building UIs on top of the Veridex agent runtime.

Status

@veridex/agents-react is implemented and usable, but it is still evolving with the core runtime. The goal is to make agent state easy to consume in apps without hiding important runtime behavior behind opaque abstractions.

What This Package Does

Use @veridex/agents-react when you want React-native access to:

• the current agent runtime
• run state and run results
• trace and turn events
• approval queues
• memory and context plans
• budget and payment state
• agent identity and reputation helpers
• OpenClaw bridge helpers inside a UI

Installation

npm install @veridex/agents-react @veridex/agents react react-dom

If you want OpenClaw bridge helpers, also install:

npm install @veridex/agents-openclaw

Quick Start

import { AgentProvider, useRun, useApprovals, useTrace } from '@veridex/agents-react';
import { createAgent, OpenAIProvider } from '@veridex/agents';

const runtime = createAgent(
  {
    id: 'support-agent',
    name: 'Support Agent',
    model: { provider: 'openai', model: 'gpt-4o-mini' },
    instructions: 'Help support operators clearly and safely.',
  },
  {
    modelProviders: {
      openai: new OpenAIProvider({
        apiKey: process.env.OPENAI_API_KEY,
      }),
    },
    enableTracing: true,
  },
);

function AgentConsole() {
  const { run, state, result, isRunning } = useRun();
  const { pending, approve, deny } = useApprovals();
  const { events } = useTrace();

  return (
    <div>
      <button disabled={isRunning} onClick={() => void run('Summarize the latest support issue')}>
        Run agent
      </button>
      <p>State: {state}</p>
      <p>Pending approvals: {pending.length}</p>
      <p>Trace events: {events.length}</p>
      <pre>{result?.output}</pre>

      {pending.map((request: any) => (
        <div key={request.id}>
          <button onClick={() => approve(request.id, 'ops')}>Approve</button>
          <button onClick={() => deny(request.id, 'Denied by ops', 'ops')}>Deny</button>
        </div>
      ))}
    </div>
  );
}

export function App() {
  return (
    <AgentProvider runtime={runtime} definition={runtime.definition}>
      <AgentConsole />
    </AgentProvider>
  );
}

Provider Model

AgentProvider accepts either:

• definition plus optional options, and it will create the runtime for you
• a prebuilt runtime if your app creates and owns the runtime elsewhere

That keeps the package flexible for:

• simple local UI prototypes
• server-created runtimes passed into React
• enterprise apps that connect React views to long-lived runtimes

Hook Overview

| Hook | Use it for | |---|---| | useAgent | Get the runtime, definition, event bus, tools, memory, approvals, and policy engine | | useRun | Start runs and observe state, result, error, and collected events | | useTurnStream | Observe model-call completions and tool execution stream state | | useApprovals | Read pending approvals and resolve them from the UI | | useTrace | Access emitted trace events and filter them in your own components | | useToolRegistry | Inspect or register tools against the runtime tool registry | | useMemory | Read and manipulate runtime memory through the hook layer | | useBudget | Track spend and token usage across runs | | useContextPlan | Read the latest compiled context plan for a run | | usePayments | Inspect payment availability, run spend, and budget checks | | useAgentIdentity | Load identity and wallet information exposed by the runtime integrations | | useAgentReputation | Query reputation and discovery helpers from the payments adapter | | useOpenClawBridge | Use OpenClaw bridge helpers from React and register imported tools |

Useful Patterns

Run state and output

const { run, state, result, error, reset } = useRun();

Use this when you need a lightweight "chat" or "execute task" UI without rebuilding state machines around the runtime.

Approval inbox

const { pending, approve, deny, decisions } = useApprovals();

Use this when your agent can hit approval-gated actions and you want a human-in-the-loop console.

Budget and payment visibility

const { budget, setLimit, limit } = useBudget();
const { isAvailable, runSpendUSD, checkBudget } = usePayments();

Use these hooks when:

• the agent can spend money
• you need a UI budget guardrail
• you want to show operators what a run has consumed

Context introspection

const { plan } = useContextPlan();

Use this to explain what runtime context the model actually received. That is helpful for debugging prompt assembly, memory recall, and runaway context growth.

Identity and reputation

const { identity, wallet, agentId } = useAgentIdentity();
const { getScore, discover } = useAgentReputation();

These hooks are only useful when the runtime has been wired to the Veridex lower-layer integrations, but they let you build richer trust-aware and commerce-aware interfaces without custom adapter code in every app.

OpenClaw Bridge in React

If you install @veridex/agents-openclaw, you can bind the bridge into a component:

import * as openclaw from '@veridex/agents-openclaw';
import { useOpenClawBridge } from '@veridex/agents-react';

function BridgeTools() {
  const { importSkillDocument, registerTool } = useOpenClawBridge(openclaw);

  async function importSkill(raw: string) {
    const document = openclaw.parseSkillDocument(raw, 'SKILL.md');
    const { tool } = openclaw.importSkillDocument(document);
    registerTool(tool);
  }

  return null;
}

Related Packages

| Package | Use it with | |---|---| | @veridex/agents | Required runtime package | | @veridex/agents-openclaw | Optional OpenClaw bridge helpers in React | | @veridex/agents-control-plane | Approval, trace, and governance UIs backed by a remote service |

Known Rough Edges

• Hook APIs will likely keep tightening as more real apps land on the framework.
• This package is intentionally thin, so complex app orchestration is still your responsibility.
• Some hooks are only meaningful when the runtime has been wired with the relevant lower-layer integrations.

Contributions are welcome, especially around better examples, streaming UX patterns, and richer operator console examples.