Agent Configuration

What Is an Agent Profile?

An agent profile is the central configuration object for an OmniLink agent. It defines who the agent is, what it can do, and how it should behave. When you send a chat request or start a ToolRunner session, the platform loads the matching profile and uses its settings to compose the system instructions sent to the underlying AI engine.

Profiles are stored server-side and keyed to your Omni Key. Each profile has a unique name that you reference in API calls, client methods, and ToolRunner subclasses.

Think of a profile as the agent’s blueprint. Changing the profile changes the agent’s behavior instantly — no code redeployment required.

Creating a Profile via Python

The OmniLinkClient class provides methods for full CRUD operations on agent profiles. Here is how to create a new profile programmatically:

from omnilink.client import OmniLinkClient

client = OmniLinkClient(omni_key="omk_your_key")

profile = client.create_profile("my-agent", settings={
    "agentName": "my-agent",
    "availableCommands": "search, summarize, translate",
    "mainTask": "You are a research assistant. When the user asks a question, "
                "search for relevant information, summarize the findings, and "
                "offer to translate the summary into other languages.",
    "agentPersona": "professional and thorough",
})

The create_profile method sends a POST request to the /api/agent-profiles endpoint and returns the created profile object, including its server-assigned ID.

Minimal Profile

At minimum, a profile needs a name and a main task. All other fields are optional and will use sensible defaults:

profile = client.create_profile("simple-bot", settings={
    "agentName": "simple-bot",
    "mainTask": "You are a helpful assistant that answers questions concisely.",
})

Configuration Fields Reference

The following table lists every field available in an agent profile’s settings object. All fields are optional except agentName.

System Instructions

The mainTask field is the cornerstone of agent behavior. It is injected into the system prompt sent to the AI engine on every request. Writing effective system instructions is the single most impactful thing you can do to improve agent performance.

How mainTask Shapes Behavior

When a chat request arrives, the platform composes a full system prompt by combining several sources: the mainTask, the agent persona, available commands, knowledge snippets (if any), and memory context. The mainTask always appears first and carries the most weight.

Writing Effective Instructions

Follow these guidelines for best results:

• Be specific. Instead of “help the user,” write “You are a customer support agent for Acme Corp. Answer questions about return policies, order tracking, and product specifications.”
• Define boundaries. State what the agent should not do: “Never provide medical advice. If asked a health question, refer the user to a healthcare professional.”
• Specify output format. If you expect structured output, say so: “Always respond with a JSON object containing action and parameters fields.”
• Include examples. Provide one or two example interactions to anchor the model’s behavior.
• Keep it focused. A concise, well-structured instruction outperforms a sprawling wall of text. Aim for clarity over length.

Example: Robotics Agent

settings = {
    "agentName": "warehouse-bot",
    "mainTask": (
        "You are the control intelligence for a warehouse robot. "
        "Your job is to navigate the warehouse, pick items from shelves, "
        "and deliver them to the packing station.\n\n"
        "Available commands:\n"
        "- move_to [location:zone]\n"
        "- pick_item [item:sku]\n"
        "- place_item\n"
        "- report_status\n\n"
        "Always confirm the current zone before moving. "
        "If an item is not found at the expected location, report it and "
        "request manual intervention."
    ),
    "availableCommands": "move_to, pick_item, place_item, report_status",
    "agentPersona": "efficient and precise",
}

Command Configuration

The availableCommands field tells the AI engine which commands the agent can produce. This is critical for ToolRunner and command-engine workflows where the AI output must match a predefined set of templates.

When you set availableCommands, the platform injects a constraint into the system prompt that instructs the AI to limit its responses to the listed commands. This dramatically reduces hallucinated or invalid commands.

# For a smart home agent
settings = {
    "agentName": "home-controller",
    "availableCommands": (
        "turn_on_[device:device], turn_off_[device:device], "
        "set_temperature_[temp:temperature], lock_[door:door], "
        "unlock_[door:door], get_status"
    ),
    "mainTask": "You control a smart home. Issue commands to manage devices.",
}

The AI will now only output commands from this set. If the user asks for something outside the command vocabulary, the agent will explain the limitation instead of producing an invalid command.

Dashboard Configuration

The Dashboard provides a visual interface for all profile settings. Here is a step-by-step guide to configuring an agent through the browser:

1. Navigate to Configuration. Log in to the Dashboard and select the Configuration page from the sidebar.
2. Select or create a profile. Use the profile selector at the top of the page. Click New Profile to create a fresh one, or select an existing profile to edit it.
3. Set the agent name. Enter a unique name in the Agent Name field. This is the identifier you will reference in code.
4. Write system instructions. Fill in the Main Task textarea with your system prompt. Use the guidelines from the previous section.
5. Define the persona. Enter a personality description in the Agent Persona field.
6. List available commands. Enter a comma-separated list in the Available Commands field. Include template syntax if you use the command engine.
7. Toggle capabilities. Use the checkboxes to enable or disable Allow Code Output and Allow Tool Use.
8. Save. Click the save button. Changes take effect immediately on the next API call.

Profile Management

Beyond creation, the Python client supports listing, updating, and managing profiles:

List All Profiles

profiles = client.list_profiles()
for p in profiles:
    print(f"{p['agentName']} — {p['id']}")

Update a Profile

client.update_profile(
    profile_id="prof_abc123",
    name="my-agent",
    settings={
        "agentName": "my-agent",
        "mainTask": "Updated system instructions here.",
        "agentPersona": "concise and helpful",
        "allowCodeOutput": True,
    },
)

The update_profile method sends a PUT request with the new settings. Only the fields you include will be updated; omitted fields retain their current values.

Switching Profiles at Runtime

You can reference different profiles in different API calls. This lets you run multiple agents from the same codebase:

# Use one profile for research tasks
response = client.chat("Find papers on transformer architectures", agent_name="researcher")

# Use another profile for customer support
response = client.chat("What is your return policy?", agent_name="support-agent")

Free-Tier Limits

Accounts on the free tier (Bronze plan) are limited to 1 agent profile. If you need multiple profiles, upgrade to Silver or higher. Paid plans support unlimited profiles, allowing you to create specialized agents for every use case.

Best Practices

• One agent, one purpose. Avoid creating a single profile that tries to do everything. Specialized agents with focused instructions perform better than generalist ones.
• Version your instructions. Store your mainTask text in your codebase or a configuration file so you can track changes over time.
• Test iteratively. Use the chat API or Dashboard to test your instructions, then refine based on actual responses.
• Use persona wisely. The persona field subtly influences tone and style. A short, clear description works better than a lengthy character backstory.
• Limit commands to what is implemented. Only list commands in availableCommands that your local runtime actually handles. Listing unimplemented commands leads to errors at runtime.
• Leverage the Dashboard for exploration. Use the Dashboard to experiment with settings, then codify the final configuration in your Python scripts for reproducibility.

Next Steps

Now that your agent is configured, explore these related topics:

• Tools — Define, register, and execute tools with a full arithmetic demo.
• Command Parsing — Define command templates and wire up handlers.
• Agent Connection — Expose your agent over the HTTP REST bridge.
• Context System — Ground your agent in domain-specific knowledge.