Metadata-Version: 2.4
Name: coval-agent-sdk
Version: 0.1.1
Summary: Python client for Coval Agent SDK voice sessions
Author: Coval, Inc.
License-Expression: Apache-2.0
Project-URL: Source, https://github.com/coval-ai/coval-agent-sdk
Project-URL: Documentation, https://docs.coval.ai/sdks/agent-sdk
Project-URL: Issues, https://github.com/coval-ai/coval-agent-sdk/issues
Project-URL: Changelog, https://github.com/coval-ai/coval-agent-sdk/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: coval-sdk<0.10,>=0.9.2
Requires-Dist: urllib3<3,>=2.1
Requires-Dist: websockets<16,>=15
Provides-Extra: tracing
Requires-Dist: opentelemetry-api<2,>=1.30; extra == "tracing"
Requires-Dist: opentelemetry-sdk<2,>=1.30; extra == "tracing"
Requires-Dist: opentelemetry-exporter-otlp-proto-common<2,>=1.30; extra == "tracing"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: pytest-asyncio<2,>=0.24; extra == "dev"
Requires-Dist: pyright==1.1.414; extra == "dev"
Requires-Dist: python-semantic-release==10.7.0; extra == "dev"
Requires-Dist: ruff==0.17.1; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Dynamic: license-file

# Coval Agent SDK

Connect your Python voice pipeline to Coval's simulated callers. Your application runs the agent; Coval records and evaluates the conversation. The SDK uses an outbound WebSocket, so your agent does not need a public endpoint.

Requires **Python 3.10 or newer**.

## Install

```sh
python -m pip install coval-agent-sdk
```

Import the package as `coval_agent_sdk`. See the [Agent SDK guide](https://docs.coval.ai/sdks/agent-sdk) for integration details and [PyPI](https://pypi.org/project/coval-agent-sdk/) for available versions.

## Run a conversation

A run uses an SDK WebSocket agent, voice persona, and test set from the same workspace. Pass credentials and resource IDs to the client and `RunConfig`; this example reads them from environment variables.

The handler below echoes the caller's audio to check the connection. In an agent integration, the handler connects the audio stream to your voice pipeline.

```python
import asyncio
import os

import coval_agent_sdk


async def on_connection(connection: coval_agent_sdk.AudioConnection) -> None:
    async for audio in connection.receive_audio():
        await connection.send_audio(audio)


async def main() -> coval_agent_sdk.RunResult:
    client = coval_agent_sdk.CovalVoiceClient(
        api_key=os.environ["COVAL_API_KEY"],
        workspace_id=os.environ["COVAL_WORKSPACE_ID"],
    )
    config = coval_agent_sdk.RunConfig(
        agent_id=os.environ["COVAL_AGENT_ID"],
        persona_id=os.environ["COVAL_PERSONA_ID"],
        test_set_id=os.environ["COVAL_TEST_SET_ID"],
        iterations=1,
        concurrency=1,
        run_timeout_seconds=600,
    )
    return await client.run(config, on_connection=on_connection)


if __name__ == "__main__":
    result = asyncio.run(main())
    print(result.run_id, result.status)
```

`on_connection` receives a ready `AudioConnection`. Feed `receive_audio()` into your pipeline and independently send its speech with `send_audio()`. Keep the handler active until the conversation ends, then finish conversation tasks and spans before returning. Handlers may run concurrently; keep conversation state separate.

The client defaults to `https://api.coval.dev/v1`. Set `api_base_url` to use another API root. Audio is PCM16 little-endian, mono, 16 kHz; see the [audio guide](https://docs.coval.ai/sdks/agent-sdk#audio-format-and-limits) for format and buffering requirements.

## Connect to an existing simulation

`connect()` attaches to one simulation without creating a run:

```python
async def attach(
    client: coval_agent_sdk.CovalVoiceClient, simulation_id: str
) -> coval_agent_sdk.ConversationResult | None:
    async with client.connect(simulation_id) as connection:
        await on_connection(connection)
    return connection.result
```

Read `connection.result` after the context exits successfully. Leaving before voice completion raises an error. Local timeout or cancellation stops local work without cancelling the hosted run.

## Results and errors

`RunResult` contains the run ID, hosted status, and completed `conversations`. Each `ConversationResult` includes its simulation ID, audio byte counts, and optional trace delivery result. Execution completion does not mean the agent passed its evaluation criteria.

Catch `CovalError` for SDK failures. After launch, `RunError.result` retains the run ID, last observed status, and completed conversations. Application exceptions and cancellation propagate unchanged. See [Developer API](docs/developer-api.md) for result types and argument validation.

## Tracing

```sh
python -m pip install "coval-agent-sdk[tracing]"
```

Share one `CovalTraceExporter` between your OpenTelemetry provider and `CovalVoiceClient(trace_exporter=...)`. Correlate the conversation root with `connection.simulation_id` and finish spans before the handler returns. The [tracing guide](https://docs.coval.ai/sdks/agent-sdk#optional-opentelemetry-traces) includes a setup example.

## Terraform

[Manage test configuration with Terraform](https://docs.coval.ai/sdks/terraform-provider) and pass the resulting resource IDs to the SDK. Use Coval to review recordings, evaluations, and traces.

## Contributing

[CONTRIBUTING.md](CONTRIBUTING.md) covers setup, tests, and review. See [local development](docs/local-development.md), [Python conventions](docs/python-style.md), and [architecture](docs/architecture.md) for contributor guidance. [CHANGELOG.md](CHANGELOG.md) records releases; [SECURITY.md](SECURITY.md) explains private vulnerability reporting.

## License

Copyright 2026 Coval, Inc. Licensed under the [Apache License, Version 2.0](LICENSE). See [NOTICE](NOTICE) for attribution.
