Testing & Debugging

Building reliable autonomous agents requires rigorous testing. OpenHive provides a suite of tools to test your agents locally, simulate cloud environments, and interact with them via the CLI.

The `exec` Command

The primary way to interact with an agent is the hive exec command. This universal client can talk to any A2A-compliant agent, whether it's running on your laptop or deployed to the OpenHive Cloud.

Basic Usage

Send a simple text message to an agent:

hive exec --agent <agent-name> --message "Your prompt here"

Interactive Mode

If you omit the --agent or --message flags, the CLI enters an interactive wizard mode.

hive exec

What happens next:

Select Registry: You choose between Local (SQLite) or OpenHive Platform.
Select Agent: The CLI lists available agents from the selected registry.
Enter Message: Type your prompt.

Testing Locally

You don't need to deploy to the cloud to test your agent.

Start Local Registry

Run the local OpenHive stack. This spins up a local registry server that mimics the production environment.

hive up

The registry will be available at http://localhost:3000.

Publish Locally

In your agent's project directory, publish it to your local registry.

hive publish --local

Execute Locally

Use the exec command and select Local (SQLite) when prompted.

hive exec
? Select registry source: Local (SQLite)
? Select an agent to execute: my-local-agent
? Enter message: Hello!

Testing Remote Agents

You can also use the CLI to test agents deployed to the cloud or a private cluster.

OpenHive Cloud

To test an agent on the public platform, simply login and run exec.

hive login
hive exec --agent weather-bot --message "What's the weather in Tokyo?"

Private/Custom Registry

If you are running a self-hosted OpenHive cluster, you can point the CLI to your custom registry URL.

hive exec \
  --registry https://registry.internal.corp.com \
  --agent internal-audit-bot \
  --message "Generate report"

Debugging Tips

Inspect Network Traffic

Agents communicate over standard HTTP. You can use tools like Wireshark or Proxyman to inspect the JSON payloads being sent to and from your agent's endpoint.

Verbose Logging

When running your agent locally with hive start, all logs are output to stdout. Look for [A2A] prefixes to see protocol-level events.

Unit Testing

Since OpenHive agents are just classes, you can write standard Jest (Node) or Pytest (Python) unit tests for your AgentExecutor logic without spinning up a server.

Unit Test Example (Node.js)

import { MyExecutor } from './agent';

test('MyExecutor replies correctly', async () => {
  const executor = new MyExecutor();
  const mockBus = { publish: jest.fn(), finished: jest.fn() };
  
  await executor.execute(mockContext, mockBus);
  
  expect(mockBus.publish).toHaveBeenCalledWith(
    expect.objectContaining({
      parts: [{ text: "Hello World" }]
    })
  );
});

Testing & Debugging

Inspect Network Traffic

Verbose Logging

Unit Testing

On this page