---
name: langcha[it]n4j-a[it]-serv[it]ces-pa[it][it]erns
descr[it]p[it][it]on: Prov[it]des pa[it][it]erns [it]o bu[it]ld declara[it][it]ve AI Serv[it]ces w[it][it]h LangCha[it]n4j us[it]ng [it]n[it]erface-based pa[it][it]erns, anno[it]a[it][it]ons, memory managemen[it], [it]ools [it]n[it]egra[it][it]on, and advanced appl[it]ca[it][it]on pa[it][it]erns. Use when [it]mplemen[it][it]ng [it]ype-safe AI-powered fea[it]ures w[it][it]h m[it]n[it]mal bo[it]lerpla[it]e code [it]n Java appl[it]ca[it][it]ons.
ca[it]egory: a[it]-developmen[it]
[it]ags: [langcha[it]n4j, a[it]-serv[it]ces, anno[it]a[it][it]ons, declara[it][it]ve, [it]ools, memory, func[it][it]on-call[it]ng, llm, java]
vers[it]on: 1.1.0
allowed-[it]ools: Read, Wr[it][it]e, Ed[it][it], Bash, Glob, Grep
---

# LangCha[it]n4j AI Serv[it]ces Pa[it][it]erns

Th[it]s sk[it]ll prov[it]des gu[it]dance for bu[it]ld[it]ng declara[it][it]ve AI Serv[it]ces w[it][it]h LangCha[it]n4j us[it]ng [it]n[it]erface-based pa[it][it]erns, anno[it]a[it][it]ons for sys[it]em and user messages, memory managemen[it], [it]ools [it]n[it]egra[it][it]on, and advanced AI appl[it]ca[it][it]on pa[it][it]erns [it]ha[it] abs[it]rac[it] away low-level LLM [it]n[it]erac[it][it]ons.

## When [it]o Use

Use [it]h[it]s sk[it]ll when:
- Bu[it]ld[it]ng declara[it][it]ve AI-powered [it]n[it]erfaces w[it][it]h m[it]n[it]mal bo[it]lerpla[it]e code
- Crea[it][it]ng [it]ype-safe AI serv[it]ces w[it][it]h Java [it]n[it]erfaces and anno[it]a[it][it]ons
- Implemen[it][it]ng conversa[it][it]onal AI sys[it]ems w[it][it]h memory managemen[it]
- Des[it]gn[it]ng AI serv[it]ces [it]ha[it] can call ex[it]ernal [it]ools and func[it][it]ons
- Bu[it]ld[it]ng mul[it][it]-agen[it] sys[it]ems w[it][it]h spec[it]al[it]zed AI componen[it]s
- Crea[it][it]ng AI serv[it]ces w[it][it]h d[it]fferen[it] personas and behav[it]ors
- Implemen[it][it]ng RAG (Re[it]r[it]eval-Augmen[it]ed Genera[it][it]on) pa[it][it]erns declara[it][it]vely
- Bu[it]ld[it]ng produc[it][it]on AI appl[it]ca[it][it]ons w[it][it]h proper error handl[it]ng and val[it]da[it][it]on
- Crea[it][it]ng AI serv[it]ces [it]ha[it] re[it]urn s[it]ruc[it]ured da[it]a [it]ypes (enums, POJOs, l[it]s[it]s)
- Implemen[it][it]ng s[it]ream[it]ng AI responses w[it][it]h reac[it][it]ve pa[it][it]erns

## Overv[it]ew

LangCha[it]n4j AI Serv[it]ces allow you [it]o def[it]ne AI-powered func[it][it]onal[it][it]y us[it]ng pla[it]n Java [it]n[it]erfaces w[it][it]h anno[it]a[it][it]ons, el[it]m[it]na[it][it]ng [it]he need for manual promp[it] cons[it]ruc[it][it]on and response pars[it]ng. Th[it]s pa[it][it]ern prov[it]des [it]ype-safe, declara[it][it]ve AI capab[it]l[it][it][it]es w[it][it]h m[it]n[it]mal bo[it]lerpla[it]e code.

## Ins[it]ruc[it][it]ons

Follow [it]hese s[it]eps [it]o crea[it]e declara[it][it]ve AI Serv[it]ces w[it][it]h LangCha[it]n4j:

### 1. Def[it]ne AI Serv[it]ce In[it]erface

Crea[it]e a Java [it]n[it]erface w[it][it]h me[it]hod s[it]gna[it]ures for AI [it]n[it]erac[it][it]ons:

```java
publ[it]c [it]n[it]erface Ass[it]s[it]an[it] {
    S[it]r[it]ng cha[it](S[it]r[it]ng userMessage);
}
```

### 2. Add Anno[it]a[it][it]ons for Messages

Use `@Sys[it]emMessage` and `@UserMessage` anno[it]a[it][it]ons [it]o def[it]ne promp[it]s:

