Agents - Apigene

Overview

Agents are specialized AI assistants that can be configured with specific instructions, tools, and behaviors. They enable you to create focused, reusable AI workflows tailored to particular tasks or domains.

Agents list with Create Agent card and MCP URLs

Open an agent to edit instructions, applications, skills, context, generative UI, workflows, and setup:

Agent detail page showing Instructions tab for CI Bottleneck Analyzer

What Are Agents?

Think of agents as expert assistants with:

Custom instructions: Define how the agent should behave and respond
Specific tools: Select which applications and APIs the agent can access
Consistent behavior: Agents follow the same instructions every time
Shareable knowledge: Make agents available across your organization

Key Features

Custom Instructions

Define exactly how your agent should operate:

Personality and tone
Domain expertise
Response format
Decision-making guidelines

Tool Selection

Control which capabilities your agent has:

Select specific applications
Choose individual API operations
Configure MCP servers access
Set tool usage policies

Visibility Control

Manage who can use your agents:

Private: Only visible to you
Public: Available to your entire organization
Easy visibility toggle

Version Control

Edit in draft, then publish when chat and MCP should pick up the change:

Save writes the draft only — live stays on the last published version
Publish (Versions tab) creates a numbered version and points live at it
Compare, restore a snapshot into draft, or switch live to an earlier version without changing the MCP URL

Creating an Agent

You can create agents in two ways:

Agent Builder (recommended) — conversational workflow in Copilot that discovers apps, drafts instructions, proposes skills, validates, and creates the agent
Agents page — manual form at Agents → + New Agent

For most users, start in Agent Builder and refine in the editor afterward.

Step 1: Navigate to Agents

Switch the sidebar to Design and open Build → Agents
Click the + New Agent card
You’ll see the agent creation form

Step 2: Configure Basic Information

Agent Name

Use lowercase kebab-case: letters, numbers, and hyphens only (for example github-bot, support-agent)
Spaces and underscores are converted to hyphens as you type
Maximum 64 characters; keep it short so MCP URLs stay readable

Display Name (Optional)

Friendly label shown in chat, agent cards, and pickers (up to 64 characters)
Leave empty to show the kebab-case name
MCP URLs and @ mentions still use the agent name

Agent Description (Optional)

Explain the agent’s purpose
Describe what it’s good at
Helps team members understand when to use it

Step 3: Write Instructions

This is where you define your agent’s behavior. Good instructions include: Role Definition

You are an expert GitHub repository manager who helps developers with code reviews and issue management.

Capabilities

You can:
- Create and update GitHub issues
- Review pull requests
- Search code repositories
- Manage project boards

Guidelines

When responding:
- Be concise and technical
- Always include relevant GitHub links
- Use markdown formatting
- Provide code examples when helpful

Example Complete Instructions

You are a customer support agent specializing in technical troubleshooting.

Your role is to:
1. Understand customer issues clearly
2. Search the knowledge base for solutions
3. Create support tickets for unresolved issues
4. Follow up with customers promptly

Guidelines:
- Always be polite and empathetic
- Ask clarifying questions when needed
- Provide step-by-step solutions
- Escalate complex issues to human agents
- Use bullet points for clarity

When creating tickets:
- Include all relevant customer information
- Tag with appropriate priority level
- Add reproduction steps if provided

Step 4: Select Tools

Choose which applications and tools your agent can access: Applications (APIs)

Attach OpenAPI integrations installed in your workspace
Each application exposes actions the agent can call

MCP Servers

Attach native MCP servers (not OpenAPI→MCP bridges — use Applications for those)
Configure per-agent in the applications / MCP attachments area
Install servers first from the MCP dashboard, official catalog, or registry

Per-tool toggles (Setup tab)

Enable or disable individual MCP gateway tools for this agent (e.g. list_skills, run_action, get_context)
Disabled tools are hidden from the agent at runtime
Useful for least-privilege agents that should only call specific operations

Default Toolkit

Enable to give access to all configured applications
Good for general-purpose agents
Simpler to manage

Custom Tool Selection

Select specific applications only
More precise control
Better for specialized agents

Step 5: Set Visibility

Private Agent

Only you can see and use it
Perfect for personal workflows
Test agents before sharing

Public Agent

Available to your entire organization
Appears in everyone’s agent list
Great for team collaboration

Step 6: Save and Test

Click Save to create your agent
Test it immediately in a new chat
Mention the agent using @support-agent (kebab-case name)
Refine instructions based on results

Agent Editor Tabs

After creating an agent, the editor is organized into tabs:

Tab	Purpose
Instructions	Name, optional display name, description, icon, and system prompt
Applications	OpenAPI integrations attached to the agent
MCP Servers	Native MCP server attachments
Skills	Org skills from your Skills library
Context	Reusable context items
Generative UI	Visual templates for MCP App results (available after first save)
Workflows	List, create, visually edit, run, and simulate agent workflows
Versions	Draft vs live, publish, compare, and version history (available after first save)
Setup	Live and design MCP URLs, per-tool toggles, managed setup export

Skills

