Core Concepts

Organizations & Workspaces

An Organization (also called a Workspace) is a completely isolated environment with its own balance, agents, teams, members, audit logs, and settings. Think of it like a Kubernetes namespace or an AWS account — everything inside is walled off from everything outside.

Users can belong to multiple organizations simultaneously. This is designed for agencies, consultancies, and platform teams that manage fleets of agents across different clients or internal departments. Switch between workspaces using the topbar dropdown — each workspace maintains its own context (active team, recent activity, session history).

Create a new workspace anytime at /workspaces/new. New workspaces start with a $0 balance and a single a single “Default” teamldquo;Defaulta single “Default” teamrdquo; team. You can invite members, create teams, provision agents, and set budgets independently in each workspace. Billing is per-workspace via Stripe.

Teams

Teams are the primary organizational unit within a workspace. They group members and agents together, manage budget pools, and control service access. Each team is a self-contained budget boundary with its own hierarchy.

Each team has:

• Team roles — Two built-in roles: Manager (can allocate budgets, manage members, approve requests) and Worker (receives budget allocations, can use services within their allocation). Custom team roles can be created with fine-grained permissions (40+ available).
• Team pool — A budget allocated from the org balance that managers distribute to workers. Think of it as a departmental budget — the org funds the team, the team distributes to individuals.
• Worker budgets — Individual spending caps per worker, with daily, monthly, and hard limits. Workers can request budget increases from managers via the Budget Requests system.
• Service access — Per-team allowlists for which services members can enable on their agents. A "Data Team" might allow web_search, text_generation, and data.csv_parse but block email and voice_call.
• Scheduled top-ups — Automatically refill worker budgets on a daily, weekly, or monthly cadence. Set a $100/day budget that resets every morning — no manual intervention needed.
• Free plan limit — The free plan allows up to 3 teams per workspace. Pro and Business plans remove this limit.

Teams also control agent visibility — agents can be scoped to a specific team (team visibility) or published to the entire organization (org visibility). Team-scoped agents are only visible to team members, keeping sensitive work contained.

Agents

An Agent is an AI-powered entity that can call services through Upivia. Each agent has its own API key, service bindings, budget caps, personality, memory, and audit trail. Think of an agent as a digital employee — you give it a job, it uses the tools youyouyou've authorizedapos;ve authorizedapos;ve authorized, and you can see everything it does.

Every agent has these properties:

• API key — Two modes: agent_key_test_ (mock adapters, zero cost — use during development) and agent_key_live_ (real providers, real spend — use in production). Keys are shown exactly once and stored as cryptographic hashes. Lost keys can be rotated but never recovered.
• Kinds — user agents are standard agents (including YUPI, the default agent). chat agents are auto-provisioned for the in-app chat surface. Both kinds go through the same policy/budget/audit pipeline.
• Status — active (normal operation),paused (temporarily suspended — queued requests are held, not dropped), disabled (permanently blocked — cannot execute any requests).
• Visibility — private (only creator and admins), team (visible to the agent's team — requires publishing), org (visible to entire organization — requires publishing + admin approval).
• Service bindings — Per-operation configuration: monthly budget cap, daily request limit, approval threshold, and operation-specific defaults. An agent with email.send enabled at $25/mo with 100 requests/day and $0.50 approval threshold will auto-execute cheap emails but queue expensive ones for review.
• Personality / Soul — The agentThe agent's identityapos;s identity: backstory, behavioral rules, communication style, and expertise. Six rich presets available (Research Analyst, Code Reviewer, Customer Support, Data Scientist, Concise Builder, Creative Strategist) or write a custom system prompt for full control. Max 2000 characters.
• Voice configuration — Kokoro TTS settings: voice name, rate (0.5–2.0), pitch (0–2), language. Enable/disable globally per agent. Test the voice from the Identity tab.
• Memory — Persistent, governed memory with vector search. Agents accumulate knowledge, experience, insights, plans, and constraints. Visualized as a 3D force-directed graph with directional pulse particles on semantic edges. Memory scopes: agent-only, team-shared, or workspace-wide.

Services & Operations

A Service is a capability provider — email, web search, text generation, browser, etc. An Operation is a specific action within a service — email.send, web_search.search, text_generation.generate.

Upivia ships with 23 service families and 40+ operations out of the box. Each operation has a defined input schema, output schema, and base price (in cents). The platform handles provider selection, authentication, retries, and reconciliation — your agent just calls the operation name.

Custom HTTP APIs can be added at /agents?tab=apis (admin only). Define a method, URL, headers, auth, pricing, and timeout — and it becomes available alongside built-in services with full policy, budget, and audit support.

Budgets & Balance

Upivia uses a hierarchical budget system with dollar-denominated limits (stored as integer cents internally). The hierarchy ensures that no single agent or team can drain the organizationorganization's walletapos;s wallet.

Org Balance ($500)         ← Single Stripe-funded wallet
  ├─ Team Pool A ($200)      ← Allocated by workspace owner
  │   ├─ Worker 1 Budget ($100)  ← Allocated by team manager
  │   └─ Worker 2 Budget ($100)
  └─ Team Pool B ($300)
      └─ Worker 3 Budget ($300)

At the agent level, per-operation caps add another layer:
  email.send:        $25/month cap, 100 requests/day max
  web_search.search: $10/month cap, 200 requests/day max
  text_generation:   $50/month cap, 500 requests/day max
  voice_call.create: $5/month cap, $0.50 approval threshold

Every service request runs a 6-step budget check:

1. Daily request count for this operation — under the limit?
2. Monthly spend on this binding — under the cap?
3. Agent-level monthly budget — under the cap?
4. WorkerWorker's personalapos;s personal budget — has enough remaining?
5. Team pool — has enough remaining?
6. Org wallet balance — can cover the estimated cost?

Budgets are caps, not deposits. Setting a $50 monthly cap doesndoesn't reserveapos;t reserve $50 — it just stops spending once $50 has been spent this month. Multiple agents and teams share the single org wallet. Only the wallet needs actual funds; caps are soft limits.

Permissions

Upivia uses a split permission system (Phase 13) that separates org-level and team-level permissions. This gives you granular control over who can manage what — from creating agents to allocating budgets to publishing workflows.

• Org-level permissions (27 total) — agent.createAny, agent.deleteAny, agent.manageAny, member.invite, member.manage, member.remove, org.update, org.manageBilling, org.viewAs, publish.manage, publish.review, delegation.create, delegation.manageAny, workflow.create, workflow.edit, scheduledTask.create, scheduledTask.manage, trigger.manage, storage.manage, customService.manage, connectedApp.manage, resource.manage, apiDocs.manage, lead.manage, team.manage, team.viewAny, budget.manage.
• Team-level permissions (40+) — team.budget.view, team.budget.allocate, team.budget.requests.review, team.members.view, team.members.manage, team.workers.view, team.workers.budget.allocate, team.service.manage, team.publish.request, team.publish.review, team.agent.spawn, team.workflow.grant, and more.
• Custom roles — Create org roles and team roles with fine-grained permission checkboxes. System roles (Owner, Admin, Member) cannot be deleted. A role with 0 members can be deleted.

Permissions are enforced at the API level. Every endpoint checks the callercaller's roleapos;s role before executing. The UI also gates features — non-admins wonwonwon't apos;t seeapos;t see admin-only tabs or buttons.

Audit Trail

Every action in Upivia — service requests, approvals, publishing events, memory mutations, delegations, budget changes — is recorded in an immutable, hash-chained audit log. This provides cryptographic proof that the log hasnhasnhasn't been tamperedapos;t been tamperedapos;t been tampered with.

Each audit entry includes an eventHash and prevEventHash, forming a chain:
eventHash = sha256(canonicalJson(entry) + prevEventHash)

canonicalJson() ensures deterministic serialization — sorted keys, consistent formatting, stable across runtimes and programming languages. This means you can verify the chain independently without trusting the platform.

Run verifyAuditChain(orgId) to validate the entire chain. If any entryentry's hash doesn't matchapos;s hash doesnentry's hash doesn't matchapos;t match its successor's prevEventHash, the chain is broken and the verification returns the first broken link. This is surfaced in the Agent Activity Ledger with a green “Audit Chain Intact” or red “Audit Chain Broken” banner.

Export your full audit log at /settings/danger for compliance, auditing, or external verification. The export is a JSON snapshot of all audit entries for the workspace.