Agents
An agent in ProvenanceOne is a configured instance of a large language model that runs as a step inside a workflow. It is not a general-purpose AI assistant — it is a specific, named configuration with a provider, a model, a system prompt, a trust level, and a set of tools (skills and MCP servers) it is permitted to call. Every agent belongs to a workspace, has a version, and accumulates performance metrics across its runs.
Agents are probabilistic. The system prompt and tool constraints shape their behavior, but agents can and do produce unexpected outputs. ProvenanceOne workflows add structure around agent steps — approval gates, logic branches, and error handling — to make agent behavior observable and governable.
When to use agents
Use an agent step in a workflow when:
- The task requires reasoning, summarisation, classification, or generation that a deterministic skill cannot handle
- The inputs vary in ways that are hard to enumerate with fixed logic
- You want the step to choose from multiple tools based on the context it receives
Do not use an agent for tasks that have a deterministic correct answer and no need for language understanding. Use a skill or data step instead.
Key concepts
Provider and model — each agent is bound to a specific provider (anthropic, openai, google, or azure-openai) and model (e.g. claude-sonnet-4-6, gpt-4o, gemini-pro). Changing the model creates a new agent version.
Trust level — low, medium, or high. Trust level controls the degree of autonomy the agent is granted within a workflow. low trust agents are more likely to trigger approval steps; high trust agents are permitted to take more actions without a human gate. Trust should be earned through observed performance, not assumed.
System prompt — the instruction set that shapes the agent's behavior. The system prompt preview is shown in the agent list; the full prompt is stored server-side and is not exposed via the API. A well-scoped system prompt reduces the likelihood of the agent producing off-topic or harmful outputs, but it does not guarantee specific behavior.
Category — agents are categorised as reasoning, coding, or analysis. Category is informational and used for filtering in the UI.
Skills and MCP servers — agents can be equipped with skills (sandboxed serverless functions) and MCP servers (external tool providers accessed through the MCP Gateway). The agent decides which tools to call and in what order based on the task context.
Persistent memory — agents have a key-value memory store that persists across runs. Memory can be read, written, and deleted via the API or by skills that the agent calls.
Model integration — the modelIntegrationId field links the agent to a workspace connection that holds the provider API key. The API key itself is stored in the secrets vault and never exposed.
How it works
Agent lifecycle
- Create an agent in Agents → New Agent. Set provider, model, system prompt, trust, and category.
- Attach skills and MCP servers the agent should have access to.
- Reference the agent in a workflow step of kind
agent. - When the workflow run reaches the agent step, ProvenanceOne invokes the agent with the step's input context.
- The agent may make zero or more tool calls before returning a final output.
- The step records the agent's output, all tool calls, and any log messages.
Provider and model configuration
| Provider | Example models |
|---|---|
anthropic | claude-sonnet-4-6, claude-opus-*, claude-haiku-* |
openai | gpt-4o, gpt-4-turbo, gpt-3.5-turbo |
google | gemini-pro, gemini-1.5-flash |
azure-openai | Azure-hosted OpenAI model deployments |
The modelIntegrationId must reference a connection in your workspace that holds valid credentials for the selected provider.
Trust levels
| Level | Behavior |
|---|---|
low | Agent is subject to the most restrictive approval and policy gates. Recommended for new agents and high-risk domains. |
medium | Standard trust. Agent can take common actions without approval but high-risk tool calls may still require a gate. |
high | Agent is permitted broader autonomy. Use only for agents with a well-established track record in the specific workflow context. |
Warning: High trust does not mean the agent is infallible. It means fewer automatic approval gates are inserted. Review
approvalRateandsuccessRatemetrics regularly for high-trust agents.
Persistent memory
Each agent has a key-value memory store scoped to the agent ID. Memory persists across runs.
| Operation | Endpoint |
|---|---|
| Read all keys | GET /agents/{id}/memory |
| Write a key | PUT /agents/{id}/memory/{key} |
| Delete a key | DELETE /agents/{id}/memory/{key} |
Memory is suitable for storing user preferences, prior decisions, or accumulated context that should influence future runs. It is not a substitute for a proper datastore for structured, queryable data.
Attaching skills
Skills appear in the agent's tool list. The agent can call any attached skill during a run. Attach skills on the agent configuration page under Tools → Skills. Each AgentSkillRef records the skill ID and any parameter overrides.
Attaching MCP servers
MCP servers provide additional tools via the Model Context Protocol. Attach MCP servers under Tools → MCP Servers. The agent interacts with MCP servers through the MCP Gateway proxy — it does not connect directly. Each AgentMcpRef records the server ID and the allowed tool subset.
System prompt guidance
Write system prompts that are:
- Scoped — describe the specific task, not a general capability
- Explicit about constraints — state what the agent should not do, not just what it should do
- Clear about output format — specify the expected structure of the agent's response if downstream steps depend on parsing it
The full system prompt is stored server-side. The systemPromptPreview field shown in the agent list is a truncated excerpt for identification purposes.
See /templates/system-prompt-template and /templates/agent-evaluation-rubric for starting points.
Configuration options
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | Internal identifier |
displayName | string | Yes | — | Human-readable name shown in the UI |
description | string | No | — | Short description for the agent list |
longDescription | string | No | — | Full description for the agent detail page |
provider | enum | Yes | — | anthropic | openai | google | azure-openai |
model | string | Yes | — | Model identifier, e.g. claude-sonnet-4-6 |
modelIntegrationId | string | Yes | — | ID of the connection holding provider credentials |
trust | enum | Yes | low | low | medium | high |
category | enum | Yes | — | reasoning | coding | analysis |
status | enum | — | active | active | paused |
owner | string | Yes | — | Owner user email |
team | string | No | — | Team the agent belongs to |
tags | string[] | No | [] | Free-form tags |
environments | string[] | No | all | Environments this agent is available in |
skills | AgentSkillRef[] | No | [] | Skills attached to this agent |
mcpServers | AgentMcpRef[] | No | [] | MCP servers attached to this agent |
Performance metrics (read-only)
| Field | Description |
|---|---|
runs30d | Number of times this agent ran in the last 30 days |
successRate | Percentage of agent step executions that succeeded |
avgLatencyMs | Average time in milliseconds for the agent step to complete |
approvalRate | Percentage of runs where this agent triggered an approval gate |
High approvalRate on a high trust agent may indicate the trust level is correctly set lower than high, or that the system prompt needs refinement.
Examples
Customer support triage agent — category: reasoning, trust: medium. Attached skills: sentiment analysis, CRM lookup. System prompt scoped to classifying ticket urgency and drafting initial responses. Used in a support escalation workflow with an approval gate before response dispatch.
Data transformation agent — category: analysis, trust: low. No attached MCP servers. Skills: CSV parser, schema validator. Used in a scheduled data sync workflow to handle edge cases that the deterministic skill steps cannot handle.
Code review agent — category: coding, trust: medium. Attached MCP server: GitHub MCP. System prompt instructs the agent to review pull requests for security anti-patterns only, not style issues.
Common mistakes
- Setting trust to
highimmediately. Start atlowormediumand reviewapprovalRateandsuccessRateover a meaningful number of runs before increasing trust. - Writing system prompts that are too broad. "You are a helpful assistant" gives the agent no constraints. A scoped prompt like "You classify inbound support tickets into one of five severity levels based on the criteria below" produces more consistent results.
- Attaching all available skills to every agent. Give agents only the tools they need for their specific task. Unnecessary tools increase the surface area for unexpected behavior.
- Storing sensitive data in agent memory. Memory values are readable by any
editororadminvia the API. Do not store credentials, PII, or other sensitive data as memory keys.
Troubleshooting
Agent step failing with a provider authentication error — verify that the modelIntegrationId references a valid, active connection and that the underlying API key has not been rotated or revoked.
Agent step producing inconsistent outputs — review the system prompt for ambiguous instructions. Check whether the model version has changed. Consider adding output format constraints to the prompt or adding a validation step downstream.
Agent step never completing — check the step logs for context length errors or rate limit messages. Very long input contexts can cause some models to time out.
Paused agent — an agent with status: paused cannot be used in new workflow runs. Reactivate the agent from the Agents page before triggering runs.
Security and permissions
editorandadmincan create, edit, and delete agents.viewercan view agent configuration and metrics but cannot modify anything.- The API key for the model provider is stored in the secrets vault. The
APIKeySecretNamefield references the secret name; the secret value is never returned by any API response. - Audit events
agent.updated,agent.memory_set,agent.memory_deleted,agent.listed, andagent.readare emitted for agent operations.
Related pages
FAQ
What models are supported?▾
ProvenanceOne supports models from Anthropic (e.g. claude-sonnet-4-6), OpenAI (e.g. gpt-4o), Google (e.g. gemini-pro), and Azure OpenAI. The full list of available models depends on the provider connection configured in your workspace.
What is trust level?▾
Trust level (low, medium, or high) controls how much autonomy the agent is granted within a workflow. Low trust agents trigger more approval gates; high trust agents are permitted to take more actions without human review. Trust should reflect observed, validated performance — not assumed capability.
Does agent memory persist between runs?▾
Yes. Agent memory is a key-value store scoped to the agent ID. Values written in one run are available in subsequent runs. Memory persists until explicitly deleted via DELETE /agents/{id}/memory/{key} or overwritten via PUT.
Can agents talk to each other?▾
Not directly. Agents communicate through the workflow DAG: one agent step produces an output, and a downstream agent step receives that output as input. There is no direct agent-to-agent messaging channel. If you need one agent's output to influence another, connect them with edges in the workflow editor and map the outputs to inputs.
How do I test an agent before using it in a production workflow?▾
Use POST /agents/{id}/test-tool to invoke the agent's tool-calling capability directly. For end-to-end testing, build a workflow in the development environment, run it manually with test payloads, and review the run debugger output before deploying to production.