orkaia 0.2.0

Observability and control for AI agents in production

Orka Python SDK

Observability and control for AI agents in production.

Add one decorator to any agent function and instantly see every action, cost, and error in real time — with the ability to pause and require human approval before destructive operations.

pip install orkaia

---

The problem

You deploy an AI agent. It runs. You have no idea what it's actually doing.

• Did it make the right API calls?
• Why did it fail on that one input?
• What did it spend your money on at 3am?
• Did it hit a rate limit or get blocked by a policy?

Logs don't capture the full chain. Debugging is a detective game. You limit your agent's capabilities out of fear rather than trust.

Orka fixes that. Connect once. See everything.

---

Quickstart (5 minutes)

1. Install

pip install orkaia

2. Initialize

import orka

orka.init(api_key="orka_your_key_here")
# Get your key at https://orka.ia.br → Settings → API Keys

3. Add to your agent

@orka.guard(agent_id="my-agent", task_type="summarize")
def run_agent(text: str) -> str:
    return your_llm.call(text)  # your existing code, unchanged

4. Open the dashboard

Every execution appears in real time at orka.ia.br/dashboard:

• Input and output of every call
• Duration and estimated cost
• Status: COMPLETED / FAILED / BLOCKED / WAITING_APPROVAL
• Risk score per execution
• Full audit trail, searchable and exportable

---

How @orka.guard works

@orka.guard(
    agent_id="my-agent",   # identifies which agent this function belongs to
    task_type="summarize", # categorizes the action for policy matching
    risk="MINIMAL",        # MINIMAL | LIMITED | HIGH | UNACCEPTABLE
    block_on_policy=True,  # raise OrkaPolicyBlocked if a policy denies it
)
def run_agent(text: str) -> str:
    return llm.call(text)

What happens on every call:

1. Policy check → Orka evaluates active policies for this agent+task_type
2. Your function runs → exactly as before, no changes to your logic
3. Execution logged → input, output, duration, status sent to Orka
4. Risk scored → automatic risk assessment stored on the execution record

Works with both def and async def — detected automatically.

---

LangChain integration

pip install "orkaia[langchain]" langchain-openai

import orka
from orka.integrations.langchain import OrkaCallbackHandler
from langchain_openai import ChatOpenAI

orka.init(api_key="orka_...")

# Every LLM call, tool use, and chain step logged to Orka automatically
cb  = OrkaCallbackHandler(agent_id="my-agent")
llm = ChatOpenAI(model="gpt-4o", callbacks=[cb])

response = llm.invoke("Summarize this document...")
# → See the full call trace in your Orka dashboard

Or use @orka.guard around your entire chain for a single auditable entry:

@orka.guard(agent_id="my-agent", task_type="langchain_chain")
def run_chain(user_input: str) -> str:
    chain = prompt | llm | output_parser
    return chain.invoke({"input": user_input})

---

CrewAI integration

pip install orkaia crewai

import orka

orka.init(api_key="orka_...")

@orka.guard(agent_id="researcher", task_type="web_search", risk="MINIMAL")
def search_web(query: str) -> str:
    return firecrawl.scrape(query)

@orka.guard(agent_id="analyst", task_type="data_analysis", risk="LIMITED")
def analyze_data(data: dict) -> str:
    return llm.analyze(data)

# Wrap any tool — the rest of your CrewAI code is unchanged

---

OpenAI integration

pip install "orkaia[openai]" openai

import orka
from orka.integrations.openai import OrkaOpenAIAdapter
from openai import OpenAI

orka.init(api_key="orka_...")

adapter = OrkaOpenAIAdapter(openai_client=OpenAI(), agent_id="my-agent")
response = adapter.run("List my agents and run a summarization task")
# → Orka tool calls handled automatically in the loop

---

Resource API

Full programmatic control over agents and executions:

from orka import OrkaClient

client = OrkaClient(api_key="orka_...")

# Manage agents
agent = client.agents.create(
    name="my-agent",
    endpoint_url="https://my-agent.example.com/run",
    trust_level="MEDIUM",
)

# Query executions
executions = client.executions.list(agent_id=agent["id"], limit=20)
for ex in executions:
    print(ex["id"], ex["status"], ex["task_type"], ex["duration_ms"])

# Agent-to-agent delegation (X-Handover)
task = client.handover.request(
    from_agent_id="orchestrator-id",
    to_agent_id="specialist-id",
    task_type="deep_analysis",
    payload={"data": "..."},
)

---

Policies and approval flows

Block or pause actions based on risk level, task type, or custom rules — configured in the dashboard, enforced in code.

@orka.guard(
    agent_id="my-agent",
    task_type="send_email",
    risk="HIGH",
    block_on_policy=True,
)
def send_email(to: str, subject: str, body: str) -> bool:
    return email_client.send(to, subject, body)

try:
    send_email("[e-mail]", "Report", "...")
except orka.OrkaPolicyBlocked as e:
    print(f"Blocked: {e.policy_name} — {e.reason}")
    # The request is queued in Orka's approval flow
    # Approve or reject from https://orka.ia.br/dashboard/approvals

---

Exceptions

Exception	When raised
orka.OrkaPolicyBlocked	A policy blocked the execution
orka.OrkaAuthError	Invalid or expired API key
orka.OrkaConnectionError	Cannot reach Orka backend

---

Why Orka vs. LangSmith / Langfuse / AgentOps

	Orka	LangSmith	Langfuse	AgentOps
Works with any framework	✓	LangChain only	✓	✓
Policy-based blocking	✓	✗	✗	✗
Human approval flow	✓	✗	✗	✗
Free tier	10k exec/mo	5k traces/mo	Self-hosted	—
One-decorator setup	✓	✓	✓	✓

Orka is the only observability tool that gives you active control — pause an agent, require human approval before a destructive action, and enforce policies that block bad behavior before it happens.

---

Installation options

pip install orkaia                  # core
pip install "orkaia[langchain]"     # + LangChain callback handler
pip install "orkaia[openai]"        # + OpenAI adapter
pip install "orkaia[all]"           # everything

Requires Python 3.10+.

---

Examples

See examples/ for ready-to-run scripts:

File	What it shows
quickstart.py	Minimal setup in 30 lines
langchain_example.py	LangChain callback handler
openai_example.py	OpenAI function calling loop
crewai_example.py	CrewAI tool wrapping

---

Links

• Dashboard: orka.ia.br
• Documentation: orka.ia.br/docs
• Issues: GitHub Issues

---

MIT License © Orka