Microsoft Copilot Studio

Kyvvu provides a dedicated endpoint for Copilot Studio agents: POST /api/v1/copilot/log. Unlike the Python SDK, there's no library to install — the integration is a custom Power Platform connector that you call explicitly from your topic's conversation flow using a Call an action node.

The full source is in examples/copilot-agent/ in the platform repo.

---

How it works

Copilot Studio conversations are mapped to Kyvvu tasks via the conversation_id. Each call to the endpoint logs one step. The endpoint handles the bookkeeping that the SDK would normally manage:

• Agent auto-registration — on the first call for a given agent name, the agent is registered automatically using the fields you pass in

• Step tracking — steps are numbered automatically within each conversation; you supply the node_type and node_name

• Task lifecycle — a START_NODE call opens a task; an END_NODE call closes it; a 5-minute inactivity timeout logs INTERNAL_TASK_UNFINISHED if no END_NODE arrives

---

Step 1 — Create the custom connector

In Power Automate (make.powerautomate.com), go to Data → Custom connectors → + New custom connector → Import an OpenAPI file. Upload the Kyvvu OpenAPI spec, set the base URL to your Kyvvu API URL, and configure API Key authentication with your Kyvvu API key.

Once saved, the connector — KyvvuConnector — is available across your Power Platform environment and to all Copilot Studio agents in it.

---

Step 2 — Add the action to your topic

In your Copilot Studio agent, open the topic you want to instrument. At each point you want to log, insert a Call an action node and select KyvvuConnector → Log Copilot Step.

The action takes 8 inputs:

Input	Value
conversation_id	System.Conversation.Id (built-in Copilot Studio variable)
node_type	The step type — e.g. START_NODE, USER_INPUT, END_NODE
node_name	A human-readable name for this step
x-ms-entra-agent-name	Your agent's name — used for auto-registration
input_data	What the agent received at this step (optional)
output_data	What the agent produced at this step (optional)
agent_purpose	Agent purpose — used for auto-registration (optional)
agent_risk_classification	Risk level: minimal, limited, high (optional)

The action returns a Result record containing log_id, step number, and any incidents generated by policy evaluation.

---

Step 3 — Wire up a topic

A typical topic conversation flow looks like this:

Trigger
  → [Log: START_NODE "conversation_start"]
  → Question node
  → [Log: USER_INPUT "city_requested"]
  → HTTP / action call
  → [Log: TOOL_CALL "weather_api_called"]
  → Message node
  → [Log: END_NODE "conversation_end"]

Each Log Copilot Step node is a Call an action node pointing at KyvvuConnector. For example, the opening log call for a weather agent:

Field	Value
conversation_id	System.Conversation.Id
node_type	START_NODE
node_name	conversation_start
x-ms-entra-agent-name	Kyvvu Weather Agent
agent_purpose	Answers weather queries for employees
agent_risk_classification	limited

And the closing call:

Field	Value
conversation_id	System.Conversation.Id
node_type	END_NODE
node_name	conversation_end
x-ms-entra-agent-name	Kyvvu Weather Agent

---

Agent auto-registration

On the first call for a given x-ms-entra-agent-name, Kyvvu registers the agent automatically using the fields you provide. You don't need to touch the dashboard to set it up — the agent appears there after the first conversation. Subsequent calls update the step counter and extend the task.

---

Handling incidents

The response from each Log Copilot Step call includes an incidents array. If a policy is violated, the incident is already recorded in Kyvvu — but you can also act on it in-flow. For example, routing to a human escalation path when a high-severity incident is detected:

[Log Copilot Step]
  → Result.incidents is not empty?
      Yes → branch to escalation topic
      No  → continue normal flow

This is optional. If you don't inspect the incidents output, violations are still recorded in Kyvvu and will appear in the dashboard and trigger any configured automated actions.

---

Comparison with the Python SDK

	Python SDK	Copilot Studio
Step tracking	Automatic	Manual — one Call an action node per step
Agent registration	kv.register_agent() at startup	Auto on first call via x-ms-entra-agent-name
Task ID	SDK-generated UUID	System.Conversation.Id
Endpoint	/api/v1/logs	/api/v1/copilot/log

The audit trail in the dashboard looks identical regardless of which integration you use.