Python SDK

python -c "import agenteye; print(agenteye.__version__)"

import agenteye

agenteye.configure(environment="production")

agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    input={"query": "latest AI research"},
)

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    output={"results": ["..."]},
)

agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")

import anthropic
import agenteye

agenteye.configure(environment="production")
client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Summarise today's incidents."}]

agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6",
    messages=messages,
)

reply = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=messages,
)

agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model=reply.model,
    stop_reason=reply.stop_reason,
    input_tokens=reply.usage.input_tokens,
    output_tokens=reply.usage.output_tokens,
    content=[block.model_dump() for block in reply.content],
)

agenteye.configure(
    base_dir=None,           # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye
    flush_interval=0.5,      # float, seconds between flush cycles
    environment=None,        # str | None. Deployment environment label
)

agenteye.configure(environment="production")

export AGENTEYE_ENVIRONMENT=production

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="planner",
    goal="answer user query",   # str | None
    parent_id=None,             # str | None - معرف وكيل الوالد للوكلاء المتداخلين
)

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="planner",
    outcome="success",          # str | None
    summary="Answered query",   # str | None
)

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",     # str, required
    tool_call_id="toolu_01",    # str, required - مفتاح الارتباط للمطابقة tool_result
    input={"query": "..."},     # dict | None
)

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",        # يجب أن يطابق tool_use السابق
    output={"results": ["..."]},    # Any | None
    error=None,                     # str | None - اضبط إذا أطلقت الأداة
    # يتم حساب duration_ms تلقائياً - لا تمرره
)

agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None - أي سلسلة موفر/نموذج؛ غير معتمدة
    messages=[                   # list[dict] | None - أدوار المحادثة
        {"role": "user", "content": "..."},
    ],
    system="You are helpful.",   # Any | None - str أو قائمة كتل المحتوى
    tools=[                      # list[dict] | None - مخططات الأداة المقدمة للنموذج
        {"name": "search", "input_schema": {"type": "object"}},
    ],
)

agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None - أي سلسلة موفر/نموذج؛ غير معتمدة
    stop_reason="end_turn",     # str | None
    input_tokens=1024,          # int | None
    output_tokens=256,          # int | None
    content=[                    # Any | None - str، أو قائمة كتل المحتوى
        {"type": "text", "text": "..."},
    ],
    role="assistant",            # str | None
)

agenteye.event.hook_triggered(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",   # str, required
    hook_id="hook-abc",         # str, required - مفتاح الارتباط
    trigger_event="tool_use",   # str | None
    input={"tool": "search"},   # Any | None
)

agenteye.event.hook_completed(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",
    hook_id="hook-abc",         # يجب أن يطابق hook_triggered السابق
    outcome="allow",            # str | None
    output=None,                # Any | None
    error=None,                 # str | None
    # يتم حساب duration_ms تلقائياً - لا تمرره
)

agenteye.event.error(
    session_id="run-001",
    agent_id="planner",
    error_type="TimeoutError",  # str, required
    message="timed out",        # str, required
    traceback="Traceback...",   # str | None
)

agenteye.event.human_wait(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",                          # str, required - مفتاح الارتباط للمطابقة human_input
    prompt="Do you approve this action?",        # str | None - السؤال المعروض للإنسان
    options=["approve", "reject", "defer"],      # list[str] | None - الخيارات المعروضة على الإنسان
    reason="approval_required",                  # str | None - لماذا ينتظر الوكيل
)

agenteye.event.human_input(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",    # str, required - يجب أن يطابق human_wait السابق
    response="approve",    # str | None - إجابة الإنسان (نص حر أو خيار محدد)
    # يتم حساب duration_ms تلقائياً - لا تمرره
)

agenteye.event.human_pause(
    session_id="run-001",
    agent_id="planner",
    reason="user_requested",  # str | None
    user_id="usr_42",         # str | None - من أوقف الوكيل
)

agenteye.event.human_interrupt(
    session_id="run-001",
    agent_id="planner",
    reason="output_incorrect",       # str | None
    user_id="usr_42",                # str | None - من قاطع الوكيل
    at_step="tool_use:web_search",   # str | None - ما كان الوكيل يفعله عند الإيقاف
)

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="db_query",
    tool_call_id="toolu_02",
    tenant_id="acme",           # حقل مخصص
    region="us-east-1",         # حقل مخصص
)

~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl