From ec1cb1e661b5f359c50dd4b5d5afe61d3564b936 Mon Sep 17 00:00:00 2001 From: Matan Grady Date: Mon, 29 Sep 2025 12:40:20 +0300 Subject: [PATCH 1/9] migration guide --- docs/ai-interfaces/migration_guide | 298 +++++++++++++++++++++++++++++ 1 file changed, 298 insertions(+) create mode 100644 docs/ai-interfaces/migration_guide diff --git a/docs/ai-interfaces/migration_guide b/docs/ai-interfaces/migration_guide new file mode 100644 index 0000000000..3085046538 --- /dev/null +++ b/docs/ai-interfaces/migration_guide @@ -0,0 +1,298 @@ +--- +sidebar_position: 8 +title: Port AI closed-beta migration guide +--- + +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" + +# Port AI Platform Migration Guide + +:::warning Migration Required +This guide covers the migration from the legacy AI system to the new Port AI platform. All users must complete this migration by **October 15, 2025** to continue using AI features. +::: + +## What's Changing + +We're excited to announce a major upgrade to Port's AI capabilities that will transform how you interact with your developer portal. This migration introduces our new **[Port AI assistant](/ai-interfaces/port-ai/overview)** - an intelligent, context-aware agent that understands your entire engineering ecosystem. + +### Key Improvements + +**🤖 Enhanced Port AI Assistant** +An out-of-the-box intelligent agent with [MCP (Model Context Protocol)](/ai-interfaces/port-mcp-server/overview-and-installation) support, providing instant insights about your services, ownership, incidents, and engineering operations with improved accuracy and performance. + +**🎨 Enhanced UI Experience** +A completely redesigned interface optimized for AI-powered workflows, making it easier to get answers and take actions through natural language. + +**🔄 Upgraded Architecture** +Streaming responses, improved performance, and better extensibility for AI-powered operations across your engineering platform. Your existing [AI agents](/ai-interfaces/ai-agents/overview) will continue to work with updated schemas. + +**✨ Using Anthropic Sonnet 4 model** +Using the advanced Sonnet 4 model for better results using the [Port MCP server](/ai-interfaces/port-mcp-server/overview-and-installation), increased accuracy is achieved. If you wish to continue using OpenAI GPT models, contact the AI team for further instructions. + +:::info Model Performance +We observed lower accuracy with OpenAI GPT models and recommend keeping the Sonnet models (provided by our cloud infrastructure in similar measures like OpenAI models). +::: + +## Migration Timeline & Phases + +### Phase 1: Transition Period (October 1-15, 2025) + +:::tip Testing Period +During this phase, you can test the new system while your existing integrations continue to work. +::: + +- New Port AI is available with backward compatibility +- Existing AI agents continue working +- Time to test and migrate at your pace + +### Phase 2: Full Migration (October 15, 2025+) + +:::warning End of Compatibility +After October 15, backward compatibility will be removed and all integrations must use the new system. +::: + +- Backward compatibility removed +- All integrations must use new endpoints and schemas + +## Migration Guide by Interface + +### 🔌 API Integrations + +**Who's affected:** Customers using custom AI API integrations +**What changes:** Endpoint updates and required parameters + +:::warning Endpoint Deprecation +The `/agent/invoke` endpoint (agent router) will be deprecated. You have two migration paths to choose from. +::: + +You have two migration paths: + + + + +**Best for:** Integrations where YOU build the logic to select which agent to route to based on context, OR if you use one general agent. + +

Phase 1 - Now

+ +Update your API calls to include new parameters: + +```javascript showLineNumbers +// Current +POST /agent/invoke +{ + "query": "your question", + "agent_id": "agent_identifier" +} + +// Update to (specific agent - you choose which one) +POST /agent/{agent_identifier}/invoke?stream=true&useMCP=true +{ + "query": "your question", +} +``` + +

Phase 2 - By October 15

+ +Continue using the same `/agent/{agent_identifier}/invoke` endpoint with updated blueprint schemas. The updated schemas will be sent prior to this date. + + + + +**Best for:** Generic "ask Port AI anything" integrations + +

