Agents

Subscribed agents

Subscribed agents are AI agents that are provided by installed applications in your Cumulocity tenant. These agents are automatically available in the AI Agent Manager once the providing application or plugin is deployed.

What are subscribed agents?

When developers build applications or plugins that include AI functionality, they define agents to be exported. These agents are then “subscribed” to your tenant and appear in the AI Agent Manager list.

Subscribed agents come with predefined:

• System prompts that define their behavior and expertise.
• Tool configurations that allow them to interact with specific Cumulocity data or services.

Subscribed agents properties:

• Pre-configured: Subscribed agents are fully configured by the application provider. You do not need to define system prompts or tools.

• Application-specific: Each subscribed agent is designed for a specific use case within an application (for example, a device troubleshooting agent for a specific device management app).

• Require global provider: Subscribed agents use your configured global provider unless they specify a local provider. Without a global provider configured, subscribed agents remain inactive.

• Read-only configuration: You cannot modify the system prompt or tools of subscribed agents. However, you view their configuration to understand their capabilities. You also overwrite the subscribed agent with a custom agent. Custom agents with the same name as the subscribed one are preferred.

• Automatic updates: When the providing application updates the agent definition, changes appear automatically in your AI Agent Manager as long as you haven’t overwritten it.

Viewing subscribed agents

To view subscribed agents:

1. Navigate to Administration > AI Agent Manager.
2. In the agents list, subscribed agents display with a badge indicating their source application.
3. Click on a subscribed agent to view its details, including the system prompt and available tools.

Testing subscribed agents

You test subscribed agents the same way as custom agents:

1. Open the subscribed agent in the AI Agent Manager.
2. Navigate to the Test tab.
3. Enter a prompt and observe the agent’s response.

Overruling subscribed agents

While you cannot change the core configuration of subscribed agents, you align them by overruling the agent. Click the three dots next to the subscribed agent and select Clone agent. The cloned agent then aligns to your needs, and all subscribed agents by any app only use this new custom agent.

Subscribed agent versioning

While agents in general are not versioned, subscribed agents are versioned. They are provided by a custom or subscribed plugin that gets versioned, so the agents also exist in different versions. The AI Agent Manager shows the “latest” version of the plugin-agent. However, a custom application might use a different version. If the agent is overruled, always the custom user-defined agent is used.

Removing subscribed agents

Subscribed agents are removed automatically when you uninstall or remove the providing application. You cannot manually delete subscribed agents while their source application remains installed. If the source application is subscribed, you need to unsubscribe this application to uninstall the agent.

Text and object agents

The AI Agent Manager supports two base types of agents: text agents and object agents. Understanding the difference helps you choose the right type for your use case.

Text agents

Text agents return natural language responses as plain text. They are designed for conversational interactions where the agent provides explanations, answers, or guidance in a human-readable format.

Use cases:

• Conversational interfaces where users ask questions in natural language.
• Explanations and guidance for device troubleshooting.
• General-purpose AI assistants that interact through chat.
• Generating reports or summaries in text format.

Response format:

By default, text agents return plain text:

The current temperature is 23.5°C and the humidity level is at 45%.

Add the ?fullResponse=true query parameter to receive a JSON response with additional metadata, including tool calls, reasoning steps, and usage statistics.

API endpoint:

POST /service/ai/agent/text/{agent-name}

Object agents

Object agents return structured data in JSON format according to a predefined schema. They are designed for programmatic integrations where the response must follow a specific structure.

Use cases:

• APIs that require structured responses.
• Data extraction where specific fields must be populated.
• Integration with other systems that expect JSON.
• Form filling or data validation workflows.

Response format:

Object agents always return JSON that matches the defined schema:

{
  "temperature": 23.5,
  "humidity": 45,
  "status": "normal"
}

Schema definition:

When creating an object agent, define the expected response structure using JSON schema:

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "Current temperature in Celsius"
    },
    "humidity": {
      "type": "number",
      "description": "Current humidity percentage"
    },
    "status": {
      "type": "string",
      "enum": ["normal", "warning", "critical"]
    }
  },
  "required": ["temperature", "humidity", "status"]
}