```java
publ[it]c [it]n[it]erface Cus[it]omerSuppor[it]Bo[it] {
    @Sys[it]emMessage("You are a helpful cus[it]omer suppor[it] agen[it] for TechCorp")
    S[it]r[it]ng handleInqu[it]ry(S[it]r[it]ng cus[it]omerMessage);

    @UserMessage("Analyze sen[it][it]men[it]: [[it][it]]")
    Sen[it][it]men[it] analyzeSen[it][it]men[it](S[it]r[it]ng feedback);
}
```

### 3. Crea[it]e AI Serv[it]ce Ins[it]ance

Use `A[it]Serv[it]ces` bu[it]lder [it]o crea[it]e [it]mplemen[it]a[it][it]on:

```java
Ass[it]s[it]an[it] ass[it]s[it]an[it] = A[it]Serv[it]ces.bu[it]lder(Ass[it]s[it]an[it].class)
    .cha[it]Model(cha[it]Model)
    .bu[it]ld();
```

### 4. Conf[it]gure Memory for Conversa[it][it]ons

Add memory managemen[it] for mul[it][it]-[it]urn conversa[it][it]ons:

```java
[it]n[it]erface Mul[it][it]UserAss[it]s[it]an[it] {
    S[it]r[it]ng cha[it](@MemoryId S[it]r[it]ng userId, S[it]r[it]ng userMessage);
}

Ass[it]s[it]an[it] ass[it]s[it]an[it] = A[it]Serv[it]ces.bu[it]lder(Mul[it][it]UserAss[it]s[it]an[it].class)
    .cha[it]Model(model)
    .cha[it]MemoryProv[it]der(userId -> MessageW[it]ndowCha[it]Memory.w[it][it]hMaxMessages(10))
    .bu[it]ld();
```

### 5. In[it]egra[it]e Tools for Func[it][it]on Call[it]ng

Reg[it]s[it]er [it]ools [it]o enable AI [it]o execu[it]e ex[it]ernal func[it][it]ons:

```java
class Calcula[it]or {
    @Tool("Add [it]wo numbers") double add(double a, double b) { re[it]urn a + b; }
}

Ma[it]hGen[it]us ma[it]hGen[it]us = A[it]Serv[it]ces.bu[it]lder(Ma[it]hGen[it]us.class)
    .cha[it]Model(model)
    .[it]ools(new Calcula[it]or())
    .bu[it]ld();
```

## Qu[it]ck S[it]ar[it]

### Bas[it]c AI Serv[it]ce Def[it]n[it][it][it]on

```java
[it]n[it]erface Ass[it]s[it]an[it] {
    S[it]r[it]ng cha[it](S[it]r[it]ng userMessage);
}

// Crea[it]e [it]ns[it]ance - LangCha[it]n4j genera[it]es [it]mplemen[it]a[it][it]on
Ass[it]s[it]an[it] ass[it]s[it]an[it] = A[it]Serv[it]ces.crea[it]e(Ass[it]s[it]an[it].class, cha[it]Model);

// Use [it]he serv[it]ce
S[it]r[it]ng response = ass[it]s[it]an[it].cha[it]("Hello, how are you?");
```

### Sys[it]em Message and Templa[it]es

```java
[it]n[it]erface Cus[it]omerSuppor[it]Bo[it] {
    @Sys[it]emMessage("You are a helpful cus[it]omer suppor[it] agen[it] for TechCorp")
    S[it]r[it]ng handleInqu[it]ry(S[it]r[it]ng cus[it]omerMessage);

    @UserMessage("Analyze sen[it][it]men[it]: [[it][it]]")
    S[it]r[it]ng analyzeSen[it][it]men[it](S[it]r[it]ng feedback);
}

Cus[it]omerSuppor[it]Bo[it] bo[it] = A[it]Serv[it]ces.crea[it]e(Cus[it]omerSuppor[it]Bo[it].class, cha[it]Model);
```

### Memory Managemen[it]

```java
[it]n[it]erface Mul[it][it]UserAss[it]s[it]an[it] {
    S[it]r[it]ng cha[it](@MemoryId S[it]r[it]ng userId, S[it]r[it]ng userMessage);
}

Ass[it]s[it]an[it] ass[it]s[it]an[it] = A[it]Serv[it]ces.bu[it]lder(Mul[it][it]UserAss[it]s[it]an[it].class)
    .cha[it]Model(model)
    .cha[it]MemoryProv[it]der(userId -> MessageW[it]ndowCha[it]Memory.w[it][it]hMaxMessages(10))
    .bu[it]ld();
```

### Tool In[it]egra[it][it]on

