Metadata-Version: 2.4
Name: kaiwen-agent
Version: 0.1.0a2
Summary: Provider-neutral asynchronous agent runtime
Project-URL: Homepage, https://github.com/ImtheKaiwen/kaiwen-agent-platform
Project-URL: Documentation, https://github.com/ImtheKaiwen/kaiwen-agent-platform/tree/main/docs
Project-URL: Repository, https://github.com/ImtheKaiwen/kaiwen-agent-platform.git
Project-URL: Issues, https://github.com/ImtheKaiwen/kaiwen-agent-platform/issues
Author: Kaiwen
License: MIT
Keywords: agent,ai,asyncio,openai,tools
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic<3,>=2.10
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.14; extra == 'dev'
Requires-Dist: openai<3,>=2; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: python-dotenv<2,>=1.1; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai<3,>=2; extra == 'openai'
Provides-Extra: release
Requires-Dist: build<2,>=1.2; extra == 'release'
Requires-Dist: twine<7,>=6; extra == 'release'
Description-Content-Type: text/markdown

# kaiwen-agent

Provider-neutral, asynchronous Python runtime for building tool-using agents.
Product applications own their prompts, domain tools, authorization context,
persistence choice, and HTTP surface.

```bash
pip install "kaiwen-agent[openai]"
```

## Minimal agent

```python
import asyncio

from pydantic import BaseModel

from kaiwen_agent import Agent, AgentContext, tool
from kaiwen_agent.models.openai import OpenAIResponsesProvider
from kaiwen_agent.types import AgentInput


class ProjectQuery(BaseModel):
    category: str | None = None


@tool(
    name="projects.read",
    description="List projects visible to the current user",
    input_model=ProjectQuery,
    permissions={"projects.read"},
)
async def read_projects(
    context: AgentContext,
    query: ProjectQuery,
) -> list[dict[str, str]]:
    repository = context.services["projects"]
    return await repository.list(category=query.category)


async def main() -> None:
    agent = Agent(
        name="portfolio",
        model=OpenAIResponsesProvider(
            model="your-model-id",
            instructions="Help visitors discover relevant products.",
            store=False,
        ),
        tools=[read_projects],
        permissions={"projects.read"},
    )
    result = await agent.run(
        AgentInput(text="Show me the games"),
        context=AgentContext(
            session_id="session-id",
            permissions=frozenset({"projects.read"}),
            services={"projects": your_repository},
        ),
    )
    print(result.text)


asyncio.run(main())
```

`OPENAI_API_KEY` is read by the OpenAI SDK from the server environment. The
runtime never stores it and it must never be exposed to browser code.

## Runtime capabilities

- Provider-neutral async agent loop and deterministic fake provider.
- Typed Pydantic tool inputs and deny-by-default permission intersection.
- Approval, idempotency, timeout, and retry handling for side effects.
- Session, run, event, and audit ports with a SQLite reference adapter.
- SSE event fan-out and trace propagation.
- Durable task graphs, workers, checkpoints, mailbox control, resource locks,
  cancellation, and bounded concurrency.
- Optional OpenAI Responses API adapter.

## Side effects

Tools marked `reversible` or `destructive` receive a runtime idempotency key.
Set `requires_approval=True` and supply an application-owned `ApprovalGate` for
publishing, deleting, deploying, calling, or sending messages. Applications
must still perform authorization inside their own service boundary.

## Coding-agent handoff

When asking another coding agent to integrate this package, provide the root
repository files `AGENTS.md` and `docs/consumer-agent-brief.md`. The complete,
provider-free example is in `examples/basic-agent`.