Attach Skills on the Skills tab to give the agent reusable workflows and domain procedures. At runtime the agent discovers skills via list_skills and loads full instructions with get_skill_content before applying them. You can also attach skills during Agent Builder creation via the skill proposals card.

Generative UI Templates

The Generative UI tab (visible after the agent is saved) lets you define visual templates for MCP App results — charts, tables, and custom layouts rendered in supported MCP hosts.

Start from starter layouts or write a JSON / json-render style spec
Preview with sample state before saving
Keep dynamic values in template state so runtime data can merge
Templates pair with run_action_ui, run_multi_actions_ui, and generative UI tools in MCP Gateway

For org-wide template libraries, GitHub sync, and clone/create flows, see MCP Apps. See MCP Gateway Tools for UI execution tools.

Managed Agent Setup Export

On the Setup tab, expand Managed agent setup (YAML / JSON) to export a configuration document for external managed-agent platforms. The export includes:

Agent name and system instructions (with skills workflow hints)
MCP server URLs (agent gateway URL plus attached MCP servers)
Tool set definitions

Copy as YAML or JSON for use in compatible deployment workflows.

MCP connection URLs

On the Setup tab, copy the URL that matches how the client should use the agent:

URL	What it uses
`/agent/{name}/mcp`	Published live version (chat, Cursor, Claude, and other runtime clients)
`/agent/{name}/design/mcp`	Unpublished draft — create or delete skills, workflows, and templates until you publish

Example design URL:

https://app.apigene.ai/agent/{name}/design/mcp

Viewers of a shared agent can connect to the live URL. Design and mutation tools are hidden unless you own the agent.

Draft, live, and version history

After the first save, the editor and agent cards show:

A vN chip for the current live version
A Draft chip when unpublished changes exist

Save updates draft only. Chat, Tasks, and /agent/{name}/mcp keep using live until you publish.

Publish

Open the agent → Versions
Review the draft vs live summary (instructions, apps, MCP servers, skills, context, workflows, UI templates, tools)
Click Publish, optionally add a note, and confirm

Publish creates the next numbered version and points live at it. The public MCP URL does not change.

History

The Versions table lists each published snapshot. Open a row for details, or use the row menu to:

Compare with live — side-by-side diff of instructions and attachments
Restore into draft — copy that version into draft (overwrites unpublished edits)
Switch live here — point live at an earlier version without rewriting draft

New agents start version history on the first save (v1). Existing agents keep working as live; further saves stay in draft until you publish.

Using Agents

In Copilot

Invoke agents in your conversations: Direct Mention

@github-bot please create an issue for the login bug

Implicit Usage The agent’s instructions guide the conversation context and behavior. Pickers and agent cards show the optional display name. @ mentions still use the kebab-case name.

Agent Context

When you use an agent:

Its instructions are added to the conversation
Only specified tools are available
The agent’s personality shapes responses
All mentions from instructions are inherited

Managing Agents

Viewing Agents

The Agents page lists every agent you can see (no 50-item cap). Cards show the display name when set, live version, and a Draft chip when unpublished changes exist. My Agents

Agents you created
Private agents
Full control to edit, publish, or delete

Shared Agents

Public agents from your organization
Created by team members
View-only access (live version only)

Agent Marketplace

When an admin enables Agent Marketplace, the Agents page shows a catalog from a private GitHub repo (Claude plugin layout). Browse by industry or line of business, preview a listing, and install it as an agent in your organization. Try Now installs (or reuses) the plugin agent, can prepare recommended demo applications so the agent has APIs to call, connects the agent to Copilot, and opens a Live chat with the agent mentioned. The first run for a line of business may take a minute and shows a progress sheet; later runs reuse what is already in place. Click the spinning Try Now button to reopen progress. How it works previews the plugin without installing. Add to my agents installs without opening chat. If demo applications are not available in your deployment, Try Now still installs the agent as before.

Editing Agents

Find your agent in “My Agents”
Click the Edit icon
Modify instructions, tools, or settings
Click Save to update the draft
Open Versions and Publish when new chats and MCP should use the change

Until you publish, existing conversations and the runtime MCP URL keep the last live version.

Deleting Agents

Find your agent in “My Agents”
Click the Delete icon
Confirm the deletion
The agent is permanently removed

Note: Existing conversations using the agent will continue to work.

Changing Visibility

Toggle between private and public:

Find your agent in the list
Click the visibility icon
Confirm the change
The agent moves to the appropriate section

Agent Best Practices

Writing Effective Instructions

Be Specific

❌ “Help users with GitHub”
✅ “You are a GitHub automation assistant that creates issues, manages pull requests, and updates project boards based on user requests”

Define Boundaries

You can:
- Create and update issues
- Comment on pull requests
- Search repositories

You cannot:
- Delete repositories
- Modify security settings
- Access private repositories without permission

Include Examples

Example interaction:
User: "Create an issue for the login bug"
You: "I'll create a GitHub issue. What should the title be?"
User: "Login fails with special characters"
You: *creates issue with title, asks for description*

Tool Selection Strategy

Specialized Agents

Select only necessary applications
Reduces confusion and errors
Improves response accuracy
Example: GitHub-only agent for code management

General Purpose Agents

