Agents

What are Agents?

Agents are custom AI assistants that you can configure to behave in specific ways. Unlike the default yeos assistant, agents have their own personality, instructions, and settings.

When you create an agent, you define its name, description, and a system prompt that tells the agent how to behave. You can also choose which tools it can use and which documents it has access to.

Agents let you create specialized assistants for different use cases. For example, you might create a Hiring Assistant that only knows about job postings and candidate information, or a Legal Assistant that focuses on contracts and compliance documents.

Automatic Agent Selection

You do not always have to pick an agent yourself. When you ask a question without choosing one, yeos compares your question against the names and descriptions of your active agents and routes it to the best match.

The selection comes with a confidence score, and the chosen agent is shown at the start of the run — so you always see who answered and can switch to a specific agent if the automatic pick was not what you wanted.

Clear agent names and descriptions make automatic selection noticeably more accurate.

How Agents Work Through Complex Requests

Simple questions get direct answers. For complex requests, the agent breaks the work into a plan of dependent steps and works through them, gathering evidence as it goes.

You can follow along: the plan summary and each tool call appear in the run view while the agent works, so the path from request to answer stays visible.

If your request is ambiguous and the available evidence cannot resolve it, the agent asks you one focused clarification question instead of guessing.

Key Concepts

System Prompt

The system prompt is the core instruction that defines how an agent behaves. Think of it as the agent's personality and guidelines. A good prompt tells the agent who it is, what it should do, and what rules it should follow.

AI-Assisted Prompt Improvement

You do not have to write the perfect prompt yourself. From the agent settings, let yeos rewrite your system prompt: it proposes an improved version and shows you a side-by-side diff, so you review every change before accepting it. Your original prompt is never replaced without your confirmation.

Example System Prompts
Hiring Assistant

"You are a helpful hiring assistant. Your role is to answer questions about open positions, company culture, and the application process. Be friendly and professional. Only discuss topics related to careers at our company."

Legal Assistant

"You are a legal document assistant. You help users find information in contracts, policies, and legal documents. Always cite the source document and page number. Do not provide legal advice."

Customer Support

"You are a customer support assistant. Help users find answers to their questions using our knowledge base. Be empathetic and patient. If you cannot find the answer, suggest contacting human support."

Temperature

Temperature controls how creative or random the agent's responses are. Lower values make responses more focused and predictable. Higher values allow more creativity and variation.

Low (0.0 – 0.3)

Use low temperature for factual questions, document search, and consistent responses. The agent will stick closely to the information in your documents.

Medium (0.4 – 0.7)

Use medium temperature for general assistance. The agent will provide helpful answers while maintaining accuracy.

High (0.8 – 2.0)

Use high temperature for brainstorming, creative tasks, or when you want more varied responses. The agent may take more liberties with the information.

Tool Access

Agents can use different tools depending on their configuration. Tools determine what the agent can do when answering questions.

Search Knowledge Base

The agent can search through your uploaded documents.

Fetch Full Section

The agent can retrieve surrounding context from documents.

Web Fetch

The agent can fetch specific web pages for additional information (if enabled for your organization).

Document Access

You can control which documents an agent has access to. This is useful when you want different agents to focus on different knowledge bases.

All Documents

The agent can search through all documents uploaded to the organization.

Selected Documents

The agent can only search through specific documents you choose. Use this to create highly focused assistants.

Creating an Agent

Agents can be created by organization owners and admins from the AI Agents section in your organization settings.

1

Name and Description

Give your agent a clear name and a brief description of what it does. The name will be visible to your team, so make it descriptive.

2

Write the System Prompt

Define how the agent should behave using the system prompt. Include information about its role, rules, and any constraints. Be specific and clear.

3

Choose Tools

Select which tools the agent can use. At minimum, you should enable Search Knowledge Base. Add other tools based on the agent's needs.

4

Set Document Access

Choose whether the agent can access all documents or only specific ones. For specialized assistants, limiting document access can improve relevance.

5

Adjust Settings

Fine-tune the temperature setting based on how creative or focused you want the agent to be. The default values work well for most use cases.

Running Agents Automatically

Agents can run without a person starting a chat. Use schedules for repeatable work, and webhook triggers when an external system should start an agent run.

Repeated runs with schedules

Create a schedule in the agent detail page when an agent should ask the same question on a recurring cadence, such as a daily summary, weekly report, or monthly compliance check.

Open Agents, select an agent, go to Scheduled Runs, and click Create schedule.

Enter a name and the question the agent should answer, then choose Daily, Weekly, Monthly, or Custom cron.

