
vira
io.github.hrpering/vira
Governed behavior for AI applications and coding agents: define, evaluate, release and inspect.
Documentation
Define it. Test it. Release it. Know what ran.
Own how your AI behaves. Define what it should say, decide and do; evaluate and release those expectations; run eligible behavior through governed tasks with inspectable evidence.
Get started · Documentation · OFF/ON chatbot · Agent Skills · Türkçe
Early access: The SDKs, Agent Skills and examples are public. Live Vira operations require a provisioned account; Studio is optional for SDK-supported operations. See what you can try today.
Operate Vira directly from your coding agent
Vira is agent-first. Install the single vira root Skill; it routes integration, MCP/SDK, Packs, Teach, evaluation, release, TaskRuns and traces without asking developers to select among 28 specialist manuals. The specialists remain optional advanced references, while actual Vira access and authority stay with the customer service.
npx skills add hrpering/tryvira --skill vira
The default Skill uses the connected MCP server when available, otherwise documented installed JavaScript/Python SDK methods, and never routes around an authorization denial. OpenCode users can follow the public OpenCode adapter setup. The separately distributed plugin is not embedded in this repository.
Ask your coding agent: “Connect my AI application, build a Behavior Pack, evaluate it and prepare it for release. Don't modify production until I approve.” The agent discovers actual MCP tools or installed SDK methods, verifies scope, and reads real server state. See the common operation flow. The Studio-less capability ledger identifies workflows still waiting for public API support; a Skill cannot invent them.
The problem
Your agent does a task. You correct an answer. The same mistake returns in another session, workflow, or model. A rule gets added to a prompt, another to application code, and a third to a test. Soon nobody can answer: What is this AI expected to do, which version is live, and was the change evaluated?
Vira provides a separate, governed place to define and operate those behaviors. It works with your existing AI application, model, and agent framework rather than replacing them.
Make AI behavior something you can manage
A prompt can tell an assistant what to do today. Vira helps teams keep those expectations consistent as applications, models, agents and requirements change.
- Define reusable, task-specific expectations outside a single prompt.
- Evaluate proposed changes with examples and failure cases before release.
- Release the approved revision to the intended scope.
- Inspect available runtime evidence to understand which behavior was selected.
- Improve behavior through reviewed feedback and Teach proposals.
Vira complements the models and agents you already use. Start with everyday and business scenarios, or explore the technical execution path.
See the full Vira loop
Vira is more than a Pack editor or a runtime rules switch. It connects real AI activity → governed behavioral changes → execution-time evidence:
Vira behavior lifecycle, illustrated.
| Capability | The practical question | Start here |
|---|---|---|
| Connect / Observe | What do our AI agents actually say, decide, call and fail at? | Observe |
| Discover / Signals | Which tasks and typed context signals can we identify from permitted evidence? | Semantic routing · Signals |
| Define / Packs / Strategies | What behavior should apply, and how should it execute? | Pack Academy · Strategies |
| Teach / Feedback / Outcomes | How does a correction become a reviewed improvement, rather than another prompt patch? | Teach · Observe |
| Evaluate / Release | Has this exact revision been tested and explicitly approved? | Evaluation · Release |
| AUTO TaskRun / Runtime enforcement | Which eligible behavior and child executor actually ran? | Canonical TaskRun |
| Runtime verification / Response Quality | Did the actual output satisfy the configured checks, and what happens on failure? | Runtime verification · Quality |
| Traces / Receipts / Operations | What was applied, skipped, denied or measured, and can the team inspect it? | Receipts · Product feature map |
Explore Vira capabilities, including Signals, runtime behavior, evaluation, Teach, integrations and operational tooling. Product availability lists current access and integration requirements.
Examples for different kinds of AI work
Vira is not limited to one industry or to complex agents. Start simple, then move to multi-task execution:
| Complexity | Example | What you would govern |
|---|---|---|
| Everyday | A four-person dinner | Keep a configured vegetarian, onion-free preference while producing a useful recipe |
| Team support | A delayed package | Ask for missing order context; never invent tracking status or promise a refund |
| Business | A marketing performance report | Avoid comparing incompatible attribution windows as if they matched |
| Technical | A safe SDK upgrade | Follow a bounded verification and rollback strategy |
| Advanced | An operations decision brief | Coordinate multiple independently governed tasks and approvals |
12 scenarios with sample prompts and failure cases · copyable short/detailed fixture prompts · Compare Vira with Skills and agents
From one task to multi-step workflows
Start with a single task, or govern a process with several steps or coordinated tasks. Vira's AUTO TaskRun can select among eligible SINGLE, STRATEGY, COMPOUND and HYBRID execution paths, depending on the connected application and released behavior.
Execution modes · TaskRun example
Learn to author high-quality Behavior Packs
Start with four versioned Behavior Packs: recipe preferences, retail-media evidence review, marketing launch decisions and operations orchestration (including a structured Strategy). They include 108 diverse design-time test scenarios, not measured model outcomes. Compare real OFF/ON responses. Where each Pack field belongs.
A business example
Imagine a retail-media assistant answering:
"Which campaign performed better? Compare these two channel reports and tell me where to move next month's budget."
The reports use different attribution windows and sales definitions. An ordinary answer might rank the ROAS figures as though they were directly comparable.
A Vira behavior for this task can explicitly require the assistant to:
- Check comparability: identify attribution windows, sales scope, and metric definitions before ranking channels.
- Handle uncertainty: distinguish supported findings from assumptions and request missing information rather than inventing a comparison.
- Preserve the workflow: provide a useful recommendation when evidence permits, including the basis and limitations.
That definition can be packaged, evaluated with positive and negative cases, reviewed, and explicitly released. A supported runtime integration resolves eligible behavior for the request and returns evidence of what was selected.
Illustrative scenario. Actual output quality and behavior enforcement depend on the model, deployed controls and test results.
What Vira adds
| Without a governed behavior layer | With Vira |
|---|---|
| Requirements spread across prompts, code, and notes | Named Semantic Tasks, Behavior Points, Programs, and Strategies |
| Changes that are hard to inspect or reproduce | Versioned candidates, evaluations, explicit review and release |
| Rules activated without a clear authority boundary | Scoped runtime resolution of eligible released behavior |
| Repeated mistakes with no structured improvement process | Permitted evidence → Teach proposals → review → evaluation |
| "It behaved differently" with little context | Returned identities, receipts, and traces for supported operations |
Explore the capabilities · Understand the concepts
See it in action
Current sample: real OFF provider response; ON shows TaskRun admission and status.
Try the Next.js + OpenAI Agents example. OFF calls your configured model; ON submits an AUTO TaskRun and displays the server's admission and state. Final verified ON answers are not yet available in this example.
git clone https://github.com/hrpering/tryvira.git
cd tryvira/examples/frameworks/node-next
npm ci
cp .env.example .env.local
# Set OPENAI_API_KEY in .env.local (server-side)
npm run dev
Open the local app and try Vira OFF. To test Vira ON admission, configure your provisioned Vira environment and eligible released behavior. Setup and prerequisites.
The sample is intended for local development. Add authentication, rate limits and tenant mapping before making its routes public.
Chatbot setup · Framework examples · Marketing Agent walkthrough
Build with the stack you already use
| Integration | Install or entry point | Guide |
|---|---|---|
| JavaScript / TypeScript | npm install @tryvira/sdk | SDK guide |
| Python | python -m pip install tryvira-sdk | Python guide |
| MCP | npx -y @tryvira/mcp | MCP setup and tool discovery |
| HTTP | Customer deployment's documented API | HTTP integration boundaries |
| Agent Skills | Task-specific guidance for coding agents | Skills library |
Each integration has its own supported operations. Check the compatibility guide and current availability before connecting to a provisioned service.
Find your path
- New to Vira? Start here and understand the concepts.
- Building an integration? Example verification status, Developer checklist, mode guide, Developer guide, examples, and troubleshooting.
- Evaluating it for a team? Use cases, approach comparison, Team evaluation guide, product overview, and FAQ.
- Working with behavior changes? Packs, Teach AI, evaluation, and runtime.
- Contributing? Contribution guide, support, and security reporting.
Trust, limits, and licensing
Vira is not a foundation model, an agent framework, or an automatic replacement for application authorization. Runtime outcomes depend on the integration boundary. Semantic matches and Teach suggestions are not permission to release or execute. Check the authority and security model.
This repository publicly shares documentation, examples, and Skills. Its repository license is proprietary; public visibility does not grant an open-source license. The separately published JavaScript, Python, and MCP client packages use MIT licenses under their own distribution terms. See published packages and licensing.
Found an issue? Use GitHub Issues for reproducible public-doc or package problems, and private vulnerability reporting for security concerns. Do not post credentials or customer information.
@tryvira/mcpnpm install @tryvira/mcp