Event-Driven LLM Integration

Learn how AgentML structures LLM calls as event-driven operations for reliability and clarity.

Event-Driven LLM Calls

AgentML embraces an event-driven integration pattern for LLMs. Rather than treating an LLM call as a monolithic black box, you structure it in terms of events that must conform to predefined schemas.

Key Principles

Prompt Minimalism

Because the runtime already provides context (state, possible events) to the LLM, you keep the user prompt or system instruction minimal and focused on the task at hand.

Schema-Adherence

The LLM's output is immediately checked against the expected schema. If it fails, the agent can handle that with a fallback transition.

Iterative Refinement

You can chain states such that each LLM call is focused. One state parses intent, another fills in details, another confirms.

Example: Intent Classification

In an intent-classification state, the system context already lists the intents and schemas, so your prompt might just be:

"Classify the user's request into one of the intents."

The LLM then returns an event like intent.flight with the required data.

Internal vs External Events

Not all events must come from the LLM. AgentML lets you mix internal events (like timeouts, or events you raise from script) with external events (LLM or user inputs).

Internal events: Raised by the agent itself using <raise>
External events: Come from LLM outputs, HTTP requests, or other I/O processors

The key is the uniform event handling – everything that causes state changes is an event, no matter the source.

Best Practices

Prompt Engineering Tip

Keep prompts minimal and focused. Rely on the runtime snapshot and schemas to provide context. Instead of lengthy instructions, just say "Classify the user's request" or "What is the best action?" – everything else the LLM needs is already in context.

Give Clear Instructions

When you do write a prompt, be explicit. If the LLM should output a certain event, mention the event by name in the prompt or in the schema description.

Provide Examples in Descriptions

Include natural language descriptions in your schemas like "e.g., if user asks for a flight, output should include 'category': 'flight' and an appropriate 'action' like 'search' or 'book'".

Next Steps

Now that you understand the core concepts, explore the architecture of AgentML to see how everything fits together.

Architecture →