# SDK methods and the katonic command

What KatonicClient in katonic-sdk 7.0.18 covers by area, the calls a stock platform refuses, and the commands the katonic CLI runs.

This page lists what the Python SDK, `katonic-sdk` 7.0.18, can do: the client's methods by area, the offline authoring modules, and the `katonic` command that ships with the package. [The Python SDK](/developers/libraries/python-sdk) covers installing it and the first call.

**Who can use it:** anyone with a `kapi_` API key from the Developer Hub. Each method needs the matching scope on the key; a call without it comes back as HTTP 403 and raises `KatonicAPIError`.

## The client's methods

`KatonicClient` is async: every method is a coroutine you `await` inside `async with KatonicClient() as k:`.

| Area | Methods |
| --- | --- |
| Agents | `list_agents`, `get_agent`, `create_agent`, `update_agent`, `publish_agent` |
| Chat and sessions | `chat`, `chat_stream`, `create_session`, `list_sessions`, `get_history`, `delete_session`, `submit_feedback` |
| Models | `list_models`, `get_model`, `completions` (OpenAI-compatible) |
| Knowledge | `list_sources`, `create_source`, `upload_documents`, `ingest`, `sync_source`, `search` |
| Knowledge graph | `load_graph`, `get_graph_schema`, `query_graph` |
| Graph schemas | `list_ontologies`, `create_ontology`, `get_ontology`, `update_ontology`, `publish_ontology`, `new_ontology_version`, `delete_ontology`, `validate_ontology`, `discover_ontology`, `list_source_ontologies`, `attach_ontology`, `detach_ontology`, `set_ontology_mode`, `baseline_ontology_violations` |
| Evaluation | `list_datasets`, `upload_dataset`, `run_evaluation`, `get_evaluation`, `poll_evaluation`, `compare_evaluations` |
| Prompt optimization | `optimize_prompt`, `get_optimization`, `poll_optimization` |
| Data flywheel | `ingest_traces`, `get_quality_trend`, `build_flywheel_dataset` |
| Skills | `list_skills`, `get_skill`, `import_skills` |
| Tools | `list_tools`, `execute_tool` |
| Guardrails | `evaluate_guardrails` |
| Usage and cost | `get_usage`, `get_analytics_usage`, `get_cost_breakdown` |

A key that runs every method needs these scopes: `chat`, `completions`, `search`, `documents`, `knowledge:sync`, `agents:read`, `agents:create`, `agents:update`, `eval:read`, `evaluations:create`, `prompt_optimization:create` (which also covers the data flywheel), `tools`, `models:read`, `guardrails:evaluate` and `usage:read`. A Builder cannot put `models:read` or `usage:read` on a key without the grants [The Python SDK](/developers/libraries/python-sdk) names.

`poll_evaluation` waits up to 300 seconds by default and `poll_optimization` up to 600, then raise `TimeoutError`. `execute_tool` takes the MCP server's name, then the tool name, then the arguments.

## Calls a stock platform refuses

Deleting a graph schema (`delete_ontology`) reaches the platform and is refused for every key, whatever its scopes: the knowledge service does not let the public API delete a schema. Delete a draft schema in Studio.

Creating a knowledge source, uploading documents and authoring graph schemas work, provided the key carries the **Documents** scope and its owner may create knowledge sources.

## Offline authoring

The rest of the package builds an agent's configuration on your machine, with no platform:

- `katonic.gateway`, `katonic.knowledge`, `katonic.guardrails` and `katonic.tools` build an agent's bindings: its model, knowledge sources, guardrail profile and tools.
- `katonic.compose` wires sub-agents into one workflow: a coordinator, a sequential pipeline, a parallel fan-out, a router or a mix.
- `katonic.scaffold` writes a blueprint package.
- `katonic.evaluate` writes local evaluation datasets and configurations.
- `katonic.connectors` is the base class for a custom knowledge connector.

## The katonic command

Installing the SDK puts a `katonic` command on your path. It reads `KATONIC_API_KEY` and `KATONIC_BASE_URL` first, then the values `katonic login` saved in a `.katonic` folder in your home directory. Set the base URL one way or the other: without it the client calls a local address.

| Command | What it does |
| --- | --- |
| `katonic login` | Saves an API key and base URL, with `--key` and `--url` or by asking. |
| `katonic agents list`, `get <id>`, `create <name>`, `chat <agent-id> "<message>"` | Agent calls. |
| `katonic sessions list`, `history <session-id>` | Session calls. |
| `katonic skills list`, `get`, `export`, `import <paths>` | The skill library; `import` takes SKILL.md files or folders. |
| `katonic search "<query>"` | Knowledge search, `--top-k` results (5 by default). |
| `katonic eval run <agent-id> <dataset-id>`, `eval compare <run-a> <run-b>` | Starts an evaluation and waits for it, or compares two runs. |
| `katonic optimize <agent-id> <dataset-id>` | Starts a prompt optimization. |
| `katonic flywheel trend <agent-id>` | The agent's quality trend. |
| `katonic tools list`, `tools exec <server> <tool> '<json>'` | Lists tools, or runs one. |
| `katonic models list`, `katonic usage` | Models, and usage. |
| `katonic compose`, `katonic scaffold` | The offline authoring commands. |

`katonic --help` lists every option. Add `--verbose` to see the full error when a command fails. The `katonic-admin` command is a different tool for operators; see [The Katonic CLI](/developers/libraries/cli).

## Related

- [The Python SDK](/developers/libraries/python-sdk)
- [Use the SDK in a workspace](/developers/libraries/python-sdk-workspace)
- Public API reference
- Authentication

Source: https://docs.katonic.ai/developers/libraries/python-sdk-methods
