Getting Started with ProvenanceOne

ProvenanceOne is an agentic AI workflow orchestration platform. You define workflows — directed acyclic graphs of steps — that coordinate AI agents, skills, MCP servers, approvals, and data actions. This guide walks you through creating a workspace, configuring your first agent, building a minimal workflow, and reviewing the results of a run.

Expect to complete these steps in under 30 minutes for a simple use case. Complex integrations that require OAuth connections or custom skills will take longer.

---

When to use this guide

Use this guide when you are setting up ProvenanceOne for the first time, or when you are helping a new team member get access and run their first workflow. For deeper reference on any individual concept, follow the links in each section to the dedicated documentation page.

---

Prerequisites

Before you begin, confirm you have the following:

• An invitation email from ProvenanceOne or an existing account
• At minimum one API key or OAuth credential for a service your workflow will interact with (e.g. a CRM, a database, a messaging tool)
• A clear idea of what you want to automate — even a rough description is enough to start

Note: You can create a workspace and explore the interface without a connection, but you will not be able to run workflows that interact with external services until at least one connection is configured.

---

First run checklist

• Create or accept an invitation to a workspace
• Assign roles to team members (admin, editor, or viewer)
• Create at least one connection (OAuth or API key)
• Create an agent and configure its model and system prompt
• Create a workflow and attach the agent as a step
• Set the workflow trigger (start with manual for testing)
• Publish the workflow (v1)
• Trigger a manual run
• Review the run output in the run debugger

---

Key concepts

Workspace — the top-level container for all your workflows, agents, skills, connections, and team members. Every resource belongs to exactly one workspace.

Environment — workflows and agents are scoped to an environment: production, staging, or development. Use development while building and testing.

Role — each team member has one role per workspace: admin, editor, or viewer. Roles control what they can create, edit, and approve.

Connection — a stored credential (OAuth token, API key, service account) that agents and skills use to call external services. Connection credentials are encrypted at rest and never exposed via the API.

Agent — a configured instance of an LLM (e.g. claude-sonnet-4-6, gpt-4o) with a system prompt, attached skills, and trust settings. Agents do not run on their own; they run as steps inside workflows.

Workflow — a DAG of steps that defines the automation logic. The workflow is the blueprint; a run is a single execution of that blueprint against a specific input.

---

How it works: Step-by-step setup

Step 1: Create your workspace

After logging in for the first time, you will be prompted to create a workspace. Choose a name and slug carefully — the slug appears in API paths and cannot be changed after creation. Select your primary environment (development is recommended for initial setup).

Step 2: Invite your team

Navigate to Settings → Members and invite colleagues by email. Assign roles:

• admin — full access including billing, settings, and member management
• editor — can create and edit workflows, agents, skills, and connections; can approve runs
• viewer — read-only access; can view runs, agents, and workflows but cannot modify anything

Step 3: Set up a connection

Go to Connections and click Add Connection. Choose the connector type (e.g. Slack, Jira, a REST API), and follow the OAuth or API key flow. Once the connection is saved and verified, it becomes available to skills and agents in your workspace.

Step 4: Create an agent

Go to Agents and click New Agent. Fill in:

• Name and display name — used in the UI and in audit logs
• Provider and model — choose from anthropic, openai, google, or azure-openai and select a model such as claude-sonnet-4-6
• System prompt — write a clear, scoped instruction set for the agent. The system prompt shapes the agent's behavior but does not fully control it; design workflows with approval steps for high-stakes actions
• Trust level — start with low or medium for new agents; increase to high only once you have validated behavior in staging
• Category — reasoning, coding, or analysis

Save the agent. It is now available as a step in workflows.

Step 5: Create a workflow

Go to Workflows and click New Workflow. In the visual editor:

1. Add a trigger step — set the trigger type to manual for your first test
2. Add an agent step — select the agent you just created
3. Connect the trigger to the agent step with an edge
4. Configure the agent step's input mapping — pass relevant fields from the trigger payload into the agent's context

Save the draft. The workflow is in draft status until you publish it.

Step 6: Publish the workflow

Click Publish in the editor toolbar. ProvenanceOne saves the current state as v1. Published versions are immutable — any subsequent changes create a new draft and must be published as v2, v3, etc. The workflow status changes to deployed.

Step 7: Trigger a manual run

On the Workflows list page, find your workflow and click Run. For a manual trigger, you can supply an input payload in JSON. The run starts immediately and appears in Runs with status running.

Step 8: Review the output

Open the run in the Runs page. The run debugger shows each step with its inputs, outputs, logs, and (for agent steps) tool calls. If a step failed, the error panel shows the error code, probable cause, and suggested fix.

---

Configuration options

Field	Type	Required	Default	Description
Workspace name	string	Yes	—	Human-readable name for the workspace
Workspace slug	string	Yes	—	URL-safe identifier; immutable after creation
Environment	enum	Yes	development	production | staging | development
Member role	enum	Yes	—	admin | editor | viewer
Agent model	string	Yes	—	Model identifier, e.g. claude-sonnet-4-6
Agent trust	enum	Yes	low	low | medium | high
Workflow trigger	enum	Yes	manual	webhook | schedule | manual | event | api | queue

---

Examples

Support escalation workflow — trigger: webhook (inbound ticket), steps: agent (triage) → approval (if risk is high) → action (update CRM). See /playbooks/customer-support-agent for a full walkthrough.

Scheduled report — trigger: schedule (daily at 09:00), steps: skill (fetch data) → agent (summarise) → notify (email). No connection required if the agent uses only built-in knowledge.

Estimate your automation ROI before committing to a build: /tools/ai-agent-roi-calculator.

---

Common mistakes

• Publishing to production before testing in development or staging. Always test a new workflow in a non-production environment first.
• Giving agents high trust immediately. High trust reduces the number of approval gates the platform inserts automatically. Earn trust incrementally by reviewing run outputs.
• Not mapping trigger payload fields to step inputs. If the agent step has no input, it will receive an empty context and produce generic output.
• Using a single environment for all testing. Separate development and staging environments exist for a reason — use them.

---

Troubleshooting

I published the workflow but I cannot see a Run button — check that the workflow status is deployed and that you have the editor or admin role. viewer cannot trigger runs.

My run is stuck in running — navigate to the run and check the step-level status. A step stuck in running often indicates an external call that has not returned. Check the logs panel for timeout messages.

I cannot create a connection — some connectors require OAuth redirect URIs to be allow-listed in the third-party app. Confirm the redirect URI https://app.provenanceone.ai/auth/callback is registered in the external service.

---

Security and permissions

All pages except /login and /auth/callback require authentication. Workspace data is strictly isolated — members only see resources belonging to workspaces they have been explicitly invited to.

Role summary:

• admin — all operations, member management, billing, settings
• editor — create/edit workflows, agents, skills, connections; approve runs; view audit log
• viewer — read-only

Audit events are emitted for every significant action (workflow.published, agent.updated, member.invited, etc.). Audit logs are immutable and cannot be deleted by any role.

---

Related pages

• Workflows
• Agents
• Approvals
• Workflow Runs
• Skills
• MCP Servers

---

FAQ