Hyperterse — Agentic server framework.

This guide sets up one A2A agent with explicit tool permissions, then exercises both non-streaming and streaming execution.

Prerequisites

A working Hyperterse project
Hyperterse CLI installed
A model API key in env vars (for this guide, OPENAI_API_KEY)

Configure root defaults

Add agent discovery + conservative tool defaults in .hyperterse:

.hyperterse

name: my-service

agents:
  directory: agents
  tool_access:
    mode: allow_none

allow_none is a good default: agents must opt in to tools explicitly.

Define a tool the agent can use

app/tools/get-orders/config.terse

description: "Get orders by status"
use: primary-db
statement: |
  SELECT id, status, created_at
  FROM orders
  WHERE status = {{ inputs.status }}
inputs:
  status:
    type: string

Define an agent

Create app/agents/support/config.terse:

name: support
description: "Support assistant"
instruction: "Help users with support requests and call tools when useful."
model:
  provider: openai_compatible
  model: gpt-4o-mini
  options:
    base_url: "https://api.openai.com/v1"
tool_access:
  mode: allow_list
  tools:
    - get-orders

If you are unsure what openai_compatible covers, see OpenAI compatibility.

Start runtime

hyperterse start

Verify the route is mounted

curl -s http://localhost:8080/agent/support/.well-known/agent-card.json | jq

You should see an A2A agent card for support.

Execute non-streaming request

Send a v1 A2A JSON-RPC request:

curl -s -X POST http://localhost:8080/agent/support \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "SendMessage",
    "params": {
      "message": {
        "role": "user",
        "parts": [{ "text": "Find pending orders" }]
      }
    }
  }' | jq

Execute streaming request (SSE)

curl -N -X POST http://localhost:8080/agent/support \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "SendStreamingMessage",
    "params": {
      "message": {
        "role": "user",
        "parts": [{ "text": "Summarize pending orders in 3 bullets" }]
      }
    }
  }'

Get a task later

If SendMessage returns a task-shaped result, you can retrieve it later:

curl -s -X POST http://localhost:8080/agent/support \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "GetTask",
    "params": { "id": "<task-id>" }
  }' | jq

Common issues

If your model call fails, verify provider credentials (OPENAI_API_KEY, GOOGLE_API_KEY, or Vertex env vars) are present.

If tool invocation is unexpectedly blocked, verify the agent allowlist and root agents.tool_access defaults in .hyperterse.

Getting started

Foundation

Agents

Tools

Resources

Prompts

Runtime

Databases

Deployment

Security

Quickstart

Prerequisites

Configure root defaults

Define a tool the agent can use

Define an agent

Start runtime

Verify the route is mounted

Execute non-streaming request

Execute streaming request (SSE)

Get a task later

Common issues

​Prerequisites

​Configure root defaults

​Define a tool the agent can use

​Define an agent

​Start runtime

​Verify the route is mounted

​Execute non-streaming request

​Execute streaming request (SSE)

​Get a task later

​Common issues

Prerequisites

Configure root defaults

Define a tool the agent can use

Define an agent

Start runtime

Verify the route is mounted

Execute non-streaming request

Execute streaming request (SSE)

Get a task later

Common issues