Use default toolkit
Enable multiple applications
Good for exploratory workflows
Example: Research assistant with web search, docs, and email

Naming Conventions

Use clear, descriptive names:

Good: “Jira Issue Creator”, “Slack Notifier”, “Data Export Assistant”
Avoid: “Agent1”, “My Agent”, “Test”

Include the domain or platform in the name when relevant.

Common Agent Types

Support Agent

You are a customer support specialist.

Responsibilities:
- Answer customer questions
- Search documentation
- Create support tickets
- Track issue resolution

Always:
- Be empathetic and professional
- Verify information before responding
- Follow up on open issues
- Provide ticket numbers for tracking

Development Assistant

You are a development workflow assistant.

You help developers by:
- Creating and updating Jira issues
- Managing GitHub pull requests
- Running CI/CD workflows
- Notifying teams in Slack

Technical Guidelines:
- Use proper technical terminology
- Include relevant links and references
- Format code snippets properly
- Verify changes before executing

Data Analyst

You are a data analysis assistant.

Your capabilities:
- Query databases
- Generate reports
- Create visualizations
- Export data to various formats

Analysis approach:
- Clarify requirements first
- Validate data quality
- Explain your methodology
- Provide actionable insights

Marketing Assistant

You are a marketing automation assistant.

You help with:
- Email campaign management
- Social media posting
- Analytics reporting
- Content scheduling

Brand Guidelines:
- Maintain consistent tone
- Follow brand voice guidelines
- Check content before publishing
- Track campaign performance

Advanced Features

Agent Mentions

Agents can include mentions in their instructions: Context Mentions

When responding, always reference @company-policies for guidelines.

Agent Chaining

For complex issues, consult @expert-agent for additional insights.

Thread References

Refer to @project-thread for project context.

Multi-Application Workflows

Create agents that orchestrate multiple services:

You are a deployment coordinator.

Deployment workflow:
1. Check CI status in GitHub
2. Create deployment record in Jira
3. Notify team in Slack
4. Monitor logs in Datadog
5. Update status in project board

At each step:
- Verify success before proceeding
- Report status to the user
- Handle errors gracefully
- Provide rollback guidance if needed

Conditional Behavior

Include decision logic in instructions:

Issue Triage Agent:

When a new issue is reported:

IF severity is HIGH:
  - Create P0 ticket in Jira
  - Notify on-call engineer in Slack
  - Set status to "Urgent"

IF severity is MEDIUM:
  - Create P1 ticket in Jira
  - Add to sprint backlog
  - Assign to team lead

IF severity is LOW:
  - Create P2 ticket in Jira
  - Add to general backlog
  - No immediate notification

Searching Agents

Use the search bar to quickly find agents:

Search by agent name
Filter through descriptions
Works on both “My Agents” and “Shared Agents”
Updates results in real-time

Troubleshooting

Agent Not Responding as Expected

Check Instructions

Review for clarity and specificity
Ensure guidelines are unambiguous
Add examples if behavior is unclear

Verify Tool Access

Confirm necessary applications are selected
Check application credentials
Test tools individually

Review Conversation Context

Agent instructions may conflict with user requests
Check for contradictory mentions
Verify all prerequisites are met

Agent Can’t Access Tools

Application Not Selected

Edit agent configuration
Add required applications
Save changes

Missing Credentials

Check Settings > Applications
Verify API keys and tokens
Reconfigure authentication

Permissions Issue

Verify MCP server access
Check organization permissions
Confirm application is properly installed

Shared Agent Not Visible

Visibility Setting

Ensure agent is set to “Public”
Check with agent creator
Verify organization membership

Next Steps

Agent Builder — create agents conversationally
Workflows — multi-step graphs on an agent (run, simulate, approve)
Tasks — scheduled and on-demand saved prompts
Use agents in Copilot for specialized tasks
Skills — org skill library and registry
Configure applications to enable more agent capabilities
Add context items for agents to reference
MCP Gateway — connect agents to external clients
View agent usage in analytics

​Overview

​What Are Agents?

​Key Features

​Custom Instructions

​Tool Selection

​Visibility Control

​Version Control

​Creating an Agent

​Step 1: Navigate to Agents

​Step 2: Configure Basic Information

​Step 3: Write Instructions

​Step 4: Select Tools

​Step 5: Set Visibility

​Step 6: Save and Test

​Agent Editor Tabs

​Skills

​Generative UI Templates

​Managed Agent Setup Export

​MCP connection URLs

​Draft, live, and version history

​Publish

​History

​Using Agents

​In Copilot

​Agent Context

​Managing Agents

​Viewing Agents

​Agent Marketplace

​Editing Agents

​Deleting Agents

​Changing Visibility

​Agent Best Practices

​Writing Effective Instructions

​Tool Selection Strategy

​Naming Conventions

​Common Agent Types

​Support Agent

​Development Assistant

​Data Analyst

​Marketing Assistant

​Advanced Features

​Agent Mentions

​Multi-Application Workflows

​Conditional Behavior

​Searching Agents

​Troubleshooting

​Agent Not Responding as Expected

​Agent Can’t Access Tools

​Shared Agent Not Visible

​Next Steps