The agent uses this schema to structure its response, ensuring consistent output format.

API endpoint:

POST /service/ai/agent/object/{agent-name}

UI support:

When creating an object agent a new Schema tab is shown. In this view you can define the correct schema and a validation will check, if you are following the right JSON Schema standard.

Key differences

Choosing the right type

Choose text agents when:

• Building conversational interfaces or chatbots.
• Users need natural language explanations.
• Response format varies based on context.
• You want to use custom tools for data access.

Choose object agents when:

• Integrating with APIs or other systems.
• Response must follow a strict structure.
• Extracting specific data fields from user input.
• Building forms or structured data collection.

Testing agent types

You test both agent types in the AI Agent Manager:

1. Navigate to Administration > AI Agent Manager.
2. Create or open an agent.
3. The agent type is selected during creation and cannot be changed later.
4. For object agents, define the JSON schema in the configuration.
5. Use the Test tab to verify responses match your expectations.

Converting between types

You cannot convert an existing agent from one type to another. To change the agent type, create a new agent with the desired type and copy the relevant configuration.

Local providers

Local providers allow you to configure agent-specific AI provider and model settings that override the global provider configuration. This enables you to use different AI models or providers for different agents based on their specific requirements.

What are local providers?

A local provider is an agent-specific configuration that defines:

• Which AI provider to use (for example, OpenAI, Anthropic, Google).
• Which model to use (for example, gpt-4, claude-3-7-sonnet).
• Provider-specific settings like API keys, base URLs, or custom parameters.

When an agent has a local provider configured, it uses those settings instead of the global provider settings.

When to use local providers

Consider the following:

• Different model requirements: Some use cases benefit from specific models. For example, use a faster, cheaper model for simple queries and a more powerful model for complex reasoning tasks.

• Cost optimization: Route less critical agents to more cost-effective models while keeping important agents on premium models.

• Provider-specific features: Access features only available from certain providers, such as extended thinking modes or specialized capabilities.

• Testing and comparison: Test different models side-by-side by creating multiple agents with different local providers.

• Separate billing: Use different API keys for different agents to track usage or allocate costs to different departments.

Global provider versus local provider

Configuring a local provider

To configure a local provider for an agent:

1. Navigate to Administration > AI Agent Manager.
2. Open the agent you want to configure or create a new agent.
3. In the agent configuration, expand the Local provider tab.

In this view you can configure your local provider (only with JSON). Therefore (depending on the provider to use) you can define a new provider, model or apiKey. This settings are always merged with the “global provider” and therefore allow to e.g. only overwrite the model to be used.

For example to use an Open AI API like LLM hosted for example on an own infrastructure, the following configuration could be used:

{
  "provider": "openai",
  "model": "my-custom-gpt",
  "baseURL": "https://your-custom-endpoint.com/v1",
  "strictMode": false
}

Testing local providers

After configuring a local provider:

1. Navigate to the Test tab of the agent.
2. Enter a test prompt.
3. Verify the response uses the local provider.

Managing multiple local providers

You configure local providers independently for each agent. This allows you to:

• Use OpenAI for agent A, Anthropic for agent B, and Google for agent C.
• Test the same agent configuration with different models by creating duplicate agents with different local providers.
• Maintain separate API keys for different use cases or cost centers.

Security considerations

• API keys: Local provider API keys are stored securely in Cumulocity and cannot be read after configuration. Only users with appropriate permissions access local provider settings.

• Access control: Ensure only authorized users have permission to configure agents and local providers, as this grants access to external AI services.

Removing a local provider

To remove a local provider and revert to the global provider simply empty the JSON object.

Troubleshooting local providers

• Agent not responding: Verify the API key is valid and the provider account has sufficient credits.

• Different results than expected: Check the model selection and advanced settings in the local provider configuration.

• Provider not available: Ensure the provider is supported by the AI Agent Manager. For the current list of supported providers, refer to the Vercel AI SDK documentation.