Report knowledge gaps with OpenAI Agents SDK and Kebivo

This tutorial runs examples/frameworks/openai-agents/agent.py. The agent has no knowledge source, so an unanswered policy question is a gap it can report to Kebivo. In a real agent, report only after checking the sources it is allowed to use.

Prerequisites

1. Start Kebivo with the quickstart. Keep MCP_ENABLED=true (the default).
2. Create a project token with feedback:gap in the Project tokens section of the project page. Copy it when shown; the page does not display it again.
3. Install uv and use Python 3.10 or later. Run the commands from the repository root. uv run reads the example’s inline dependencies and installs them for that script.

Use the Kebivo origin in KEBIVO_URL; the script adds /mcp. For a nonlocal server, use its HTTPS origin.

Check the connection

export KEBIVO_URL=http://127.0.0.1:8000
export KEBIVO_TOKEN='<PROJECT_TOKEN>'
uv run examples/frameworks/openai-agents/agent.py --list-tools

With a token that has feedback:gap, the documented local check returned:

{"tools": ["report_knowledge_gap"]}

This command does not call a model or submit feedback. If the tool is absent, check the token scope and project status. A missing or revoked token fails authentication; a disabled MCP endpoint cannot connect. See MCP tool visibility and errors.

Ask a question

The documented model run used a local OpenAI-compatible Ollama server with qwen2.5:3b. Start Ollama and make that model available, then run:

export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
export OPENAI_API_KEY=ollama
export MODEL=qwen2.5:3b
uv run examples/frameworks/openai-agents/agent.py 'How do I reset my corporate VPN?'

The script prints JSON with tool_calls and answer. If the model calls the tool, tool_calls includes report_knowledge_gap. Open Kebivo’s Inbox, find the question, and open its group detail; the occurrence shows Reported via: mcp. Kebivo returns accepted to the tool once it stores the event and processing job. Routing and delivery happen later, so check Deliveries separately.

The example defaults to hosted OpenAI gpt-5-mini when MODEL is unset. That path needs your own OPENAI_API_KEY and was not run in the documented check. See the example README for both model commands.

Adapt the pattern

The example connects MCPServerStreamableHttp to {KEBIVO_URL}/mcp with the project bearer token, then passes that server in Agent(mcp_servers=[...]). Give the agent a clear condition for reporting, such as the sample agent instructions. Do not include personal or secret data in the reported question or context. Keep the project token on the server side.

The model decides whether to call the tool, so an agent that answers successfully may still have reported nothing. If reporting is mandatory, use REST submission from application code. This example reports gaps only; corrections need a separate feedback:correction scope and human review. See the MCP guide for limits and result semantics.