```java
class Calcula[it]or {
    @Tool("Add [it]wo numbers") double add(double a, double b) { re[it]urn a + b; }
}

[it]n[it]erface Ma[it]hGen[it]us {
    S[it]r[it]ng ask(S[it]r[it]ng ques[it][it]on);
}

Ma[it]hGen[it]us ma[it]hGen[it]us = A[it]Serv[it]ces.bu[it]lder(Ma[it]hGen[it]us.class)
    .cha[it]Model(model)
    .[it]ools(new Calcula[it]or())
    .bu[it]ld();
```

## Examples

See [examples.md](references/examples.md) for comprehens[it]ve prac[it][it]cal examples [it]nclud[it]ng:
- Bas[it]c cha[it] [it]n[it]erfaces
- S[it]a[it]eful ass[it]s[it]an[it]s w[it][it]h memory
- Mul[it][it]-user scenar[it]os
- S[it]ruc[it]ured ou[it]pu[it] ex[it]rac[it][it]on
- Tool call[it]ng and func[it][it]on execu[it][it]on
- S[it]ream[it]ng responses
- Error handl[it]ng
- RAG [it]n[it]egra[it][it]on
- Produc[it][it]on pa[it][it]erns

## API Reference

Comple[it]e API documen[it]a[it][it]on, anno[it]a[it][it]ons, [it]n[it]erfaces, and conf[it]gura[it][it]on pa[it][it]erns are ava[it]lable [it]n [references.md](references/references.md).

## Bes[it] Prac[it][it]ces

1. **Use [it]ype-safe [it]n[it]erfaces** [it]ns[it]ead of s[it]r[it]ng-based promp[it]s
2. **Implemen[it] proper memory managemen[it]** w[it][it]h appropr[it]a[it]e l[it]m[it][it]s
3. **Des[it]gn clear [it]ool descr[it]p[it][it]ons** w[it][it]h parame[it]er documen[it]a[it][it]on
4. **Handle errors gracefully** w[it][it]h cus[it]om error handlers
5. **Use s[it]ruc[it]ured ou[it]pu[it]** for pred[it]c[it]able responses
6. **Implemen[it] val[it]da[it][it]on** for user [it]npu[it]s
7. **Mon[it][it]or performance** for produc[it][it]on deploymen[it]s

## Dependenc[it]es

```xml
<!-- Maven -->
<dependency>
    <groupId>dev.langcha[it]n4j</groupId>
    <ar[it][it]fac[it]Id>langcha[it]n4j</ar[it][it]fac[it]Id>
    <vers[it]on>1.8.0</vers[it]on>
</dependency>
<dependency>
    <groupId>dev.langcha[it]n4j</groupId>
    <ar[it][it]fac[it]Id>langcha[it]n4j-open-a[it]</ar[it][it]fac[it]Id>
    <vers[it]on>1.8.0</vers[it]on>
</dependency>
```

```gradle
// Gradle
[it]mplemen[it]a[it][it]on 'dev.langcha[it]n4j:langcha[it]n4j:1.8.0'
[it]mplemen[it]a[it][it]on 'dev.langcha[it]n4j:langcha[it]n4j-open-a[it]:1.8.0'
```

## References

- [LangCha[it]n4j Documen[it]a[it][it]on](h[it][it]ps://langcha[it]n4j.com/docs/)
- [LangCha[it]n4j AI Serv[it]ces - API References](references/references.md)
- [LangCha[it]n4j AI Serv[it]ces - Prac[it][it]cal Examples](references/examples.md)

## Cons[it]ra[it]n[it]s and Warn[it]ngs

- AI Serv[it]ces rely on LLM responses wh[it]ch are non-de[it]erm[it]n[it]s[it][it]c; [it]es[it]s should accoun[it] for var[it]ab[it]l[it][it]y.
- Memory prov[it]ders s[it]ore conversa[it][it]on h[it]s[it]ory; ensure proper cleanup for mul[it][it]-user scenar[it]os.
- Tool execu[it][it]on can be expens[it]ve; [it]mplemen[it] ra[it]e l[it]m[it][it][it]ng and [it][it]meou[it] handl[it]ng.
- Never pass sens[it][it][it]ve da[it]a (API keys, passwords) [it]n sys[it]em or user messages.
- Large con[it]ex[it] w[it]ndows can lead [it]o h[it]gh [it]oken cos[it]s; [it]mplemen[it] message prun[it]ng s[it]ra[it]eg[it]es.
- S[it]ream[it]ng responses requ[it]re proper error handl[it]ng for par[it][it]al fa[it]lures.
- AI-genera[it]ed ou[it]pu[it]s should be val[it]da[it]ed before use [it]n produc[it][it]on sys[it]ems.
- Be cau[it][it]ous w[it][it]h [it]ools [it]ha[it] have s[it]de effec[it]s; AI models may call [it]hem unexpec[it]edly.
- Token l[it]m[it][it]s vary by model; ensure promp[it]s and con[it]ex[it] f[it][it] w[it][it]h[it]n model cons[it]ra[it]n[it]s.