Quickstart

This is the fastest first-success path: create an agent, dispatch a goal, and optionally store a manual learning.

Minimal flow

curl -X POST "https://api.hyperstruck.com/agents" \
  -H "Authorization: Bearer <YOUR_HYPERSTRUCK_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Execution Assistant",
    "core_config": { "instructions": "You are a helpful sales execution assistant." }
  }'

curl -X POST "https://api.hyperstruck.com/agents/<AGENT_ID>/goals" \
  -H "Authorization: Bearer <YOUR_HYPERSTRUCK_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Create a follow-up sales execution plan for a call with client XYZ" }'

from hyperstruck import Hyperstruck

hs = Hyperstruck(api_key="<YOUR_HYPERSTRUCK_API_KEY>")

agent = hs.agents.create(
    name="Sales Execution Assistant",
    instructions="You are a helpful sales execution assistant.",
)

run = agent.run("Create a follow-up plan for the client XYZ call")
print(run.result)

curl -X POST "https://api.hyperstruck.com/agents/<AGENT_ID>/learnings" \
  -H "Authorization: Bearer <YOUR_HYPERSTRUCK_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "qualify_lead returns cold for cybersecurity companies",
    "applicable_tools": ["qualify_lead"],
    "instances": [
      {
        "entity_values": {
          "company": "CrowdShield",
          "industry": "cybersecurity"
        },
        "outcome": {
          "tier": "cold",
          "score": "0.12"
        }
      }
    ]
  }'

/hyper-reasoning Create a follow-up sales execution plan for a call with client XYZ
/hyper-learning search client XYZ decision makers
/hyper-learning store

Common next knobs

• Agent creation optional fields: description, status (defaults to active), reasoning_profile (defaults to full), home_space_id, and everything inside core_config. See Agent configuration for instructions, tools, guardrails, and approval gates.
• Goal dispatch optional fields: context, session_id, worker_profile, metadata
• Manual learning optional fields: utility, source_goal, applicable_goals, applicable_tools, privacy, instances

Run Hyperstruck Engine in your own process

The hosted API above dispatches goals to Hyperstruck Engine for you. If you are running it yourself, start by checking your setup. You do not choose models: every reasoning component runs a model benchmarked for that component's job, pinned, with no silent substitution when one is unavailable.

pip install hyperstruck-core
hyperstruck doctor

The doctor reports everything at once rather than failing on the first problem it meets:

Provider keys      OPENAI_API_KEY  ok
                   GROQ_API_KEY    missing  (planner, plan validator, final composer)
Embedder           nomic-embed-text, 768 dimensions  ok
Innate corpus      not seeded for this embedder
Services           Qdrant unreachable at localhost:6333

Once the report is clean, dispatch a goal:

agent = create_agent(
    AgentConfig(
        name="Collections",
        instructions="You work through collections tasks using the available tools.",
    )
)
agent.register_tool(fetch_overdue)
agent.register_tool(send_reminder)

result = await agent.run(goal="Run month-end collections")

result.success            # True only when the completion gate could ground it
result.is_quality_passed  # final reflection's verdict on the work itself
result.incomplete_reason  # machine-readable on refusal, e.g. UNGROUNDED_CLAIM

The run decomposes into milestones, validates the plan before any tool fires, executes, reflects and revises. Memory and learning are separate services you pass in when you want them. A reasoning run does not require any of them.

When to upload credentials

You usually do not need provider credentials for the first run because Hyperstruck provides a platform default. Upload credentials only when you want model billing or endpoint control under your own account. This is a billing and routing choice, not a model choice.

Resolution order is: a matching active agent_override for the agent, then a matching active tenant_default, then the platform default. It decides whose account is billed and which endpoint is called, never which model runs.

Related pages