An agent family compiled onto the graph runtime: a model/tool loop whose conversations are threads of a org.llm4s.agent.graph.GraphRuntime. Built with Agent.builder.
for
agent <- Agent.builder("assistant", client).withTools(registry).build()
first <- agent.run("What is the weather in Paris?")
second <- agent.continueConversation(first, "And in London?")
yield second.answer
Every run is a turn on a thread. A run that reaches the graph's end is Right with status Completed or StepLimitReached; one a guardrail blocks is Right with Blocked, the blocked turn absent from the thread; one that parks on approvals, questions or breakpoints is Right with Suspended, and continues with resume. Anything else is Left: a blank query and the runtime's refusals (ThreadBusy, TenantMismatch, IncompleteRun, PendingInterrupts, ...) leave the thread unchanged, as does another middleware's beforeAgent or afterAgent failure (a Block without a guardrail; a blank query or answer from a hook is one), which also ends the run; a failed run - a provider error, a tool's Fatal, a model or tool wrapper's failure, cancellation, a deadline - leaves the thread for recover.
Attributes
- Companion
- object
- Graph
-
- Supertypes
-
class Objecttrait Matchableclass Any
Members list
Value members
Concrete methods
The next turn on previous's thread: only its threadId is read.
The next turn on previous's thread: only its threadId is read.
Attributes
Removes threadId - its history, usage and event log - from the agent's runtime, so that its id names a new thread again. Threads are kept until forgotten, one-shot runs included. Refused, with nothing removed, for a thread whose run is active in this runtime (GraphError.ThreadBusy) or that belongs to another tenant than config's (GraphError.TenantMismatch). Forgetting an unknown thread is Right(()).
Removes threadId - its history, usage and event log - from the agent's runtime, so that its id names a new thread again. Threads are kept until forgotten, one-shot runs included. Refused, with nothing removed, for a thread whose run is active in this runtime (GraphError.ThreadBusy) or that belongs to another tenant than config's (GraphError.TenantMismatch). Forgetting an unknown thread is Right(()).
Attributes
Continues threadId's failed or interrupted run, re-running only failed or unstarted work. Interrupting the calling thread cancels the turn, as for run.
Continues threadId's failed or interrupted run, re-running only failed or unstarted work. Interrupting the calling thread cancels the turn, as for run.
Attributes
Answers some of threadId's pending approvals, questions and breakpoints - built with AgentResult.approve, AgentResult.reject, AgentResult.edit, AgentResult.reply and AgentResult.proceed - and continues. Unanswered ones stay pending. Interrupting the calling thread cancels the turn, as for run.
Answers some of threadId's pending approvals, questions and breakpoints - built with AgentResult.approve, AgentResult.reject, AgentResult.edit, AgentResult.reply and AgentResult.proceed - and continues. Unanswered ones stay pending. Interrupting the calling thread cancels the turn, as for run.
Attributes
One turn on a new thread with a random id. The thread stays in the agent's runtime - on the default in-memory runtime, in memory - until forget removes it; a caller that does not continue the conversation should forget result.threadId when done.
One turn on a new thread with a random id. The thread stays in the agent's runtime - on the default in-memory runtime, in memory - until forget removes it; a caller that does not continue the conversation should forget result.threadId when done.
A Left carries no thread id, so nothing could recover or forget the thread: a turn that fails
- cancelled by an interrupt included - is forgotten here once it has ended. A cancelled turn whose provider ignores its interrupt past AgentRun.Drain has not ended, and its thread is left in the runtime (logged at WARN). For a turn to recover, name its thread:
run(threadId, query).
Attributes
One turn on threadId: a new thread is created, seeded with history; on a completed or blocked thread it is the next turn, and history must be empty. history holds no system message and must be a valid conversation. A blank query, a history refused for its content, or one given for a thread that exists, is a ValidationError; the runtime's refusals - GraphError.TenantMismatch for another tenant's thread, ThreadBusy, IncompleteRun, PendingInterrupts - come back unchanged. Either way no thread is created and an existing one is unchanged.
One turn on threadId: a new thread is created, seeded with history; on a completed or blocked thread it is the next turn, and history must be empty. history holds no system message and must be a valid conversation. A blank query, a history refused for its content, or one given for a thread that exists, is a ValidationError; the runtime's refusals - GraphError.TenantMismatch for another tenant's thread, ThreadBusy, IncompleteRun, PendingInterrupts - come back unchanged. Either way no thread is created and an existing one is unchanged.
Interrupting the calling thread cancels the turn: run returns Left(CancelledError) with the interrupt flag still set, once the turn has ended, leaving the thread for recover. It waits up to 5 seconds (AgentRun.Drain) for the turn to end; with tracing, delivering the ended turn's last trace events can add to that. A turn whose provider ignores its interrupt for longer is logged at WARN and left to end on its own, and until it does the thread is GraphError.ThreadBusy. With tracing, the cancelled turn's trace is complete when run returns. A turn that had already begun committing its outcome when the interrupt came cannot be cancelled: run returns that outcome - Completed, Suspended, ... - with the interrupt flag still set. A caller already interrupted gets Left(CancelledError) without a turn being started. To keep a turn running past an interrupt, use start and await the AgentRun.
Attributes
One turn on threadId, new, completed or blocked.
One turn on threadId, new, completed or blocked.
Attributes
One turn on threadId, new, completed or blocked, with the default config.
One turn on threadId, new, completed or blocked, with the default config.
Attributes
first on a new thread, then each of followUps on it, stopping at the first turn whose status is not Completed; returns the last turn's result. Each turn is its own run: the first runs with config, each follow-up with config and a fresh RunId. A Left carries no thread id, so a conversation whose turn fails - cancelled by an interrupt included - is forgotten once that turn has ended, as for the one-shot run.
first on a new thread, then each of followUps on it, stopping at the first turn whose status is not Completed; returns the last turn's result. Each turn is its own run: the first runs with config, each follow-up with config and a fresh RunId. A Left carries no thread id, so a conversation whose turn fails - cancelled by an interrupt included - is forgotten once that turn has ended, as for the one-shot run.
Attributes
start, with listener subscribed before the turn begins, so it receives every event of the turn - live text deltas included - until the turn's terminal event, or a Disconnected if it fell behind or threw; the subscription then ends itself. A turn that ends without a terminal event (a crash, or a failed commit) ends it as soon as it has delivered the turn's last event, at the run's end-of-run barrier. A refused start (a blank query, a busy thread, ...) is Left, and the listener hears nothing. The run's AgentRun.await returns only once listener has returned from the turn's last event.
start, with listener subscribed before the turn begins, so it receives every event of the turn - live text deltas included - until the turn's terminal event, or a Disconnected if it fell behind or threw; the subscription then ends itself. A turn that ends without a terminal event (a crash, or a failed commit) ends it as soon as it has delivered the turn's last event, at the run's end-of-run barrier. A refused start (a blank query, a busy thread, ...) is Left, and the listener hears nothing. The run's AgentRun.await returns only once listener has returned from the turn's last event.
Attributes
startRecover with listener subscribed first; see stream.
startResume with listener subscribed first; see stream.