Phase 1 - Now

+ +Migrate directly to the new AI assistant: + +```javascript showLineNumbers +// Migrate to +POST /ai/invoke +{ + "query": "your question", + "userSystemPrompt": "optional custom instructions", + "tools": ["optional", "tool", "list"] +} +``` + +This endpoint doesn't require pre-configured agents, automatically uses streaming and MCP, and provides out-of-the-box intelligence. + + + + +:::info API Reference +The new API uses streaming responses for real-time results. Full [API reference](/ai-interfaces/port-ai/api-interaction) and implementation details will be shared by Oct 1st. +::: + +### ⚙️ Workflow Automations + +**Who's affected:** Teams using AI agents in automations +**What changes:** Parameter updates and endpoint migration + +#### Phase 1 - Now + +- Automations are assumed to use specific agents using the `/agent/{agent_identifier}/invoke` endpoint +- Add `useMCP=true` and `stream=true` to all automation configurations +- Test automations with new parameters + +#### Phase 2 - By October 15 + +- Once updated by Port's team, you can remove the query parameters as they will be used by default +- Update your blueprints schemas. The updated schemas will be sent prior to this date + +### 💬 Slack Integration + +**Who's affected:** Teams using Port AI through Slack +**What changes:** Service interruption starting October 1 + +:::caution Service Interruption +Slack integration will stop working completely during the migration. No backward compatibility will be provided. +::: + +**Timeline:** + +- **October 1:** Slack integration stops working +- **Q1 2025:** New integration planned (subject to change) + +**Immediate Action Required:** + +- Stop using Slack integration +- Switch to Port web UI or API integration + + +### 🖥️ AI Agent Widget (UI) + +**Who's affected:** Teams using AI widgets in the Port UI +**What changes:** None - seamless automatic migration + +:::tip Easy Migration +This is the simplest migration path with minimal manual work required. +::: + +Edit your AI agent widgets to toggle on the `useMCP` flag. Test to ensure it works as expected. + +By October 15th, the remaining widgets will be automatically migrated to this flag, so the behavior will change to use the new MCP behind the scenes, including the usage of the Anthropic Sonnet 4 model. + +## Blueprint Schema Updates + +### Affected Blueprints + +Two system blueprints require schema updates: + +- `ai_invocation` blueprint +- `ai_agent` blueprint + +### Phase 1 - By October 15 + +:::info Schema Compatibility +Both old and new schemas will be supported during this period to ensure smooth transition. +::: + +- Manually update your AI agent entities to match the new schema +- Verify everything works correctly with the new schema +- This must come AFTER you have completed the integrations migration + +### Phase 2 - October 15+ + +:::warning Schema Migration +Schemas will be automatically migrated. Existing agents might break if not updated in Phase 1. +::: + +- Schemas will be automatically migrated +- Existing agents might break if not updated in Phase 1 +- Only new schemas are supported + +### Action Required + +1. Review the new schema requirements in your Port environment (schemas will be shared by Oct 1st) +2. Update your AI agent entities during Phase 1 +3. Test functionality before automatic migration + +## Updated Quotas & Rate Limits + +With the open beta launch, new monthly quotas and rate limits apply immediately: + +:::info Quota Changes +These limits apply immediately upon migration to ensure system stability and fair usage. +::: + +- Monthly quotas adjusted based on your plan type +- Hourly rate limits for system protection + +If you reach these limits, reach out to us to make sure you have the right limit. + +## Migration Checklist + +### ✅ Immediate Actions + +- [ ] Identify all AI agent usage points (API, Automations, Slack, UI) +- [ ] Stop using Slack integration +- [ ] Plan your migration plan +- [ ] Update API calls with `stream=true` and `useMCP=true` +- [ ] Update automation & AI widgets parameters +- [ ] Test integrations with new parameters +- [ ] Migrate to the new schema + +### 📋 By October 15 (Phase 1) + +- [ ] Complete schema migration +- [ ] Update to final API endpoints +- [ ] Remove legacy configurations +- [ ] Verify all integrations work + +## Support & Resources + +### 📚 Documentation + +For more details on specific migration topics, see: + +- [Port AI Overview](/ai-interfaces/port-ai/overview) - Understanding the new AI system +- [AI API Interaction](/ai-interfaces/port-ai/api-interaction) - API reference and examples +- [AI Agents Overview](/ai-interfaces/ai-agents/overview) - Working with AI agents +- [Port MCP Server](/ai-interfaces/port-mcp-server/overview-and-installation) - Model Context Protocol integration + +### 💬 Get Help + +- Contact Port's AI team through your shared Slack channel +- Reach out to your Technical Success Manager + +## Frequently Asked Questions + +
+What do I need to do now? (Click to expand) + +Check if you're using API integrations, workflow automations, or Slack with AI agents. API and automations need updates by October 15, Slack users should switch to alternatives immediately. + +
+ +
+Will my existing AI agents break? (Click to expand) + +They'll continue working during October with backward compatibility. You must migrate to new schemas by October 15 or they might break during automatic migration. + +
+ +
+Why are you making this change? (Click to expand) + +Based on your feedback, we've upgraded our infrastructure to provide better performance, streaming responses, and [MCP support](/ai-interfaces/port-mcp-server/overview-and-installation) while maintaining your existing AI agents with improved capabilities. + +
+ +
+When will Slack integration be available again? (Click to expand) + +We're targeting Q1 2025 for the new Slack integration, but this timeline may change. + +
+ +
+Is this production-ready? (Click to expand) + +This is an open beta release. While fully functional, it's not recommended for production-critical workflows initially. + +
+ +--- + +*We're committed to making this migration as smooth as possible. The new Port AI represents a significant leap forward in how platform teams can leverage AI to accelerate their engineering operations.* \ No newline at end of file From c1d5f44069688a81c7804143c91fbd3ead493085 Mon Sep 17 00:00:00 2001 From: Matan Grady Date: Mon, 29 Sep 2025 12:49:50 +0300 Subject: [PATCH 2/9] add prefix --- docs/ai-interfaces/{migration_guide => migration_guide.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/ai-interfaces/{migration_guide => migration_guide.md} (100%) diff --git a/docs/ai-interfaces/migration_guide b/docs/ai-interfaces/migration_guide.md similarity index 100% rename from docs/ai-interfaces/migration_guide rename to docs/ai-interfaces/migration_guide.md From 9a964f3c3be735f5810835307763caa0667e4e13 Mon Sep 17 00:00:00 2001 From: Matan Grady Date: Mon, 29 Sep 2025 13:23:06 +0300 Subject: [PATCH 3/9] update to 2026 --- docs/ai-interfaces/migration_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ai-interfaces/migration_guide.md b/docs/ai-interfaces/migration_guide.md index 3085046538..0800989082 100644 --- a/docs/ai-interfaces/migration_guide.md +++ b/docs/ai-interfaces/migration_guide.md @@ -152,7 +152,7 @@ Slack integration will stop working completely during the migration. No backward **Timeline:** - **October 1:** Slack integration stops working -- **Q1 2025:** New integration planned (subject to change) +- **Q1 2026:** New integration planned (subject to change) **Immediate Action Required:** From 3e7698068fe27f6456081eeacddc345df728f3ce Mon Sep 17 00:00:00 2001 From: Matan Grady Date: Tue, 30 Sep 2025 16:28:12 +0300 Subject: [PATCH 4/9] add ai agent schema --- docs/ai-interfaces/migration_guide.md | 161 +++++++++++++++++++++++++- 1 file changed, 158 insertions(+), 3 deletions(-) diff --git a/docs/ai-interfaces/migration_guide.md b/docs/ai-interfaces/migration_guide.md index 0800989082..61418f52ab 100644 --- a/docs/ai-interfaces/migration_guide.md +++ b/docs/ai-interfaces/migration_guide.md @@ -204,9 +204,164 @@ Schemas will be automatically migrated. Existing agents might break if not updat ### Action Required -1. Review the new schema requirements in your Port environment (schemas will be shared by Oct 1st) -2. Update your AI agent entities during Phase 1 -3. Test functionality before automatic migration +1. **By October 8th:** Manually update your AI agent entities to the new schema format for testing and adjustment +2. **October 8-15:** Test functionality with the new schema to ensure everything works correctly +3. **October 15th+:** Automatic migration will occur - agents not manually updated may break + +### New AI Agent Schema + +:::warning Manual Schema Update Required +Starting **October 8th**, you must manually update your AI blueprints schemas to the new format for testing and adjustment. + +Starting **October 15th**, schemas will be automatically migrated, but existing agents might break if not manually updated during the testing period. +::: + +
+View the new AI agent schema (Click to expand) + +```json +{ + "identifier": "_ai_agent", + "title": "AI Agent", + "icon": "Details", + "ownership": { + "type": "Direct", + "title": "Owning Teams" + }, + "schema": { + "properties": { + "description": { + "icon": "DefaultProperty", + "type": "string", + "title": "Description", + "description": "Brief explanation of what this agent does" + }, + "status": { + "icon": "DefaultProperty", + "title": "Status", + "description": "Is the agent active (available to be run manually, or allowed to operate autonomously)", + "type": "string", + "enum": [ + "active", + "inactive" + ], + "enumColors": { + "active": "green", + "inactive": "red" + }, + "default": "active" + }, + "tools": { + "items": { + "type": "string" + }, + "icon": "DefaultProperty", + "type": "array", + "title": "Tools", + "description": "An array of tools that the agent is allowed to execute. Docs: https://docs.port.io/ai-interfaces/port-ai/api-interaction#tool-selection", + "default": [ + "^(list|get|search|track|describe)_.*" + ] + }, + "prompt": { + "icon": "DefaultProperty", + "type": "string", + "maxLength": 2500, + "title": "Prompt", + "format": "markdown", + "description": "The system prompt for the agent. Where the agent is manually invoked, a user prompt will be provided in the invocation" + }, + "execution_mode": { + "title": "Execution Mode", + "type": "string", + "enum": [ + "Automatic", + "Approval Required" + ], + "default": "Approval Required", + "description": "The execution mode for actions - Automatic or requiring approval" + }, + "conversation_starters": { + "items": { + "type": "string" + }, + "icon": "Chat", + "type": "array", + "title": "Conversation Starters", + "description": "Predefined conversation starter messages to help users interact with this agent" + }, + "provider": { + "type": "string", + "title": "Provider", + "description": "The provider of the agent" + }, + "model": { + "type": "string", + "title": "Model", + "description": "The model of the agent" + }, + "labels": { + "type": "object", + "title": "Labels", + "description": "Free labels to identify specific attributes on the agent" + } + }, + "required": [ + "tools", + "status", + "prompt" + ] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": { + "total_invocations": { + "title": "Total Invocations", + "type": "number", + "description": "The number of invocations for this agent", + "target": "_ai_invocations", + "calculationSpec": { + "func": "count", + "calculationBy": "entities" + } + }, + "average_input_tokens": { + "title": "Average input tokens", + "type": "number", + "description": "The average input tokens for this agent invocations", + "target": "_ai_invocations", + "calculationSpec": { + "func": "median", + "property": "prompt_tokens", + "calculationBy": "property" + } + }, + "average_output_tokens": { + "title": "Average output tokens", + "type": "number", + "description": "The average output tokens for this agent invocations", + "target": "_ai_invocations", + "calculationSpec": { + "func": "median", + "property": "completion_tokens", + "calculationBy": "property" + } + } + }, + "relations": {} +} +``` + +
+ +
+ +View the new AI Invocation schema (Click to expand) + +```json +TBD +``` +
## Updated Quotas & Rate Limits From 6ec4a083e78b807de870465f2cb7df537d9f2440 Mon Sep 17 00:00:00 2001 From: Matan Grady Date: Tue, 30 Sep 2025 16:55:10 +0300 Subject: [PATCH 5/9] update use_mcp syntax --- docs/ai-interfaces/migration_guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/ai-interfaces/migration_guide.md b/docs/ai-interfaces/migration_guide.md index 61418f52ab..1621692066 100644 --- a/docs/ai-interfaces/migration_guide.md +++ b/docs/ai-interfaces/migration_guide.md @@ -86,7 +86,7 @@ POST /agent/invoke } // Update to (specific agent - you choose which one) -POST /agent/{agent_identifier}/invoke?stream=true&useMCP=true +POST /agent/{agent_identifier}/invoke?stream=true&use_mcp=true { "query": "your question", } @@ -132,7 +132,7 @@ The new API uses streaming responses for real-time results. Full [API reference] #### Phase 1 - Now - Automations are assumed to use specific agents using the `/agent/{agent_identifier}/invoke` endpoint -- Add `useMCP=true` and `stream=true` to all automation configurations +- Add `use_mcp=true` and `stream=true` to all automation configurations - Test automations with new parameters #### Phase 2 - By October 15 @@ -169,7 +169,7 @@ Slack integration will stop working completely during the migration. No backward This is the simplest migration path with minimal manual work required. ::: -Edit your AI agent widgets to toggle on the `useMCP` flag. Test to ensure it works as expected. +Edit your AI agent widgets to toggle on the `use_mcp` flag. Test to ensure it works as expected. By October 15th, the remaining widgets will be automatically migrated to this flag, so the behavior will change to use the new MCP behind the scenes, including the usage of the Anthropic Sonnet 4 model. @@ -383,7 +383,7 @@ If you reach these limits, reach out to us to make sure you have the right limit - [ ] Identify all AI agent usage points (API, Automations, Slack, UI) - [ ] Stop using Slack integration - [ ] Plan your migration plan -- [ ] Update API calls with `stream=true` and `useMCP=true` +- [ ] Update API calls with `stream=true` and `use_mcp=true` - [ ] Update automation & AI widgets parameters - [ ] Test integrations with new parameters - [ ] Migrate to the new schema From aab9877d51c7f35da49cc1cae05e2327bf6cf878 Mon Sep 17 00:00:00 2001 From: Matan Grady Date: Thu, 2 Oct 2025 22:34:01 +0300 Subject: [PATCH 6/9] updated schema for /ai/invoke --- docs/ai-interfaces/migration_guide.md | 96 +++++++++++++++++++++++++-- 1 file changed, 91 insertions(+), 5 deletions(-) diff --git a/docs/ai-interfaces/migration_guide.md b/docs/ai-interfaces/migration_guide.md index 1621692066..6513a12bdd 100644 --- a/docs/ai-interfaces/migration_guide.md +++ b/docs/ai-interfaces/migration_guide.md @@ -107,21 +107,107 @@ Migrate directly to the new AI assistant: ```javascript showLineNumbers // Migrate to -POST /ai/invoke +POST /v1/ai/invoke { - "query": "your question", - "userSystemPrompt": "optional custom instructions", - "tools": ["optional", "tool", "list"] + "userPrompt": "what services do we have?", + "labels": { + "source": "test" + }, + "systemPrompt": "you are a devops guru at the company, your task is to help developers with software infrastructure stuff", + "executionMode": "Manual Approval", + "tools": ["^(list|get|search|track|describe)_.*"] } ``` +### Request Parameters + +The `/v1/ai/invoke` endpoint accepts the following parameters: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `userPrompt` | string | ✅ | The user's question or request in natural language | +| `systemPrompt` | string | ❌ | Custom instructions that provide context about your organization, terminology, or specific requirements for the AI to consider in each request | +| `executionMode` | string | ❌ | Controls how action execution tools behave. Options: `"Automatic"` or `"Manual Approval"` (default: `"Manual Approval"`) | +| `tools` | array | ❌ | Array of regex patterns to control which [Port MCP tools](/ai-interfaces/port-ai/api-interaction#tool-selection) are available. Default: `["^(list|get|search|track|describe)_.*"]` | +| `labels` | object | ❌ | Free-form labels for tracking and filtering AI invocations (e.g., `{"source": "monitoring", "environment": "production"}`) | + +### Execution Modes + +The `executionMode` parameter controls how Port AI handles action execution tools: + +- **`"Manual Approval"`** (default): Port AI creates draft actions that require your review before execution +- **`"Automatic"`**: Port AI executes actions immediately based on your request + +:::info Tool Selection +The `tools` parameter uses regex patterns to control which MCP tools are available. For example: +- `["^(list|get|search|track|describe)_.*"]` - Read-only operations only +- `["^run_.*"]` - Action execution only +- `["run_.*github.*", "run_.*jira.*"]` - Specific integration actions + +Learn more about [tool selection patterns](/ai-interfaces/port-ai/api-interaction#tool-selection). +::: + This endpoint doesn't require pre-configured agents, automatically uses streaming and MCP, and provides out-of-the-box intelligence. +
+Migration Examples (Click to expand) + +Here are practical examples of migrating from the old `/agent/invoke` endpoint to the new `/v1/ai/invoke` endpoint: + +**Example 1: Basic Query Migration** +```javascript showLineNumbers +// Old endpoint +POST /agent/invoke +{ + "query": "What services are failing health checks?", + "agent_id": "monitoring_agent" +} + +// New endpoint +POST /v1/ai/invoke +{ + "userPrompt": "What services are failing health checks?", + "systemPrompt": "You are a monitoring specialist. Focus on health metrics and provide actionable insights.", + "executionMode": "Manual Approval", + "tools": ["^(list|get|search)_.*"], + "labels": { + "source": "monitoring_dashboard", + "environment": "production" + } +} +``` + +**Example 2: Action Execution Migration** +```javascript showLineNumbers +// Old endpoint +POST /agent/invoke +{ + "query": "Create an incident for the payment service", + "agent_id": "incident_agent" +} + +// New endpoint +POST /v1/ai/invoke +{ + "userPrompt": "Create an incident for the payment service", + "systemPrompt": "You are an incident response specialist. Always include severity levels and impact assessment.", + "executionMode": "Automatic", + "tools": ["^(list|get|search)_.*", "run_.*incident.*"], + "labels": { + "source": "automation", + "service": "payment", + "trigger": "health_check_failure" + } +} +``` + +
+ :::info API Reference -The new API uses streaming responses for real-time results. Full [API reference](/ai-interfaces/port-ai/api-interaction) and implementation details will be shared by Oct 1st. +The new API uses streaming responses for real-time results. See the [API interaction documentation](/ai-interfaces/port-ai/api-interaction) for complete details on request/response formats, streaming events, and error handling. ::: ### ⚙️ Workflow Automations From 0ac4a4e477f5a684e85bd5350e0833eb22b75be4 Mon Sep 17 00:00:00 2001 From: Matan Grady Date: Tue, 7 Oct 2025 07:07:49 +0300 Subject: [PATCH 7/9] AI invocation schema --- docs/ai-interfaces/migration_guide.md | 103 +++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/docs/ai-interfaces/migration_guide.md b/docs/ai-interfaces/migration_guide.md index 6513a12bdd..a4133fc50e 100644 --- a/docs/ai-interfaces/migration_guide.md +++ b/docs/ai-interfaces/migration_guide.md @@ -445,7 +445,108 @@ Starting **October 15th**, schemas will be automatically migrated, but existing View the new AI Invocation schema (Click to expand) ```json -TBD +{ + "identifier": "_ai_invocations", + "description": "For each agent request a match feedback entity will be created", + "title": "AI Invocation", + "icon": "Star", + "schema": { + "properties": { + "status": { + "icon": "DefaultProperty", + "title": "Status", + "type": "string", + "description": "The agent invocation status", + "enum": ["In Progress", "Completed", "Failed"], + "enumColors": { + "In Progress": "blue", + "Completed": "green", + "Failed": "red" + } + }, + "asked_at": { + "type": "string", + "title": "Asked At", + "icon": "Calendar", + "description": "When the agent was invoked", + "format": "date-time" + }, + "replied_at": { + "type": "string", + "title": "Replied At", + "icon": "Calendar", + "description": "When the agent replied", + "format": "date-time" + }, + "prompt": { + "type": "string", + "title": "Prompt", + "description": "The prompt sent to the agent, including both the user and the agent prompt", + "format": "markdown" + }, + "error": { + "type": "string", + "description": "Detailed description of an error in case of failed execution", + "title": "Error" + }, + "response": { + "type": "string", + "description": "The final agent response", + "title": "Response", + "format": "markdown" + }, + "execution_logs": { + "type": "string", + "description": "The reasoning and tools execution logs", + "format": "markdown", + "title": "Execution Logs" + }, + "labels": { + "type": "object", + "description": "Free labels to identify specific attributes on the invocation", + "title": "Labels" + }, + "quota": { + "type": "object", + "description": "The quota usage", + "title": "Quota" + }, + "provider": { + "type": "string", + "title": "Provider", + "description": "The LLM provider used for the invocation" + }, + "model": { + "type": "string", + "title": "Model", + "description": "The LLM model used for the invocation" + } + }, + "required": ["asked_at", "status"] + }, + "mirrorProperties": { + "agent_title": { + "title": "agent title", + "path": "agent.$title" + } + }, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "agent": { + "title": "Agent", + "description": "The agent that was invoked", + "target": "_ai_agent", + "required": false, + "many": false + } + }, + "ownership": { + "type": "Inherited", + "title": "Owning Teams", + "path": "agent" + } +} ``` From e922768ae7d627be793e636b1289340a350c9653 Mon Sep 17 00:00:00 2001 From: Matan Grady Date: Sun, 12 Oct 2025 06:06:24 +0300 Subject: [PATCH 8/9] removed token aggregation on agent blueprint --- docs/ai-interfaces/migration_guide.md | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/docs/ai-interfaces/migration_guide.md b/docs/ai-interfaces/migration_guide.md index a4133fc50e..e332daab39 100644 --- a/docs/ai-interfaces/migration_guide.md +++ b/docs/ai-interfaces/migration_guide.md @@ -410,28 +410,6 @@ Starting **October 15th**, schemas will be automatically migrated, but existing "func": "count", "calculationBy": "entities" } - }, - "average_input_tokens": { - "title": "Average input tokens", - "type": "number", - "description": "The average input tokens for this agent invocations", - "target": "_ai_invocations", - "calculationSpec": { - "func": "median", - "property": "prompt_tokens", - "calculationBy": "property" - } - }, - "average_output_tokens": { - "title": "Average output tokens", - "type": "number", - "description": "The average output tokens for this agent invocations", - "target": "_ai_invocations", - "calculationSpec": { - "func": "median", - "property": "completion_tokens", - "calculationBy": "property" - } } }, "relations": {} From adf4fb9a07113806e084e49471423744c8c83444 Mon Sep 17 00:00:00 2001 From: Matan Grady Date: Sun, 12 Oct 2025 14:16:57 +0300 Subject: [PATCH 9/9] update invocation blueprint with asked by --- docs/ai-interfaces/migration_guide.md | 214 ++++++++++++++------------ 1 file changed, 114 insertions(+), 100 deletions(-) diff --git a/docs/ai-interfaces/migration_guide.md b/docs/ai-interfaces/migration_guide.md index e332daab39..0b7af85364 100644 --- a/docs/ai-interfaces/migration_guide.md +++ b/docs/ai-interfaces/migration_guide.md @@ -424,106 +424,120 @@ Starting **October 15th**, schemas will be automatically migrated, but existing ```json { - "identifier": "_ai_invocations", - "description": "For each agent request a match feedback entity will be created", - "title": "AI Invocation", - "icon": "Star", - "schema": { - "properties": { - "status": { - "icon": "DefaultProperty", - "title": "Status", - "type": "string", - "description": "The agent invocation status", - "enum": ["In Progress", "Completed", "Failed"], - "enumColors": { - "In Progress": "blue", - "Completed": "green", - "Failed": "red" - } - }, - "asked_at": { - "type": "string", - "title": "Asked At", - "icon": "Calendar", - "description": "When the agent was invoked", - "format": "date-time" - }, - "replied_at": { - "type": "string", - "title": "Replied At", - "icon": "Calendar", - "description": "When the agent replied", - "format": "date-time" - }, - "prompt": { - "type": "string", - "title": "Prompt", - "description": "The prompt sent to the agent, including both the user and the agent prompt", - "format": "markdown" - }, - "error": { - "type": "string", - "description": "Detailed description of an error in case of failed execution", - "title": "Error" - }, - "response": { - "type": "string", - "description": "The final agent response", - "title": "Response", - "format": "markdown" - }, - "execution_logs": { - "type": "string", - "description": "The reasoning and tools execution logs", - "format": "markdown", - "title": "Execution Logs" - }, - "labels": { - "type": "object", - "description": "Free labels to identify specific attributes on the invocation", - "title": "Labels" - }, - "quota": { - "type": "object", - "description": "The quota usage", - "title": "Quota" - }, - "provider": { - "type": "string", - "title": "Provider", - "description": "The LLM provider used for the invocation" - }, - "model": { - "type": "string", - "title": "Model", - "description": "The LLM model used for the invocation" - } - }, - "required": ["asked_at", "status"] - }, - "mirrorProperties": { - "agent_title": { - "title": "agent title", - "path": "agent.$title" - } - }, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": { - "agent": { - "title": "Agent", - "description": "The agent that was invoked", - "target": "_ai_agent", - "required": false, - "many": false - } - }, - "ownership": { - "type": "Inherited", - "title": "Owning Teams", - "path": "agent" - } + "identifier": "_ai_invocations", + "description": "For each agent request a match feedback entity will be created", + "title": "AI Invocation", + "icon": "Star", + "ownership": { + "type": "Inherited", + "title": "Owning Teams", + "path": "agent" + }, + "schema": { + "properties": { + "status": { + "icon": "DefaultProperty", + "title": "Status", + "type": "string", + "description": "The agent invocation status", + "enum": [ + "In Progress", + "Completed", + "Failed" + ], + "enumColors": { + "In Progress": "blue", + "Completed": "green", + "Failed": "red" + } + }, + "asked_at": { + "type": "string", + "title": "Asked At", + "icon": "Calendar", + "description": "When the agent was invoked", + "format": "date-time" + }, + "replied_at": { + "type": "string", + "title": "Replied At", + "icon": "Calendar", + "description": "When the agent replied", + "format": "date-time" + }, + "prompt": { + "type": "string", + "title": "Prompt", + "description": "The prompt sent to the agent, including both the user and the agent prompt", + "format": "markdown" + }, + "error": { + "type": "string", + "description": "Detailed description of an error in case of failed execution", + "title": "Error" + }, + "response": { + "type": "string", + "description": "The final agent response", + "title": "Response", + "format": "markdown" + }, + "execution_logs": { + "type": "string", + "description": "The reasoning and tools execution logs", + "format": "markdown", + "title": "Execution Logs" + }, + "labels": { + "type": "object", + "description": "Free labels to identify specific attributes on the invocation", + "title": "Labels" + }, + "quota": { + "type": "object", + "description": "The quota usage", + "title": "Quota" + }, + "provider": { + "type": "string", + "title": "Provider", + "description": "The LLM provider used for the invocation" + }, + "model": { + "type": "string", + "title": "Model", + "description": "The LLM model used for the invocation" + } + }, + "required": [ + "asked_at", + "status" + ] + }, + "mirrorProperties": { + "agent_title": { + "title": "agent title", + "path": "agent.$title" + } + }, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "agent": { + "title": "Agent", + "description": "The agent that was invoked", + "target": "_ai_agent", + "required": false, + "many": false + }, + "asked_by": { + "title": "Asked By", + "description": "Who invoked the agent", + "target": "_user", + "required": false, + "many": false + } + } } ```