Agent quickstart

From preview access to a governed agent call.

Install the CLI from your preview bundle, bind a scoped agent credential, configure your model client, and run a typed tool call. The agent works behind the same approval boundary your humans do.

Request early preview Read the runtime

Steps

Preview setup has five checkpoints.

We send the endpoint, workspace, and scoped credential path. Your model client connects to KarmanFlow through MCP; policy and approvals stay on the platform side.

1. Request early preview

# Preview access includes the kf CLI installer,
# tenant id, endpoint, and hosted credentials.
kf version --pretty

2. Log in and pick a tenant

# Preview workspaces are addressed by tenant id in the API.
kf login --oauth \
  --endpoint https://api.karmanflow.com/graphql \
  --tenant tnt_acme_apparel \
  --environment staging

kf profile show --pretty

3. Bind a scoped credential to the agent client

# Create a SERVICE or AGENT-scoped API key in workspace admin.
# The kf CLI does not create agent identities yet.
printf '%s' "$KARMANFLOW_AGENT_KEY" | \
kf login --profile receiving-bot \
  --endpoint https://api.karmanflow.com/graphql \
  --tenant tnt_acme_apparel \
  --environment staging \
  --api-key-stdin

kf auth status --profile receiving-bot --pretty

4. Configure your model client

# Claude Desktop, OpenAI Responses, or any MCP client
{
  "mcpServers": {
    "karmanflow": {
      "url": "https://api.karmanflow.com/mcp",
      "headers": {
        "Authorization": "Bearer $KARMANFLOW_AGENT_KEY",
        "X-KarmanFlow-Tenant": "$KARMANFLOW_TENANT_ID",
        "X-KarmanFlow-Env": "staging"
      }
    }
  }
}

5. Run a typed tool call

# In Claude Desktop or your client, ask the model:
#   "Create a reservation for 2 units of var_tshirt_sm at loc_edison_nj"
#
# The model calls karmanflow.inventory.command.CreateReservation. Policy runs.
# The receipt comes back to the agent and to the operator timeline.
kf receipts list --tenant tnt_acme_apparel --environment staging \
  --actor-id agt_receiving_bot --limit 20 --pretty

Receipt preview

What comes back after the call.

The response should show status, receipt ID, actor, policy outcome, and events. The quickstart keeps the preview short; the developer reference carries the full payload shape.

// Receipt preview
{
  "status": "SUCCEEDED",
  "receipt": {
    "id": "cmd_01HZ8GDV6Z...",
    "reservationId": "rsv_01HZ8GDV6ZA2VTYE1WJ5N8K2A0G",
    "actor": "agent",
    "policy": "approved",
    "events": ["reservation created"],
    "timeline": "available in operator console"
  }
}

Going further

Read the runtime, then design the agent.

The runtime page walks the four layers between an agent's tool call and a recorded operating event. Read it before wiring an agent into anything that writes.

Read the runtime Talk to us