Interact with AI agents

Closed Beta

Port's AI offerings are currently in closed beta and will be gradually rolled out to users by the end of 2025.

Built on Port AI

AI Agents are specialized implementations built on top of Port AI, designed for machine-to-machine communication and autonomous operations within defined domains.

Getting started

Once you've built your AI agents, you can integrate them into your workflows and systems. AI agents are designed for machine-to-machine communication and can be triggered programmatically through Port's API or automatically through workflow automations.

How AI Agents Work

AI Agents are domain-specific entities built on Port AI with configured tools and prompts. For details on agent architecture and configuration, see AI agents overview and Build an AI agent.

Interaction approaches

AI agents are designed for specific domains and use cases. When interacting with agents, you target the specific agent that has the expertise and tools needed for your task. This approach works best for structured scenarios like automation triggers and API integrations where you know which domain-specific capabilities you need.

Interaction methods

API integration

AI agents can be integrated into your applications and workflows through Port's API. Agents use the same streaming API patterns as Port AI.

Agent-specific endpoint:

curl 'https://api.port.io/v1/agent/<AGENT_IDENTIFIER>/invoke?stream=true' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"prompt":"Analyze the health of our production services"}'

For comprehensive details on API interaction, streaming responses, event types, quota management, and integration patterns, see Port AI API Interaction.

Actions and automations

You can trigger AI agents through Port's actions and automations, enabling integration of AI capabilities into your existing workflows. This is the primary method for creating autonomous, machine-to-machine AI systems.

Automation Workflows

Automations allow you to automatically trigger AI agents based on events in your Port catalog. This enables reactive AI systems that respond to changes in your infrastructure or applications.

Example: Automatic Incident Response (Click to expand)

When a new incident is created, automatically trigger an agent that:

• Analyzes the incident context
• Gathers relevant information from related services
• Creates initial response documentation
• Notifies appropriate teams

{
  "identifier": "incident_response_automation",
  "title": "Automatic Incident Response",
  "trigger": {
    "type": "automation",
    "event": {
      "type": "ENTITY_CREATED",
      "blueprintIdentifier": "incident"
    }
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://api.getport.io/v1/agent/incident_response_agent/invoke",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "prompt": "New incident created: {{ .entity.title }}. Severity: {{ .entity.properties.severity }}. Please analyze and provide initial response recommendations.",
      "labels": {
        "source": "automation",
        "incident_id": "{{ .entity.identifier }}",
        "trigger_type": "incident_created"
      }
    }
  }
}

Example: Infrastructure Healing (Click to expand)

Monitor infrastructure health and automatically trigger healing agents when issues are detected:

{
  "identifier": "k8s_healing_automation",
  "title": "Kubernetes Workload Healing",
  "trigger": {
    "type": "automation",
    "event": {
      "type": "ENTITY_UPDATED",
      "blueprintIdentifier": "k8s_workload"
    },
    "condition": {
      "type": "JQ",
      "expressions": [
        ".diff.before.properties.isHealthy == \"Healthy\"",
        ".diff.after.properties.isHealthy == \"Unhealthy\""
      ],
      "combinator": "and"
    }
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://api.getport.io/v1/agent/k8s_healing_agent/invoke",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "prompt": "Workload {{ .event.diff.after.title }} is unhealthy. Current state: {{ .event.diff.after.properties.replicas }} replicas, {{ .event.diff.after.properties.readyReplicas }} ready. Please analyze and fix.",
      "labels": {
        "source": "automation",
        "workload_name": "{{ .event.diff.after.identifier }}",
        "namespace": "{{ .event.diff.after.properties.namespace }}"
      }
    }
  }
}

Self-Service Actions

You can create self-service actions that invoke AI agents, allowing users to trigger intelligent workflows on-demand.

Example: Service Analysis Action (Click to expand)

{
  "identifier": "analyze_service_health",
  "title": "Analyze Service Health",
  "description": "Get AI-powered analysis of service health and recommendations",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "blueprintIdentifier": "service"
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://api.getport.io/v1/agent/service_health_agent/invoke",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "prompt": "Analyze the health of service {{ .entity.title }}. Check metrics, recent deployments, and incidents.",
      "labels": {
        "source": "self_service",
        "service_name": "{{ .entity.identifier }}",
        "requested_by": "{{ .trigger.by.user.email }}"
      }
    }
  }
}

For comprehensive examples, see our AI guides.

Discovering Available Agents

You can discover available AI agents through the AI Agents catalog page or programmatically via the API using the _ai_agent blueprint.

cURL Example

curl -L 'https://api.port.io/v1/blueprints/_ai_agent/entities' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer <YOUR_API_TOKEN>'

AI interaction details

Every AI agent interaction creates an entity in Port, providing tracking and analysis capabilities. For comprehensive details on AI invocations, execution plans, and tools used, see Port AI Overview.

Data & security considerations

For information on data handling and security, see AI Security and Data Controls.

Limits

AI agents use the same rate limits and quotas as Port AI.

Note: These limits apply when using Port's managed AI infrastructure. Bring your own LLM provider to use your provider's limits instead.

For detailed information on limits, monitoring, and quota management, see Port AI API Interaction.

Troubleshooting & FAQ

How can I integrate agents into my workflows? (Click to expand)

AI agents are designed for machine-to-machine communication and can be integrated through:

• API integration: Direct HTTP calls to agent endpoints
• Workflow automations: Automatic triggering based on Port catalog events
• Self-service actions: User-initiated agent workflows

For examples, see our automation guides.

What happens if an agent can't answer my question? (Click to expand)

If the agent doesn't have the knowledge or capabilities to answer your question, you'll receive a response mentioning that it can't assist you with your specific query. Consider using a different agent that's specialized for your domain or task.

How do I improve agent performance? (Click to expand)

For comprehensive guidance on improving AI performance, debugging issues, and analyzing invocation details, see Port AI Overview. The troubleshooting approaches for Port AI apply to AI agents as well.

For agent-specific improvements, see Build an AI agent for prompt engineering and tool configuration guidance.