Step-by-step guide for using the entire platform

If you are brand new to the platform, follow this exact sequence first.

1. 1
   Create or access your account

   Use Sign up to create a new account, or Sign in if your admin already invited you. If you received an invite link, open it first to attach your membership to the correct organization.

2. 2
   Complete onboarding

   Create your organization (or confirm the invited org), then create your first agent so the platform can route you into the main console experience.

3. 3
   Verify access to key sections

   Open Dashboard, Agents, Runs, and Approvals. Owners/Admins should also verify Team, API Keys, and Webhooks are visible and working.

4. 4
   Pick your first success path

   For business users: create and run an agent. For technical users: create an API key and test the Platform API. For operations users: configure webhooks and approvals.

Understanding access levels helps prevent confusion during setup and approval workflows.

The onboarding flow is designed to get you to a usable console quickly.

1. 1
   Step 1 — Organization

   Enter a clear organization name. Use a stable naming convention (for example, “Acme Operations” instead of temporary project nicknames) so audits, exports, and team invites remain easy to track later.

2. 2
   Step 2 — First agent

   Create a first agent with a simple, testable purpose such as summarization, triage, extraction, or QA. Keep the first version focused; you can add tools and workflow orchestration after the baseline run works.

3. 3
   Step 3 — Ready

   You will land on the Dashboard. From here, continue into Agents to refine the agent, or into Team/API Keys if another teammate or external integration needs access.

Use the dashboard as your operational overview before drilling into detailed pages.

1. 1
   Review activity and status cards

   Check high-level metrics and recent activity to confirm your org is active and no queue/backlog issue is preventing runs from completing.

2. 2
   Jump to the next action

   Use the dashboard links to open Agents, Runs, Workflows, Approvals, or Team depending on your current objective.

3. 3
   Use dashboard as a daily checklist

   Many teams begin each day by scanning pending approvals, failed runs, and webhook delivery status before making changes to agents or workflows.

Agents are versioned execution units. Use versions to keep behavior reproducible while improving prompts and tool access over time.

Knowledge pages let you manage documents and retrieval inputs used by agents and workflows.

1. 1
   Open Org → Knowledge

   Review documents already added to your org. Confirm the source set is correct before relying on retrieval in production agents.

2. 2
   Add or update documents

   Upload source material or connect content according to your org process. Use clear titles and ownership tags so operators can identify stale documents quickly.

3. 3
   Validate retrieval relevance

   Run a knowledge search or a test run using representative queries. Confirm the returned chunks are accurate, current, and safe to use in downstream outputs.

4. 4
   Retire stale knowledge

   Remove, replace, or supersede old documents when business rules change to avoid incorrect answers and accidental policy drift.

Tools extend agents with structured actions (e.g., HTTP calls, external systems). Treat tool setup like production integration work.

1. 1
   Open Org → Tools and create a tool

   Define the tool name and purpose so reviewers understand exactly what action the agent may take using this integration.

2. 2
   Configure endpoint/method/schema

   Provide the request details (URL, method, headers, payload schema) and validate the expected inputs/outputs before enabling the tool on agents.

3. 3
   Store secrets securely

   Never paste credentials into prompts. Use the platform’s tool secret handling so tokens and keys are encrypted and not shown in normal UI views.

4. 4
   Apply approvals for risky actions

   If the tool can mutate external systems, enable approvals so humans review intent before execution completes.

Runs are your primary execution record for prompts, tool calls, outputs, and debugging.

Workflows coordinate multi-step execution. Use them for repeatable, auditable automation that spans prompts and tools.

1. 1
   Open Org → Workflows and create a workflow

   Name the workflow by business outcome (for example: “Weekly pipeline digest + anomaly review”) and define a clear owner for operational accountability.

2. 2
   Add steps in execution order

   Each step can call an agent or tool. Keep each step focused and clearly named so approvals and logs are easy to interpret later.

3. 3
   Reference earlier outputs

   Pass context from previous steps into later steps using template references. This keeps workflows deterministic and reduces manual copying between runs.

4. 4
   Test with realistic payloads

   Run the workflow with representative input and validate intermediate outputs, approval pauses, and final artifacts before broader rollout.

{{step.N}}   # Example: {{step.1}}

Approvals are the human control plane for sensitive or high-impact actions.

1. 1
   Open Org → Approvals

   Use filters to focus on pending items, workflow-only items, or agent-run items depending on your triage responsibilities.

2. 2
   Sort by step when reviewing workflows

   Use Step ↑ or Step ↓ to review workflow approvals in execution order. This helps reviewers understand context before approving downstream actions.

3. 3
   Open details and verify intent

   Inspect the action payload, related run/workflow, and any tool context. Confirm the requested action matches policy and expected business logic.

4. 4
   Approve or reject

   Submit the decision. The page preserves your filters/sort settings so you can continue triaging without losing context.

Use the Team page to scale access safely while preserving role boundaries.

API keys let external systems call your UmamiAI Platform API securely.

1. 1
   Open Org → API Keys

   Only owners/admins should create keys. Review existing keys and scopes to avoid issuing duplicates for the same integration.

2. 2
   Create a scoped key

   Provide a name that identifies the integration (for example, “crm-sync-prod”), choose the minimum scopes, and create the key.

3. 3
   Copy the plaintext key once

   The full key is shown only at creation time. Store it immediately in a secret manager, CI/CD secret store, or runtime environment variable.

4. 4
   Test with the Platform API

   Use the docs and developer guide curl examples to verify auth, create a run, fetch results, and confirm your integration path before production rollout.

# Example API auth header
curl -sS "$UMAMIAI_BASE_URL/api/v1/agent-runs/$RUN_ID" \
  -H "Authorization: Bearer umami_..."

Webhooks notify your systems when events happen in the platform (for example run completion or approvals).

1. 1
   Open Org → Webhooks and add an endpoint

   Provide a reachable HTTPS endpoint in your system. Use separate endpoints for staging and production where possible.

2. 2
   Store the signing secret

   Copy the webhook signing secret and store it securely. Your receiver will use it to verify each delivery signature.

3. 3
   Implement signature verification

   Validate the delivery using the signature header before trusting the payload. Reject requests that fail verification or come from unexpected sources.

4. 4
   Test and monitor deliveries

   Trigger a platform event, inspect webhook delivery attempts, and verify your receiver handles retries and idempotency safely.

Use the platform’s records to support troubleshooting, governance, and operational review.

These practices reduce incidents and speed up onboarding for new teammates.

Use these quick checks before escalating to your platform owner or developer team.