Metadata-Version: 2.4
Name: agent-skill-compiler
Version: 0.4.3
Summary: Python SDK for sending agent traces to a remote Agent Skill Compiler backend.
Project-URL: Homepage, https://github.com/dlamaro96/Skill-Compiler
Project-URL: Frontend, https://github.com/dlamaro96/skills-compiler
Project-URL: Issues, https://github.com/dlamaro96/Skill-Compiler/issues
Author: Open Source Contributors
License: MIT
Keywords: agents,ai,analysis,skills,tooling,tracing
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.11.0
Provides-Extra: agno
Requires-Dist: agno; extra == 'agno'
Description-Content-Type: text/markdown

# Agent Skill Compiler

`agent-skill-compiler` is a Python SDK for sending agent traces from your application backend to a remote Agent Skill Compiler backend.

This package is for `pip install` only. It does not run the ASC server, database, or UI.

## Install

```bash
pip install agent-skill-compiler
```

With Agno support:

```bash
pip install "agent-skill-compiler[agno]"
```

For Microsoft Agent Framework:

```bash
pip install agent-skill-compiler
pip install agent-framework --pre
```

## What You Need

Your app backend needs these environment variables:

```bash
ASC_BASE_URL=http://your-asc-backend
ASC_PUBLIC_KEY=asc_pk_...
ASC_SECRET_KEY=asc_sk_...
```

Legacy aliases are also supported:

```bash
SKILL_COMPILER_HOST=http://your-asc-backend
SKILL_COMPILER_PUBLIC_KEY=asc_pk_...
SKILL_COMPILER_SECRET_KEY=asc_sk_...
```

## Quick Start

```python
from agent_skill_compiler import SkillCompilerTracer

tracer = SkillCompilerTracer.from_env(
    optional=True,
    default_agent_name="planner",
    metadata={
        "service": "app-backend",
        "framework": "custom",
    },
)

with tracer.trace(
    task_name="ai_planner_chat",
    input_text=user_prompt,
    metadata={
        "workflow": "ai_planner",
        "session_id": session_id,
        "user_id": user_id,
    },
) as run:
    tool_call = run.tool_call(
        action_name="get_calendar_tasks",
        semantic_name="list_user_tasks",
        arguments={"user_id": user_id, "date": "today"},
    )

    tasks = load_tasks(user_id)

    run.tool_result(
        action_name="get_calendar_tasks",
        semantic_name="list_user_tasks",
        result={"task_count": len(tasks), "tasks": tasks},
        parent_event_id=tool_call.event_id,
    )

    run.decision(
        action_name="prioritize_tasks",
        decision={"strategy": "due_date_then_importance"},
        reason="Tasks exist and need ordering.",
    )

    run.final_output(output=assistant_response)
```

If the environment variables are missing and `optional=True`, the SDK becomes a safe no-op and will not break your app.

## Low-Level Client

```python
from agent_skill_compiler import SkillCompilerClient

client = SkillCompilerClient.from_env(optional=False)

run = client.start_run(
    task_name="customer_followup",
    input_text="Review this customer issue and prepare next steps.",
    metadata={"service": "support-api", "workflow": "support_triage"},
)

event = client.record_event(
    run_id=run.run_id,
    agent_name="ResearchAgent",
    action_name="search_docs",
    action_kind="tool_call",
    input_payload={"query": "latest billing escalation policy"},
    tool_metadata={
        "semantic_name": "knowledge_search",
        "tool_name": "search_docs",
        "framework": "custom",
    },
)

client.record_event(
    run_id=run.run_id,
    agent_name="ResearchAgent",
    action_name="search_docs",
    action_kind="tool_result",
    output_payload={"documents": ["billing-policy-v2"]},
    tool_metadata={
        "semantic_name": "knowledge_search",
        "tool_name": "search_docs",
        "framework": "custom",
    },
    tool_call_id=event.event_id,
    parent_event_id=event.event_id,
)

client.finish_run(run_id=run.run_id, status="success")
client.close()
```

## What The Tracer Captures

The generic tracer supports:

- `run.tool_call(...)`
- `run.tool_result(...)`
- `run.decision(...)`
- `run.route(...)`
- `run.message(...)`
- `run.error(...)`
- `run.final_output(...)`
- `run.update_metadata(...)`

Use `semantic_name=...` on tool events when you want stable grouping across framework-specific tool names.

## Event Wire Format

For tool events, send structured metadata as first-class fields instead of hiding it only inside payload blobs.

`RecordEventRequest` and `TraceEvent` support:

- `input_payload`
- `output_payload`
- `tool_metadata`
- `tool_call_id`
- `parent_event_id`

Recommended meanings:

- `tool_metadata.semantic_name`: stable semantic label used across frameworks and renames
- `tool_metadata.tool_name`: raw runtime tool name
- `tool_call_id`: stable reference to the originating tool call event
- `parent_event_id`: event tree linkage for parent/child relationships

Example:

```json
{
  "agent_name": "ResearchAgent",
  "action_name": "search_docs",
  "action_kind": "tool_result",
  "input_payload": {},
  "output_payload": {
    "documents": ["billing-policy-v2"]
  },
  "tool_metadata": {
    "semantic_name": "knowledge_search",
    "tool_name": "search_docs",
    "framework": "custom"
  },
  "tool_call_id": "call_evt_123",
  "parent_event_id": "call_evt_123",
  "latency_ms": 128,
  "success": true
}
```

Send structured dict/list data directly when possible. The SDK will preserve dict-like and JSON-like results instead of degrading them into strings whenever it can serialize them safely.

## Helpers Exported By The SDK

- `SkillCompilerClient`
- `AsyncSkillCompilerClient`
- `SkillCompilerTracer`
- `AsyncSkillCompilerTracer`
- `trace_run(...)`
- `trace_run_async(...)`
- `serialize_for_trace(...)`
- `normalize_tool_arguments(...)`
- `get_first_attr(...)`

## Framework Integrations

### Generic

```python
from agent_skill_compiler import SkillCompilerClient, trace_run

client = SkillCompilerClient.from_env(optional=False)

with trace_run(
    client,
    task_name="support_triage",
    input_text="Investigate this issue.",
    metadata={"framework": "custom"},
) as run:
    tool_call = run.tool_call(
        action_name="search_docs",
        semantic_name="knowledge_search",
        arguments={"query": "refund policy"},
    )
    run.tool_result(
        action_name="search_docs",
        semantic_name="knowledge_search",
        result={"documents": ["refund-policy-v2"]},
        tool_call_id=tool_call.event_id,
        parent_event_id=tool_call.event_id,
    )
    run.final_output(output="Escalate to billing.")
```

### Agno

```python
from agent_skill_compiler import SkillCompilerClient, run_agno_agent

client = SkillCompilerClient.from_env(optional=False)

response = run_agno_agent(
    agent,
    client,
    input="Summarize the latest billing guidance.",
    task_name="billing_guidance",
    metadata={"framework": "agno"},
)
```

### Microsoft Agent Framework

```python
from agent_skill_compiler import AsyncSkillCompilerClient, create_agent_framework_middleware

client = AsyncSkillCompilerClient.from_env(optional=False)

middleware = create_agent_framework_middleware(
    client,
    task_name="weather_assistant",
    metadata={"framework": "microsoft-agent-framework"},
)
```

## Important

- This package does not create ASC projects or keys.
- This package does not run the ASC backend.
- This package does not include the frontend.
- Keep `ASC_SECRET_KEY` on the backend only.

## License

MIT
