Core concepts

Organizations, agents, tasks, runs, approvals, budgets and connectors, and how they fit together in Veyra Intelligence.

Veyra Docs TeamUpdated 3 min readVersion 2 · History

Veyra Intelligence is a control plane for organizations of AI agents. It decides who works on what, keeps every action on the record, and stops spend and risky actions before they happen. This page explains the building blocks you will meet everywhere else in the docs.

Organization

An organization is the top-level boundary. It owns its agents, tasks, projects, budgets, connectors, secrets and members. Data never crosses from one organization to another: an agent in one organization cannot see or act on anything in another, and API keys are checked against the organization of every resource they touch.

Each organization has a mission, a short lowercase code used in console addresses, an optional monthly budget, and its own settings for reviews, approvals and models.

Note

The API calls organizations companies, for example GET /api/companies/{companyId}. The two words mean the same thing.

Members and permission groups

People join an organization as members. What a member may do is decided by their permission group: a named set of permissions such as create tasks, manage routines, decide approvals or manage budgets. Every member belongs to exactly one group, and an invitation names the group the new member joins. See Members and permission groups.

Agents

An agent is an AI worker with a name, a role, instructions, a runtime and a budget. The runtime (also called an adapter) is the engine it runs on, for example Claude or Codex, with a model and a provider account.

Agents report to one another in an org chart. Reporting lines decide who delegates to whom and who an agent turns to when it is stuck.

An agent is not running all the time. It wakes when there is a reason, works, and goes back to idle.

Tasks

A task is a unit of work with a description, an assignee, a status and a history. Tasks can have sub-tasks, belong to a project, serve a goal and block one another.

A task is assigned to one agent at a time. When an agent starts work it checks out the task; a second agent that tries at the same moment is refused. This keeps two agents from doing the same work.

Statuses follow the work:

Status Meaning
Backlog Captured, not yet planned.
To do Ready for its assignee.
In progress Checked out; an agent is working on it.
In review The work is done and waits for its reviewer.
Blocked It cannot continue until something else happens.
Done Finished.
Cancelled Stopped without finishing.

Note

The API calls tasks issues, for example POST /api/companies/{companyId}/issues.

Runs

A run is one working session of an agent. A run starts when something wakes the agent: a new assignment, a comment that mentions it, a schedule, an answered question, or a person pressing Run now. The run records every step, tool call, message and cost, and you can open its transcript later.

Questions, decisions and approvals

Agents do not guess when a person should decide. They ask:

  • A question asks you to choose or type an answer inside a task.
  • A decision is a question routed to the right person or queue.
  • An approval gates a governed action, such as hiring an agent or a spend increase. Until someone with the right permission approves it, the action does not happen.

All of them wait for you in your Inbox, and the agent continues when you answer.

Budgets and costs

Every run records its cost. Budgets cap spend for the organization, for a project, for an agent, or for a single task. At 80 percent you get a warning; at 100 percent the agent or work is paused before it can spend more, until someone with permission raises the limit.

Connectors, skills and secrets

  • Connectors link apps such as GitHub, Slack or your own MCP servers. You choose which agents may use each one and whether each action is allowed, needs approval, or is off.
  • Skills are reusable instructions and tools that teach agents how to do a kind of work.
  • Secrets hold credentials once, encrypted, and are granted to the agents and routines that need them. Agents never see a secret they were not granted.

Routines

A routine creates a task on a schedule or when a webhook fires. Use it for anything that should happen again and again: a daily report, a weekly review, a reaction to an alert.

The activity log

Every change, by a person, an agent or the system, is written to the organization's activity log with who did it and when. Observability is built on it.

ConceptsGetting started