Set time, timezone, and status. Use the run history table to review status, linked conversations, request IDs, and errors.

UI setup
1. Agents → select agent
2. Scheduled Runs → Create schedule
3. Add Name and Question
4. Choose recurrence, time, timezone, and status
5. Save

Triggered runs with webhooks

Create a webhook trigger from the agent detail page when an external event should start an agent, for example a ticket update, form submission, deployment event, or CRM change.

Open Agents, select an agent, go to Webhook Triggers, and click Create webhook. Enter a name and choose Active or Paused.

After saving, copy the generated secret immediately. It is shown only once. Send it either as the X-Yeos-Webhook-Secret header or, for systems that cannot set custom headers, as a ?secret= query parameter on the Invoke URL.

Copy the Invoke URL into the external system. When that system sends JSON with the secret (header or query parameter), yeos passes the JSON to the agent as run context.

UI setup
1. Agents → select agent
2. Webhook Triggers → Create webhook
3. Add Name and Status
4. Save and copy the secret
5. Copy Invoke URL into the external system

Permissions and limits

Creating or changing schedules and webhook triggers requires organization admin access. Webhook invocations must use JSON and the trigger secret, and oversized requests are rejected before they are queued.

Managing Agents

Organization owners and admins can create, edit, and delete agents. Regular team members can view the list of available agents.

Editing Agents

You can update any agent configuration at any time. Changes take effect immediately for new conversations.

Deactivating Agents

If you do not want to delete an agent but also do not want it used, you can set its status to inactive. Inactive agents are hidden from the agent list but can be reactivated later.

Sub-agent Delegation

Agents can also be invoked from within another agent run when the request clearly points to a specialist.

Inferred by mention

If a prompt contains @AgentName or @"Agent Name", yeos tries to resolve that mention to an active agent with that exact name.

Called explicitly

An agent can use the delegation tool directly and pass one or more focused jobs to sub-agents.

Resolution behavior

When a mention matches exactly one active agent, yeos strips the mention from the task, sends the remaining request to that sub-agent, and merges the result back into the final answer. If a mention does not resolve uniquely, the request continues through the normal flow.

Example prompts

@LegalAssistant review this contract termination clause

Compare these vendor terms and ask @"HR Policy Assistant" about employee handbook constraints

Example explicit delegation payload
{
  "jobs": [
    {
      "subagent_id": "agent-uuid",
      "task": "Review the liability section in this agreement"
    }
  ]
}
Current limits

Delegation only works for active agents.

Name-based delegation works best when agent names are unique.

Sub-agents do not keep delegating indefinitely. yeos limits delegation depth to avoid recursive chains.

Best Practices

Clear Naming

Use descriptive names that clearly indicate the agent's purpose. For example, "HR Policy Assistant" is better than "Assistant 1".

Specific Prompts

The more specific your system prompt, the better the agent's responses will be. Include examples of good and bad responses when relevant.

Limited Scope

It is often better to create multiple specialized agents than one general-purpose agent. A focused agent will provide more accurate and relevant answers.

Use unique names

Mention-based delegation depends on matching an active agent name. Distinct names make inference more reliable.

Test Thoroughly

After creating an agent, test it with various questions to ensure it behaves as expected. Adjust the prompt and settings based on the results.

Common Questions

What is the difference between an agent and the default assistant?

The default assistant is a general-purpose AI that can answer questions about any topic using your documents. Agents are customizable assistants with their own personality, instructions, and document access. Use agents when you need specialized behavior.

Can I use multiple agents in one conversation?

Yes, in a limited way. A conversation runs with one main agent, but that agent can delegate focused work to sub-agents when they are mentioned explicitly or when delegation is triggered internally. Separate conversations are still the clearest option when you want to compare full agent behaviors end-to-end.

How do I improve an agent's accuracy?

Start by refining the system prompt to be more specific. You can also limit document access to only relevant files, and enable tools like Fetch Full Section to give the agent more context.

Can agents access the internet?

Only if Web Fetch is enabled for your organization and you have enabled it for the specific agent. Even then, the agent will avoid domains on your blocklist.

How many agents can I create?

The number of agents you can create depends on your plan. Check your plan details or contact support for information about agent limits.

Can team members create their own agents?

Only organization owners and admins can create agents. Regular team members can view and use existing agents but cannot modify them.

How do I call a specific sub-agent?

Mention the agent by name in your prompt using @AgentName or @"Agent Name". If the name matches one active agent, yeos routes that part of the request to the mentioned agent.

What happens if two agents have similar names?

yeos only infers a sub-agent when the name resolves uniquely. If the match is ambiguous, the system falls back to the normal flow instead of guessing.